Guide
Migrate from Mailtrap
Move from Mailtrap Email Sending to Emailit. Map streams, tokens and sub-accounts, convert API calls and Handlebars templates, swap SMTP, and move webhooks, suppressions and contacts.
This guide maps Mailtrap Email Sending concepts, API calls, webhooks, suppressions, templates and contacts to their Emailit equivalents. Read Migrate to Emailit first for the overall order and how to run both providers in parallel.
Concepts
| Mailtrap | Emailit |
|---|---|
| Organization and sub-accounts | Account and workspaces. Each workspace has its own domains, keys, members and credits. |
| Sending domains | Sending domains |
| Transactional stream | The Email API and SMTP relay |
| Bulk stream | Campaigns, or the API with your own List-Unsubscribe headers |
| API tokens with per-resource permissions | API keys: Full Access, or Sending Only optionally restricted to one domain |
| Demo domain | New workspaces are in sandbox mode and can send to workspace members from your own verified domain. |
| Email Sandbox (testing) | Not available. Keep Mailtrap’s sandbox for testing, or send to workspace members while you develop. |
| Templates | Templates with an alias and versions, rendered with Temple |
| Webhooks per stream | Webhooks per workspace |
| Suppressions per domain and stream | One suppression list per workspace |
| Email logs | Email APIEmails and Email APILogs |
category and custom_variables |
meta |
| Email Marketing: contacts, lists, campaigns, automations | Contacts, audiences, campaigns and automations (beta) |
| Inbound email | Inbound email |
To keep transactional and marketing reputation apart, as Mailtrap’s two streams do, send them from different domains or subdomains, such as mail.acme.com for receipts and news.acme.com for newsletters.
Update your API calls
Mailtrap’s POST /api/send becomes POST /v2/emails. Both take a bearer token and JSON, but Emailit’s addresses are plain strings instead of objects:
curl https://send.api.mailtrap.io/api/send \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@acme.com", "name": "Acme" },
"to": [{ "email": "ada@example.com" }],
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}'curl https://api.emailit.com/v2/emails \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}'| Mailtrap | Emailit |
|---|---|
Authorization: Bearer <token> or Api-Token: <token> |
Authorization: Bearer secret_… |
send.api.mailtrap.io and bulk.api.mailtrap.io |
One host, api.emailit.com |
from: { email, name } |
from: "Name <email>" |
to[], cc[], bcc[] with email and name |
to, cc, bcc as a string or an array of up to 50 each |
reply_to: { email, name } |
reply_to |
subject, text, html, headers |
The same |
attachments[] with content, filename, type, disposition and content_id |
attachments[] with content, filename, content_type and content_id, or a url instead of content |
category |
meta, for example meta: { "category": "password-reset" } |
custom_variables |
meta, returned in webhook events |
template_uuid and template_variables |
template (an alias or ID) and variables |
| Tracking set per domain | Tracking set per domain, or per email with tracking: { "loads": true, "clicks": true } |
POST /api/batch (up to 500 messages) |
Not available. Send one request per message. |
Response with message_ids, one per recipient |
200 with id (em_…), status: "accepted" and, for several recipients, ids with one ID each |
Emailit also supports scheduling with scheduled_at and safe retries with an Idempotency-Key header, which Mailtrap’s send API doesn’t offer. See Send an email.
Switch SMTP settings
| Setting | Mailtrap | Emailit |
|---|---|---|
| Host | live.smtp.mailtrap.io, or bulk.smtp.mailtrap.io for the bulk stream |
smtp.emailit.com |
| Port | 587, 2525 or 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 or 25 (STARTTLS), 465 (TLS) |
| Username | api |
emailit |
| Password | Your Mailtrap API token | Your Emailit API key |
Emailit doesn’t read the X-MT-Category or X-MT-Custom-Variables headers. Remove them, and use the API when you need metadata. See SMTP settings.
Map webhook events
| Mailtrap event | Emailit event |
|---|---|
delivery |
email.delivered |
soft bounce |
email.attempted while Emailit retries, then email.bounced if every retry fails |
bounce |
email.bounced |
reject |
email.suppressed when the address has a recipient suppression |
suspension |
email.held |
spam |
email.complained |
open |
email.loaded |
click |
email.clicked |
unsubscribe |
email.unsubscribed, for campaign email only |
inbound.message_received |
email.received, then fetch the content with GET /emails/{id} |
Emailit also sends email.accepted when the API accepts an email. See Event types.
The request format changes:
- Mailtrap posts an
eventslist of up to 500 events, or JSON Lines. Emailit posts a JSON array of up to 100 events as the request body. - The event name is in
type, and the email is indata.object. Usedata.object.id, theem_ID from the send response, instead ofmessage_id, anddata.object.toinstead ofemail. Yourmetavalues, which replacecategoryandcustom_variables, are indata.object.meta. - For
email.loadedandemail.clicked,data.objectis the load or the click. Usedata.object.email_idfor the email’s ID, anddata.object.email.rcpt_toanddata.object.email.metafor the recipient and yourmetavalues. - Mailtrap’s
Mailtrap-Signatureheader is an HMAC-SHA256 of the raw body. Emailit’sX-Emailit-Signatureis an HMAC-SHA256 of<timestamp>.<raw body>, keyed with yourwhsec_secret, so readX-Emailit-Timestamptoo. See Request signature.
for (const event of req.body) {
const email = event.data.object;
if (event.type === 'email.bounced') markBounced(email.to, email.id);
if (event.type === 'email.complained') unsubscribe(email.to);
}Move suppressions
-
Export your suppressions from Suppressions in Mailtrap, or page through
GET https://mailtrap.io/api/suppressions, which returns up to 1,000 entries per call. -
Build one CSV with the columns
email,type,reason:Mailtrap type Emailit type hard bounce,spam complaint,manual importrecipient, which blocks API, SMTP and campaign sendsunsubscriptionunsubscribe, which stops campaigns but still lets transactional email through. Userecipientfor unsubscribes from the transactional stream.email,type,reason old-address@example.com,recipient,mailtrap hard bounce left@example.com,unsubscribe,mailtrap unsubscription -
In Email APISuppressions, select Import and upload the file. Each file can have up to 10,000 rows and can be at most 8 MB. Duplicates are skipped, so addresses suppressed for several Mailtrap domains or streams are added once.
See Manage suppressions.
Move contacts
If you use Mailtrap Email Marketing, export your contacts from Contacts with More Actions > Export, or with POST https://mailtrap.io/api/contacts/exports filtered on subscription_status and list_id. Create the matching custom fields and audiences in Emailit first.
Import only subscribed contacts, one audience at a time, in Email MarketingContacts with Import. The import adds everyone in the file as subscribed, so add unsubscribed contacts to your suppression file with the type unsubscribe instead. Split files into parts of up to 2,500 rows. See Import and export contacts.
Move templates
Get your templates’ HTML with GET https://mailtrap.io/api/email_templates, which returns each template’s body_html, body_text and subject. Import each one in Email MarketingTemplates or create it with the Templates API, and give it an alias, such as receipt.
Mailtrap templates use Handlebars. Temple covers the common parts:
| Mailtrap (Handlebars) | Emailit (Temple) |
|---|---|
{{name}}, {{user.name}} |
The same |
{{{html_block}}} |
{{html_block}}. Temple never escapes HTML, so escape user input yourself. |
{{#if plan}}…{{else}}…{{/if}} |
The same |
{{#unless plan}}…{{/unless}} |
{{#if plan}}{{else}}…{{/if}} |
{{#if name}}{{name}}{{else}}Customer{{/if}} |
{{name|"Customer"}} |
{{#each items}}…{{/each}}, {{#with}} |
Not supported. Render the list in your code and pass it as one variable. |
template_variables |
variables |
See Temple and Import and export templates.
Change DNS
Add your domain in Email APIDomains and publish the Emailit records. They use their own names (emailit._domainkey, emailit.<domain>, and optionally go and inbound), so they don’t conflict with Mailtrap’s rwmt1._domainkey and rwmt2._domainkey DKIM records, its verification CNAME or its mt-link tracking CNAME. Keep your DMARC record. See DNS records.
After the cutover, remove the Mailtrap DKIM, verification and tracking records, and include:_spf.mailtrap.io if your SPF record still has it. Mailtrap inbound receives on your root domain’s MX record, and Emailit inbound on a subdomain such as inbound.acme.com, so move inbound mail and update your receiving addresses before you change the MX record. See Set up inbound.
Next steps
- Go-live checklist
- Set up webhooks
- Priority migration: let Emailit engineers do the move with you