# 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](/docs/migrate/) first for the overall order and how to run both providers in parallel.

## Concepts

| Mailtrap | Emailit |
| --- | --- |
| Organization and sub-accounts | Account and [workspaces](/docs/workspaces/). Each workspace has its own domains, keys, members and credits. |
| Sending domains | [Sending domains](/docs/domains/) |
| Transactional stream | The [Email API](/docs/email-api/) and [SMTP relay](/docs/smtp/) |
| Bulk stream | [Campaigns](/docs/campaigns/), or the API with your own `List-Unsubscribe` headers |
| API tokens with per-resource permissions | [API keys](/docs/developers/api-keys/): **Full Access**, or **Sending Only** optionally restricted to one domain |
| Demo domain | New workspaces are in [sandbox mode](/docs/workspaces/production-access/) 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](/docs/templates/) with an alias and versions, rendered with [Temple](/docs/templates/temple/) |
| Webhooks per stream | [Webhooks](/docs/webhooks/) per workspace |
| Suppressions per domain and stream | One [suppression list](/docs/suppressions/) per workspace |
| Email logs | **Email API → Emails** and **Email API → Logs** |
| `category` and `custom_variables` | `meta` |
| Email Marketing: contacts, lists, campaigns, automations | [Contacts](/docs/contacts/), [audiences](/docs/audiences/), [campaigns](/docs/campaigns/) and [automations](/docs/automations/) (beta) |
| Inbound email | [Inbound email](/docs/inbound/) |

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:

```bash title="Before: Mailtrap"
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>"
  }'
```

```bash title="After: Emailit"
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 "` |
| `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](/docs/email-api/send-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](/docs/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}`](/docs/api-reference/emails/get/) |

Emailit also sends `email.accepted` when the API accepts an email. See [Event types](/docs/webhooks/event-types/).

The request format changes:

- Mailtrap posts an `events` list 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 in `data.object`. Use `data.object.id`, the `em_` ID from the send response, instead of `message_id`, and `data.object.to` instead of `email`. Your `meta` values, which replace `category` and `custom_variables`, are in `data.object.meta`.
- For `email.loaded` and `email.clicked`, `data.object` is the load or the click. Use `data.object.email_id` for the email's ID, and `data.object.email.rcpt_to` and `data.object.email.meta` for the recipient and your `meta` values.
- Mailtrap's `Mailtrap-Signature` header is an HMAC-SHA256 of the raw body. Emailit's `X-Emailit-Signature` is an HMAC-SHA256 of `<timestamp>.<raw body>`, keyed with your `whsec_` secret, so read `X-Emailit-Timestamp` too. See [Request signature](/docs/webhooks/request-signature/).

```javascript
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

1. 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.

2. Build one CSV with the columns `email,type,reason`:

   | Mailtrap type | Emailit type |
   | --- | --- |
   | `hard bounce`, `spam complaint`, `manual import` | `recipient`, which blocks API, SMTP and campaign sends |
   | `unsubscription` | `unsubscribe`, which stops campaigns but still lets transactional email through. Use `recipient` for unsubscribes from the transactional stream. |

```csv
email,type,reason
old-address@example.com,recipient,mailtrap hard bounce
left@example.com,unsubscribe,mailtrap unsubscription
```

3. In **Email API → Suppressions**, 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](/docs/suppressions/manage/).

## 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](/docs/contacts/custom-fields/) and [audiences](/docs/audiences/) in Emailit first.

Import only subscribed contacts, one audience at a time, in **Email Marketing → Contacts** 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](/docs/contacts/import-export/).

## 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 Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/), 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](/docs/templates/temple/) and [Import and export templates](/docs/templates/import-export/).

## Change DNS

Add your domain in **Email API → Domains** 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](/docs/domains/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](/docs/inbound/set-up/).

## Next steps

- [Go-live checklist](/docs/get-started/go-live/)
- [Set up webhooks](/docs/webhooks/set-up/)
- [Priority migration](/docs/programs/priority-migration/): let Emailit engineers do the move with you

---
Source: https://emailit.com/docs/migrate/mailtrap/
