# Migrate from Mailjet

> Move from Mailjet to Emailit. Map API key pairs and senders, convert Send API v3.1 calls and template language, swap SMTP, and move webhooks, exclusions and contact lists.

This guide maps Mailjet 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

| Mailjet | Emailit |
| --- | --- |
| Primary API key and sub-account API keys | Account and [workspaces](/docs/workspaces/). Each workspace has its own domains, keys, members and credits. |
| API key pair (public and secret key) | [API key](/docs/developers/api-keys/): **Full Access**, or **Sending Only** optionally restricted to one domain |
| Senders: single addresses and whole domains | [Sending domains](/docs/domains/). Single sender addresses aren't available. |
| `SandboxMode` | No test mode. New workspaces are in [sandbox mode](/docs/workspaces/production-access/) and deliver only to workspace members. |
| Templates and the Mailjet template language | [Templates](/docs/templates/) with an alias and versions, rendered with [Temple](/docs/templates/temple/) |
| Event API, one URL per event type | [Webhooks](/docs/webhooks/): one endpoint can receive every event type |
| Parse API | [Inbound email](/docs/inbound/) |
| Exclusion list, spam complainers and blocked addresses | [Suppressions](/docs/suppressions/) |
| Contacts, contact lists and contact properties | [Contacts](/docs/contacts/), [audiences](/docs/audiences/) and [custom fields](/docs/contacts/custom-fields/) |
| Segments | Pick and exclude audiences in each campaign. [Segments](/docs/segments/) are in alpha and open to the Emailit team only. |
| Campaigns and automations | [Campaigns](/docs/campaigns/) and [automations](/docs/automations/) (beta) |
| `CustomID`, `EventPayload`, `CustomCampaign` | `meta` |
| Statistics and message history | **Email API → Emails**, **Email API → Logs** and [campaign reports](/docs/campaigns/reports/) |

## Update your API calls

Mailjet's `POST /v3.1/send` takes basic authentication and a `Messages` list with PascalCase fields. Emailit's `POST /v2/emails` takes a bearer token and one message with lowercase fields:

```bash title="Before: Mailjet"
curl https://api.mailjet.com/v3.1/send \
  --user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
  -H "Content-Type: application/json" \
  -d '{
    "Messages": [{
      "From": { "Email": "hello@acme.com", "Name": "Acme" },
      "To": [{ "Email": "ada@example.com" }],
      "Subject": "Your receipt",
      "TextPart": "Thanks for your order.",
      "HTMLPart": "<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>"
  }'
```

| Mailjet (Send API v3.1) | Emailit |
| --- | --- |
| Basic authentication with the public and secret key | `Authorization: Bearer secret_…` |
| `api.mailjet.com`, or `api.us.mailjet.com` for US accounts | One host, `api.emailit.com` |
| `Messages[]`, up to 50 per call | One message per request |
| `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 |
| `ReplyTo` | `reply_to` |
| `Subject`, `TextPart`, `HTMLPart` | `subject`, `text`, `html` |
| `Headers` | `headers` |
| `Attachments[]` with `ContentType`, `Filename`, `Base64Content` | `attachments[]` with `content_type`, `filename`, `content` |
| `InlinedAttachments[]` with `ContentID` | `attachments[]` with a `content_id`, referenced as `cid:` in the HTML |
| `CustomID`, `EventPayload`, `CustomCampaign` | `meta`, for example `meta: { "custom_id": "order-123" }`, returned in webhook events |
| `TemplateID`, `TemplateLanguage: true` and `Variables` | `template` (an alias or ID) and `variables` |
| `TrackOpens`, `TrackClicks` | `tracking: { "loads": true, "clicks": true }` |
| `URLTags` | Add UTM parameters to your links. Campaigns add them for you. |
| `Globals` | Not available. Repeat the shared fields in each request. |
| Response with `MessageUUID` and `MessageID` for each recipient | `200` with `id` (`em_…`), `status: "accepted"` and, for several recipients, `ids` with one ID each |

Emailit IDs are strings, so you no longer need to handle Mailjet's large integer `MessageID` values. Emailit also supports scheduling with `scheduled_at` and safe retries with an `Idempotency-Key` header. See [Send an email](/docs/email-api/send-email/).

## Switch SMTP settings

| Setting | Mailjet | Emailit |
| --- | --- | --- |
| Host | `in-v3.mailjet.com` | `smtp.emailit.com` |
| Port | `587`, `588`, `2525`, `25` or `80` (STARTTLS), `465` (TLS) | `587`, `2587`, `2525` or `25` (STARTTLS), `465` (TLS) |
| Username | Your public API key | `emailit` |
| Password | Your secret API key | Your Emailit API key |

Emailit doesn't read Mailjet's headers, such as `X-Mailjet-Campaign`, `X-MJ-CustomID`, `X-MJ-EventPayload`, `X-Mailjet-TrackOpen`, `X-Mailjet-TrackClick`, `X-MJ-TemplateID` or `X-MJ-Vars`. 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

| Mailjet event | Emailit event |
| --- | --- |
| `sent` | `email.delivered` |
| `bounce` | `email.bounced`. Emailit also sends `email.attempted` for each failed attempt it retries. |
| `blocked` | `email.suppressed` when the address has a `recipient` suppression |
| `spam` | `email.complained` |
| `open` | `email.loaded` |
| `click` | `email.clicked` |
| `unsub` | `email.unsubscribed`, for campaign email only |
| Parse API route | `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:

- Mailjet needs one URL for each event type, and posts one event per request unless you group events. An Emailit webhook can subscribe to many event types and posts a JSON array of up to 100 events, so loop over the body.
- The event name moves from `event` to `type`, and the email is in `data.object`. Use `data.object.id`, the `em_` ID from the send response, instead of `MessageID` or `Message_GUID`, and `data.object.to` instead of `email`. Your `meta` values, which replace `CustomID` and `Payload`, 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.
- Mailjet doesn't sign its requests. Emailit signs every one: verify `X-Emailit-Signature` against `X-Emailit-Timestamp` and your `whsec_` secret, and drop the basic authentication credentials from your URL if you like. 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

Mailjet has no single suppression list, so collect the addresses from several places:

1. Gather the addresses Mailjet blocks:

   | Mailjet | How to export | Emailit type |
   | --- | --- | --- |
   | Exclusion list | The exclusion list's download in the dashboard, or `GET /v3/REST/contact?IsExcludedFromCampaigns=true` | `unsubscribe`, which stops campaigns but still lets transactional email through, like Mailjet's exclusion list |
   | Spam complainers | Contacts with `IsSpamComplaining` set, from `GET /v3/REST/contact` | `recipient` |
   | Hard bounces | The `bounce` events your webhooks stored, or your campaign reports | `recipient` |

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

```csv
email,type,reason
excluded@example.com,unsubscribe,mailjet exclusion list
angry@example.com,recipient,mailjet spam complaint
```

   The type `recipient` blocks API, SMTP and campaign sends.

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.

If you used several Mailjet API keys, repeat this for each one. See [Manage suppressions](/docs/suppressions/manage/).

## Move contacts

Export each contact list from **Contacts** in Mailjet, or with `GET /v3/REST/listrecipient?ContactsList={id}`, which includes each member's `IsUnsubscribed` flag. Contact properties come from `GET /v3/REST/contactdata`.

1. **Prepare Emailit.** Create a [custom field](/docs/contacts/custom-fields/) for each contact property you use, and an [audience](/docs/audiences/) for each list.

2. **Import the subscribed members.** In **Email Marketing → Contacts**, select **Import**, map the columns and choose the matching audience. Split files into parts of up to 2,500 rows. See [Import and export contacts](/docs/contacts/import-export/).

3. **Suppress the rest.** The import adds everyone in the file as subscribed, so keep unsubscribed members out of the file. Add them to your suppression file with the type `unsubscribe` instead, and leave out contacts whose opt-in is still pending. An `unsubscribe` suppression stops every campaign, so don't add one for people who are still subscribed to another list you're moving.

Recreate your campaigns and automations in **Email Marketing → Campaigns** and **Automations**, starting from your imported templates.

## Move templates

Get each template's HTML with `GET /v3/REST/template/{id}/detailcontent`, which returns `Html-part` and `Text-part`, or copy it from Mailjet's editor. Import it in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/), and give it an alias, such as `receipt`.

Convert the Mailjet template language to Temple:

| Mailjet | Emailit (Temple) |
| --- | --- |
| `{{var:name}}`, `{{var:order.total}}` | `{{name}}`, `{{order.total}}` |
| `{{var:name:"there"}}` | `{{name\|"there"}}` |
| `{{data:firstname}}` (a contact property) | `{{first_name}}` or `{{cf.<key>}}` in campaigns. In API sends, pass the value in `variables`. |
| `{% if var:plan %}…{% else %}…{% endif %}` | `{{#if plan}}…{{else}}…{{/if}}` |
| `{% if var:plan == "pro" %}`, `{% elseif %}` | Not supported. Pass a boolean such as `is_pro` and use `{{#if is_pro}}`. |
| `{% for item in var:items %}…{% endfor %}` | Not supported. Render the list in your code and pass it as one variable. |
| Functions such as `Upper()` or `FormatNumber()` | Not supported. Format the value in your code. |
| `{{mj:unsub_link}}` | `{{unsubscribe_url}}` in campaigns |
| `Variables` | `variables` |

Temple never escapes 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 Mailjet's `mailjet._domainkey` DKIM record or its ownership TXT record. Keep your DMARC record. See [DNS records](/docs/domains/dns-records/).

If your custom Mailjet tracking host is already `go`, choose another name for Emailit's with `tracking_key`. See [Custom tracking domain](/docs/tracking/custom-tracking-domain/).

After the cutover, remove the Mailjet DKIM, ownership, tracking and return-path records, and `include:spf.mailjet.com` from your SPF record. If you receive mail with the Parse API on your own domain, 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/mailjet/
