Guide
Migrate from MailerSend
Move from MailerSend to Emailit. Map domains, tokens and SMTP users, convert API calls and personalization, switch SMTP, and move webhooks, suppressions and templates.
This guide maps MailerSend concepts, API calls, webhooks, suppressions and templates to their Emailit equivalents. Read Migrate to Emailit first for the overall order and how to run both providers in parallel.
Concepts
| MailerSend | Emailit |
|---|---|
| Account | Account and workspaces. Each workspace has its own domains, keys, members and credits. |
| Domains | Sending domains |
| Sender identities | Not available. Every From address must be on a verified domain. |
| API tokens with scopes | API keys: Full Access, or Sending Only optionally restricted to one domain |
| SMTP users | Your API key, used as the SMTP password |
| Test domain and sandbox mode | No shared test domain. New workspaces are in sandbox mode and can only send to workspace members. |
| Templates | Templates with an alias and versions, rendered with Temple |
| Webhooks per domain | Webhooks per workspace |
| Inbound routes | Inbound email, with the email.received webhook or the Forward received email automation |
| Suppressions per domain: hard bounces, spam complaints, unsubscribes, blocklist | One suppression list per workspace |
| On hold list | Not needed. Emailit retries soft bounces and reports each attempt as email.attempted. |
| Activity | Email APIEmails and Email APILogs |
| Tags | meta |
| Email verification | Email verification |
| Dedicated IPs | Dedicated IPs on request |
Update your API calls
MailerSend’s POST /v1/email becomes POST /v2/emails. Both take a bearer token and JSON, but Emailit’s addresses are plain strings instead of objects:
curl https://api.mailersend.com/v1/email \
-H "Authorization: Bearer $MAILERSEND_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>"
}'| MailerSend | Emailit |
|---|---|
Authorization: Bearer <token> |
Authorization: Bearer secret_… |
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 |
The same |
headers: [{ "name": "…", "value": "…" }] |
headers: { "Name": "Value" } |
list_unsubscribe |
headers with List-Unsubscribe and List-Unsubscribe-Post. See Headers and metadata. |
attachments[] with content, filename, disposition and id |
attachments[] with content, filename and content_type, or a url instead of content. Use content_id for inline images. |
template_id |
template, a template ID or alias |
personalization: [{ "email": "…", "data": { … } }] |
variables, with one request per recipient when the values differ |
tags |
meta, returned in webhook events |
send_at (Unix time or ISO 8601) |
scheduled_at (ISO 8601 or plain English). Convert Unix times to ISO 8601 first. |
settings.track_opens, settings.track_clicks |
tracking: { "loads": true, "clicks": true } |
POST /v1/bulk-email |
Not available. Send one request per message. |
202 Accepted with an x-message-id header and an empty body |
200 with a JSON body: id (em_…), status: "accepted" and, for several recipients, ids with one ID each |
Each recipient in an Emailit request becomes its own email with its own ID. MailerSend answers 202 even when every recipient is suppressed, with a warning in the body. Emailit accepts recipients with a recipient suppression too and gives each one the status suppressed. Add an Idempotency-Key header so retries are safe. See Send an email.
Switch SMTP settings
| Setting | MailerSend | Emailit |
|---|---|---|
| Host | smtp.mailersend.net |
smtp.emailit.com |
| Port | 587 (STARTTLS) |
587, 2587, 2525 or 25 (STARTTLS), 465 (TLS) |
| Username | The SMTP user’s generated username | emailit |
| Password | The SMTP user’s password | Your Emailit API key |
Emailit doesn’t read the X-MailerSend-Tags header. Remove it. Unlike MailerSend, Emailit delivers your other custom headers unchanged. See SMTP settings.
Map webhook events
| MailerSend event | Emailit event |
|---|---|
activity.sent |
email.accepted (API only) |
activity.delivered |
email.delivered |
activity.deferred |
email.attempted |
activity.soft_bounced |
email.attempted while Emailit retries, then email.bounced if every retry fails |
activity.hard_bounced |
email.bounced |
activity.suppressed |
email.suppressed |
activity.opened, activity.opened_unique |
email.loaded, sent for every load |
activity.clicked, activity.clicked_unique |
email.clicked, sent for every click |
activity.spam_complaint |
email.complained |
activity.unsubscribed |
email.unsubscribed, for campaign email only |
| Inbound route forwarding to a webhook | email.received, then fetch the content with GET /emails/{id} |
The request format changes:
- MailerSend posts one event per request. Emailit posts a JSON array of up to 100 events, so loop over the body.
- The event name is in
typein both. Emailit’s email is indata.object: usedata.object.id, theem_ID from the send response, instead ofdata.message_id(data.email.message.idin version 1 webhooks), anddata.object.toinstead ofdata.recipient. 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. - MailerSend’s
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
-
In MailerSend, export the Hard bounces, Spam complaints, Unsubscribes and Blocklist of each domain, from the suppressions pages or with the API (
/v1/suppressions/hard-bounces,/spam-complaints,/unsubscribesand/blocklist). The on hold list is temporary, so you can leave it out. -
Build one CSV with the columns
email,type,reason:email,type,reason old-address@example.com,recipient,mailersend hard bounce angry@example.com,recipient,mailersend spam complaintUse the type
recipientfor addresses that must never receive email. It blocks API, SMTP and campaign sends. For people who only unsubscribed from marketing email, use the typeunsubscribe, which stops campaigns but still lets transactional email through. -
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.
Emailit has one suppression list per workspace, so addresses from all your MailerSend domains go into the same list. Suppressions are exact addresses: blocklist patterns such as .*@example.com have no equivalent. See Manage suppressions.
Move templates
Copy each template’s HTML from MailerSend’s editor, then import it in Email MarketingTemplates or create it with the Templates API. Give it an alias, such as receipt, and send it with "template": "receipt" and variables.
MailerSend’s personalization is a limited version of Twig. Temple covers the common parts:
| MailerSend | Emailit (Temple) |
|---|---|
{{ name }}, {{ user.name }} |
{{name}}, {{user.name}} |
{{ name|default('there') }} |
{{name|"there"}} |
{% if plan %}…{% else %}…{% endif %} |
{{#if plan}}…{{else}}…{{/if}} |
{% if plan == "pro" %}, {% elseif %} |
Not supported. Pass a boolean such as is_pro and use {{#if is_pro}}. |
{% for item in items %}…{% endfor %} |
Not supported. Render the list in your code and pass it as one variable. |
{{ name|upper }} and other filters |
Not supported. Format the value in your code. |
personalization[].data |
variables |
MailerSend strips most HTML from personalization values. Temple never escapes or strips HTML, so escape user input before you pass it. 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 MailerSend’s ms1._domainkey and ms2._domainkey DKIM records, its mta return-path CNAME or its email tracking CNAME. Keep your DMARC record. See DNS records.
MailerSend inbound routing also uses an inbound subdomain by default. If yours does, give Emailit inbound another subdomain with inbound_key, or switch the MX record when you move inbound mail. See Set up inbound.
After the cutover, remove the MailerSend DKIM, return-path and tracking records, and remove include:_spf.mailersend.net from your SPF record.
Next steps
- Go-live checklist
- Set up webhooks
- Priority migration: let Emailit engineers do the move with you