Guide
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 first for the overall order and how to run both providers in parallel. If you also send campaigns from Mailchimp, see Migrate from 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, each with its own domains, keys, limits and credits |
| API keys | API keys: Full Access, or Sending Only optionally restricted to one domain |
| Test API keys | No test mode. New workspaces are in sandbox mode and can only send to workspace members. |
| Sending domains and DKIM/SPF verification | Sending domains |
| Tracking domains | Tracking subdomain, such as go.acme.com |
Templates with mc:edit regions |
Templates with an alias and versions, rendered with Temple |
| Webhooks | Webhooks |
| Inbound domains and routes | Inbound email |
| Rejection denylist | Suppressions |
| Rejection allowlist | Not available |
| Merge languages: Mailchimp and Handlebars | Temple |
| Tags and metadata | meta |
| Outbound activity | Email APIEmails and Email APILogs |
| Dedicated IPs and IP pools | 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:
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>"
}
}'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 <email>" |
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.
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.
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} |
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 indata.object. Usedata.object.id, theem_ID from the send response, instead of_id, anddata.object.toinstead ofmsg.email. Yourmetavalues 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. - 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: verifyX-Emailit-SignatureagainstX-Emailit-Timestampand yourwhsec_secret. 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 the whole rejection denylist with Export Full Denylist on Mandrill’s Rejection Denylist page, or with the
/exports/rejectsAPI call./rejects/listreturns at most 1,000 entries, so don’t use it for this. The export is a ZIP file withrejects.csv, and covers every subaccount. -
Build one CSV with the columns
email,type,reason. Skip entries that have already expired, and use thereasoncolumn to pick the type:Mandrill reason Emailit type hard-bounce,spam,customrecipientunsubunsubscribe, which stops campaigns but still lets transactional email through. Userecipientto block all email, as Mandrill did.soft-bounceLeave it out. These expire after a day. email,type,reason old-address@example.com,recipient,mandrill hard-bounce angry@example.com,recipient,mandrill spamThe type
recipientblocks API, SMTP and campaign sends. If you used subaccounts, split the file by its subaccount column and import each part into the matching workspace. -
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.
Mandrill’s rejection allowlist has no equivalent. See Manage suppressions.
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 MarketingTemplates or create it with the Templates API. 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. |
{{#if plan}}…{{else}}…{{/if}} |
The same |
{{#each items}}…{{/each}} |
Not supported. Render the list in your code and pass it as one variable. |
<div mc:edit="body">…</div> 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.
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 Mandrill’s mte1._domainkey and mte2._domainkey CNAMEs or its mandrill_verify TXT record. Keep your DMARC record. See 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 first.
Next steps
- Go-live checklist
- Set up webhooks
- Priority migration: let Emailit engineers do the move with you