# Migrate from Mandrill

> Move from Mandrill (Mailchimp Transactional) to Emailit. Map API keys and subaccounts, convert messages/send calls, swap SMTP and X-MC headers, verify webhooks and move rejects.

This guide maps Mandrill (Mailchimp Transactional Email) concepts, API calls, webhooks, the rejection denylist and templates to their Emailit equivalents. Read [Migrate to Emailit](/docs/migrate/) first for the overall order and how to run both providers in parallel. If you also send campaigns from Mailchimp, see [Migrate from Mailchimp](/docs/migrate/mailchimp/).

## Concepts

| Mandrill | Emailit |
| --- | --- |
| A Mailchimp Standard or Premium plan with transactional blocks | An Emailit account. You don't need a marketing plan to send transactional email. |
| Subaccounts | [Workspaces](/docs/workspaces/), each with its own domains, keys, limits and credits |
| API keys | [API keys](/docs/developers/api-keys/): **Full Access**, or **Sending Only** optionally restricted to one domain |
| Test API keys | No test mode. New workspaces are in [sandbox mode](/docs/workspaces/production-access/) and can only send to workspace members. |
| Sending domains and DKIM/SPF verification | [Sending domains](/docs/domains/) |
| Tracking domains | [Tracking subdomain](/docs/tracking/), such as `go.acme.com` |
| Templates with `mc:edit` regions | [Templates](/docs/templates/) with an alias and versions, rendered with [Temple](/docs/templates/temple/) |
| Webhooks | [Webhooks](/docs/webhooks/) |
| Inbound domains and routes | [Inbound email](/docs/inbound/) |
| Rejection denylist | [Suppressions](/docs/suppressions/) |
| Rejection allowlist | Not available |
| Merge languages: Mailchimp and Handlebars | [Temple](/docs/templates/temple/) |
| Tags and metadata | `meta` |
| Outbound activity | **Email API → Emails** and **Email API → Logs** |
| Dedicated IPs and IP pools | [Dedicated IPs](/docs/deliverability/dedicated-ips/) on request |

## Update your API calls

Mandrill's `POST /messages/send` takes the API key in the JSON body and nests the email in `message`. Emailit's `POST /v2/emails` takes a bearer token and a flat body:

```bash title="Before: Mandrill"
curl https://mandrillapp.com/api/1.0/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "key": "'"$MANDRILL_API_KEY"'",
    "message": {
      "from_email": "hello@acme.com",
      "from_name": "Acme",
      "to": [{ "email": "ada@example.com", "type": "to" }],
      "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>"
  }'
```

| Mandrill | Emailit |
| --- | --- |
| `key` in the request body | `Authorization: Bearer secret_…` header |
| `message.from_email` and `from_name` | `from: "Name "` |
| `message.to[]` with `type` `to`, `cc` or `bcc` | `to`, `cc`, `bcc`, up to 50 each |
| `message.headers["Reply-To"]` | `reply_to` |
| `message.subject`, `html`, `text` | `subject`, `html`, `text` |
| `message.headers` | `headers` |
| `message.attachments[]` with `type`, `name`, `content` | `attachments[]` with `content_type`, `filename`, `content` |
| `message.images[]` for inline images | `attachments[]` with a `content_id`, referenced as `cid:` in the HTML |
| `message.metadata`, `message.tags` | `meta`, an object of string values, returned in webhook events |
| `message.track_opens`, `track_clicks` | `tracking: { "loads": true, "clicks": true }` |
| `message.global_merge_vars` | `variables` |
| `message.merge_vars` (per recipient) | One request per recipient, each with its own `variables` |
| `message.subaccount` | Use an API key from the matching workspace |
| `send_at` | `scheduled_at` (ISO 8601 or plain English) |
| `async` | Not needed. Emailit queues every email for delivery and answers without waiting for it. |
| `POST /messages/send-template` with `template_name` | The same `POST /v2/emails` with `template` (an alias or ID) and `variables` |
| Response: an array with `email`, `status` and `_id` for each recipient | `200` with `id` (`em_…`), `status: "accepted"` and, for several recipients, `ids` with one ID each |

Mandrill reports problems per recipient in the response, with statuses such as `rejected` or `invalid`. Emailit validates the whole request and returns an HTTP error for invalid input. Recipients with a `recipient` suppression are accepted and then get the status `suppressed`. Add an `Idempotency-Key` header so retries are safe. See [Send an email](/docs/email-api/send-email/).

## Switch SMTP settings

| Setting | Mandrill | Emailit |
| --- | --- | --- |
| Host | `smtp.mandrillapp.com` | `smtp.emailit.com` |
| Port | `587`, `2525` or `25` (STARTTLS), `465` (TLS) | `587`, `2587`, `2525` or `25` (STARTTLS), `465` (TLS) |
| Username | Any value | `emailit` |
| Password | A Mandrill API key | Your Emailit API key |

Emailit doesn't read `X-MC-*` headers such as `X-MC-Template`, `X-MC-MergeVars`, `X-MC-Tags`, `X-MC-Metadata` or `X-MC-Track`. Remove them. Set tracking on the domain, and use the API when you need templates or metadata. See [SMTP settings](/docs/smtp/settings/).

## Map webhook events

| Mandrill event | Emailit event |
| --- | --- |
| `send` | `email.accepted` (API only) |
| `delivered` | `email.delivered` |
| `deferral` | `email.attempted` |
| `hard_bounce` | `email.bounced` |
| `soft_bounce` | `email.attempted` while Emailit retries, then `email.bounced` if every retry fails |
| `open` | `email.loaded` |
| `click` | `email.clicked` |
| `spam` | `email.complained` |
| `unsub` | `email.unsubscribed`, for campaign email only |
| `reject` | `email.suppressed` when the address has a `recipient` suppression. Other reject reasons, such as `unsigned`, are API errors in Emailit. |
| Rejection denylist sync events | `suppression.created`, `suppression.deleted`, for suppressions you add or remove |
| `inbound` | `email.received`, then fetch the content with [`GET /emails/{id}`](/docs/api-reference/emails/get/) |

The request format changes:

- Mandrill posts a form field, `mandrill_events`, that holds a JSON array of up to 1,000 events. Emailit posts the JSON array as the request body, with up to 100 events.
- 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 `_id`, and `data.object.to` instead of `msg.email`. Your `meta` values 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.
- Mandrill signs the URL and the form fields with HMAC-SHA1, base64-encoded, in `X-Mandrill-Signature`. Emailit signs `<timestamp>.<raw body>` with HMAC-SHA256: verify `X-Emailit-Signature` against `X-Emailit-Timestamp` and your `whsec_` secret. 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 the whole rejection denylist with **Export Full Denylist** on Mandrill's **Rejection Denylist** page, or with the `/exports/rejects` API call. `/rejects/list` returns at most 1,000 entries, so don't use it for this. The export is a ZIP file with `rejects.csv`, and covers every subaccount.

2. Build one CSV with the columns `email,type,reason`. Skip entries that have already expired, and use the `reason` column to pick the type:

   | Mandrill reason | Emailit type |
   | --- | --- |
   | `hard-bounce`, `spam`, `custom` | `recipient` |
   | `unsub` | `unsubscribe`, which stops campaigns but still lets transactional email through. Use `recipient` to block all email, as Mandrill did. |
   | `soft-bounce` | Leave it out. These expire after a day. |

```csv
email,type,reason
old-address@example.com,recipient,mandrill hard-bounce
angry@example.com,recipient,mandrill spam
```

   The type `recipient` blocks API, SMTP and campaign sends. If you used subaccounts, split the file by its subaccount column and import each part into the matching workspace.

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.

Mandrill's rejection allowlist has no equivalent. See [Manage suppressions](/docs/suppressions/manage/).

## Move templates

Get your templates' code from Mandrill: one `/templates/list` call returns every template with its `slug` and its published HTML in `publish_code`. Then import each one in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/). Use the Mandrill slug as the alias if it fits the alias format of lowercase letters, numbers, `-` and `_`.

Templates that used `mc:edit` regions filled by `template_content` need those regions turned into variables. Mandrill merge variable names aren't case-sensitive, but Temple's are: `{{FNAME}}` only matches a variable named `FNAME`. Convert merge tags to Temple:

| Mandrill | Emailit (Temple) |
| --- | --- |
| `*\|FNAME\|*` (Mailchimp merge language) | `{{FNAME}}`, or rename it to `{{first_name}}` |
| `{{fname}}` (Handlebars merge language) | `{{fname}}` |
| `*\|IF:FNAME\|*…*\|ELSE:\|*…*\|END:IF\|*` | `{{#if FNAME}}…{{else}}…{{/if}}` |
| `*\|IF:PLAN=pro\|*`, or a comparison inside a Handlebars `{{#if}}` | Not supported. Pass a boolean such as `is_pro` and use `{{#if is_pro}}`. |
| `*\|DATE:d/m/y\|*`, `*\|CURRENT_YEAR\|*`, helpers such as `{{upper name}}` | Not supported. Format the value in your code and pass it. |
| `*\|UNSUB:https://…\|*`, `{{unsub "…"}}` | Your own unsubscribe link. See [Unsubscribes](/docs/audiences/unsubscribes/#transactional-email-and-unsubscribes). |
| `{{#if plan}}…{{else}}…{{/if}}` | The same |
| `{{#each items}}…{{/each}}` | Not supported. Render the list in your code and pass it as one variable. |
| `…` with `template_content` | `{{body}}`, passed in `variables` |
| `global_merge_vars` | `variables` |

Temple never escapes HTML, so escape user input before you pass it. A missing value renders as an empty string unless you add a default, such as `{{name|"there"}}`. See [Temple](/docs/templates/temple/).

## 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 Mandrill's `mte1._domainkey` and `mte2._domainkey` CNAMEs or its `mandrill_verify` TXT record. Keep your DMARC record. See [DNS records](/docs/domains/dns-records/).

After the cutover, remove the Mandrill DKIM and verification records, any custom tracking or return-path CNAMEs, and `include:spf.mandrillapp.com` if your SPF record has it. If you receive mail with Mandrill inbound routes, move it to an Emailit [inbound subdomain](/docs/inbound/set-up/) first.

## 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/mandrill/
