Mailtrap

Mailtrap

This connector uses the Mailtrap API for one Mailtrap account: sending transactional and bulk email (Email API), testing email in Email Sandbox, sending domains, suppressions, sending stats and email logs, email templates, and Email Marketing contacts, lists and campaigns. Mailtrap serves these areas from different hosts and the connector picks the right one per tool: https://mailtrap.io for management and reports, https://send.api.mailtrap.io for transactional sending, https://bulk.api.mailtrap.io for the Bulk stream and https://sandbox.api.mailtrap.io for test sends into a sandbox.

Setup (3 minutes)

1. In Mailtrap open Settings, API Tokens (https://mailtrap.io/api-tokens) and create a token. Give it access to the sending domains (for sending, stats, logs and suppressions), the sandboxes or projects (for Email Sandbox) and, if you use it, Email Marketing. Admin access is needed to change suppressions.
2. Paste it into MAILTRAP_API_TOKEN. It is sent as Authorization: Bearer <token> and does not expire until you reset it.
3. Run mailtrap_list_accounts to check the token. A token belongs to one account and every call works on that account, so no account id is needed.
4. Live sending needs a verified sending domain (mailtrap_list_sending_domains); Email Sandbox works without one.

Sending email

• mailtrap_send_email sends one transactional email, mailtrap_send_batch_emails up to 500 different ones in one call. Marketing and other bulk mail belongs on the Bulk stream: mailtrap_send_bulk_email and mailtrap_send_bulk_batch_emails.
• Content is text, html or both, or a stored template: pass template_uuid (the uuid from mailtrap_list_templates, not the numeric id) with template_variables, and leave subject, text, html and category out.
• from_email must be on a verified sending domain. to, cc and bcc are lists of {"email", "name"}. Attachments are Base64 in content.
• Sending is real. Before any send, batch, bulk send or campaign start, show the user the recipients, sender, subject and content and wait for a clear yes. To try a message out first, send it with mailtrap_send_sandbox_email and look at it in the sandbox.
• A send answers message_ids, one per recipient; follow them with mailtrap_get_email_log. Batch calls answer 200 even when single messages fail: check success and errors of each entry in responses.

Email Sandbox (testing)

• Find sandboxes with mailtrap_list_sandboxes or by project with mailtrap_list_sandbox_projects; mailtrap_get_sandbox shows one, mailtrap_create_sandbox adds one to a project.
• Send test mail with mailtrap_send_sandbox_email: it is caught in the sandbox and never delivered.
• Inspect: mailtrap_list_sandbox_messages, mailtrap_get_sandbox_message, mailtrap_get_sandbox_message_body (txt, html, htmlsource or raw), mailtrap_get_sandbox_message_headers, mailtrap_list_sandbox_attachments, mailtrap_get_sandbox_spam_report (SpamAssassin score) and mailtrap_get_sandbox_html_analysis (email client support).
• mailtrap_clean_sandbox deletes every message in a sandbox; confirm first.

Domains and deliverability

• mailtrap_list_sending_domains, mailtrap_get_sending_domain (DNS records and their verification), mailtrap_create_sending_domain, mailtrap_send_domain_setup_instructions (emails the DNS steps to whoever manages DNS).
• Suppressed addresses get no mail: mailtrap_list_suppressions, mailtrap_create_suppression, mailtrap_delete_suppression (only when the recipient asked for it or the bounce is resolved).
• What happened to an email: mailtrap_list_email_logs (filter by recipient, status, events, category, sent time), then mailtrap_get_email_log for its delivery, open, click and bounce events.
• Totals: mailtrap_get_sending_stats for a date range, mailtrap_get_sending_stats_grouped split by domain, category, mailbox provider or day. Usage against the plan: mailtrap_get_billing_usage.

Templates: mailtrap_list_templates, mailtrap_get_template, mailtrap_create_template, mailtrap_update_template. Variables use Handlebars, e.g. {{user_name}}.

Email Marketing

• Contacts: mailtrap_list_contacts, mailtrap_get_contact and mailtrap_update_contact (by id or email), mailtrap_create_contact, mailtrap_delete_contact, custom events with mailtrap_create_contact_event. Many contacts at once: mailtrap_import_contacts, then mailtrap_get_contact_import until it is finished.
• Lists and fields: mailtrap_list_contact_lists, mailtrap_create_contact_list, mailtrap_list_contact_fields (the merge tags used as keys in fields).
• Campaigns: mailtrap_list_campaigns, mailtrap_get_campaign, mailtrap_get_campaign_stats. Build one with mailtrap_create_campaign (always a draft) and mailtrap_update_campaign, then mailtrap_schedule_campaign or mailtrap_start_campaign; mailtrap_cancel_campaign returns a scheduled campaign to draft. Scheduling and starting email the whole audience: confirm first.
• Add only contacts who agreed to receive email. To stop mailing someone, unsubscribe them (unsubscribed: true) rather than deleting them.

Reading the answers: ids of domains, sandboxes, messages, templates, lists and campaigns are integers; contacts, suppressions and email log messages use UUIDs. Times are ISO 8601 in UTC. Stats rates are fractions (0.25 = 25%); stats dates are YYYY-MM-DD. Sandbox and template lists leave out SMTP credentials and bodies.

Paging

• Contacts: pass pagination.next_token as token; stop when it is null. Campaigns: token is a page number taken from pagination.next_token.
• Email logs: pass next_page_cursor as search_after. Suppressions: pass the id of the last item as last_id (1000 per page). Sandbox messages: 30 per page, use page or the last message id as last_id.

Limits: 150 requests per 10 seconds per token; Contacts 200 per minute, Stats and Suppressions 10 per minute, listing email logs 60 per minute per account. A send takes up to 1000 recipients, a batch up to 500 messages and 50 MB.

Errors: 401 Incorrect API token (wrong token, or no access to that domain or sandbox), 403 missing permission, 404 unknown id, 422 invalid input with the reason in errors (e.g. sender not on a verified domain, campaign not in draft), 429 rate limit.

Switched off at install: mailtrap_delete_suppression, mailtrap_clean_sandbox and mailtrap_delete_contact; they cannot be undone, so an admin switches them on when the team needs them.