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

## Concepts

| MailerSend | Emailit |
| --- | --- |
| Account | Account and [workspaces](/docs/workspaces/). Each workspace has its own domains, keys, members and credits. |
| Domains | [Sending domains](/docs/domains/) |
| Sender identities | Not available. Every From address must be on a verified domain. |
| API tokens with scopes | [API keys](/docs/developers/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](/docs/workspaces/production-access/) and can only send to workspace members. |
| Templates | [Templates](/docs/templates/) with an alias and versions, rendered with [Temple](/docs/templates/temple/) |
| Webhooks per domain | [Webhooks](/docs/webhooks/) per workspace |
| Inbound routes | [Inbound email](/docs/inbound/), with the `email.received` webhook or the **Forward received email** [automation](/docs/inbound/forward-with-automations/) |
| Suppressions per domain: hard bounces, spam complaints, unsubscribes, blocklist | One [suppression list](/docs/suppressions/) per workspace |
| On hold list | Not needed. Emailit retries soft bounces and reports each attempt as `email.attempted`. |
| Activity | **Email API → Emails** and **Email API → Logs** |
| Tags | `meta` |
| Email verification | [Email verification](/docs/email-verification/) |
| Dedicated IPs | [Dedicated IPs](/docs/deliverability/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:

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

```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>"
  }'
```

| MailerSend | Emailit |
| --- | --- |
| `Authorization: Bearer <token>` | `Authorization: Bearer secret_…` |
| `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` | The same |
| `headers: [{ "name": "…", "value": "…" }]` | `headers: { "Name": "Value" }` |
| `list_unsubscribe` | `headers` with `List-Unsubscribe` and `List-Unsubscribe-Post`. See [Headers and metadata](/docs/email-api/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](/docs/email-api/send-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](/docs/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}`](/docs/api-reference/emails/get/) |

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 `type` in both. Emailit's email is in `data.object`: use `data.object.id`, the `em_` ID from the send response, instead of `data.message_id` (`data.email.message.id` in version 1 webhooks), and `data.object.to` instead of `data.recipient`. 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.
- MailerSend's `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. 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`, `/unsubscribes` and `/blocklist`). The on hold list is temporary, so you can leave it out.

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

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

   Use the type `recipient` for addresses that must never receive email. It blocks API, SMTP and campaign sends. For people who only unsubscribed from marketing email, use the type `unsubscribe`, which stops campaigns but still lets transactional email through.

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.

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](/docs/suppressions/manage/).

## Move templates

Copy each template's HTML from MailerSend's editor, then import it in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/). 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](/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 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](/docs/domains/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](/docs/inbound/set-up/).

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](/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/mailersend/
