# Migrate from Elastic Email

> Move from Elastic Email to Emailit. Map API v4 and v2 calls, SMTP credentials and notifications, convert merge fields, and move suppressions, contacts and campaigns.

This guide maps Elastic Email concepts, API calls, notifications, 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

| Elastic Email | Emailit |
| --- | --- |
| Account and subaccounts | Account and [workspaces](/docs/workspaces/). Each workspace has its own domains, keys, members and credits. |
| API keys with access levels | [API keys](/docs/developers/api-keys/): **Full Access**, or **Sending Only** optionally restricted to one domain |
| SMTP credentials | Your API key, used as the SMTP password |
| Verified domains and verified sender addresses | [Sending domains](/docs/domains/). Single sender addresses aren't available. |
| Channels and postback values | `meta` |
| Templates, addressed by name | [Templates](/docs/templates/) with an alias and versions |
| Merge fields and template scripting | [Temple](/docs/templates/temple/): variables, defaults and conditionals |
| HTTP web notifications | [Webhooks](/docs/webhooks/) |
| Inbound routes | [Inbound email](/docs/inbound/) |
| Suppressions and blocking contact statuses | [Suppressions](/docs/suppressions/) |
| Contacts and lists | [Contacts](/docs/contacts/) and [audiences](/docs/audiences/) |
| 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) |
| Forms | [Forms](/docs/forms/) (early access), or an audience's [subscribe URL](/docs/audiences/subscribe-url/) |
| Email verification | [Email verification](/docs/email-verification/) |
| Private IPs and IP pools | [Dedicated IPs](/docs/deliverability/dedicated-ips/) on request |

Elastic Email adds an unsubscribe link to every email, including API and SMTP sends. Emailit adds `List-Unsubscribe` headers only to [campaigns](/docs/campaigns/) and to marketing emails from automations, and you add the visible link yourself with `{{unsubscribe_url}}`. If you send newsletters or other bulk mail through the API or SMTP, add your own link and `List-Unsubscribe` headers. See [Headers and metadata](/docs/email-api/headers-and-metadata/#add-list-unsubscribe-to-bulk-mail).

## Update your API calls

Elastic Email's `POST /v4/emails/transactional` becomes `POST /v2/emails`. The body is flat, field names are lowercase, and the key moves to an `Authorization` header:

```bash title="Before: Elastic Email"
curl https://api.elasticemail.com/v4/emails/transactional \
  -H "X-ElasticEmail-ApiKey: $ELASTICEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Recipients": { "To": ["ada@example.com"] },
    "Content": {
      "From": "Acme <hello@acme.com>",
      "Subject": "Your receipt",
      "Body": [
        { "ContentType": "HTML", "Content": "<p>Thanks for your order.</p>" },
        { "ContentType": "PlainText", "Content": "Thanks for your order." }
      ]
    }
  }'
```

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

| Elastic Email (API v4) | Emailit |
| --- | --- |
| `X-ElasticEmail-ApiKey` header | `Authorization: Bearer secret_…` |
| `Content.From` | `from` |
| `Recipients.To`, `CC`, `BCC` | `to`, `cc`, `bcc`, up to 50 each |
| `Content.ReplyTo` | `reply_to` |
| `Content.Subject` | `subject` |
| `Content.Body[]` with `ContentType` `HTML` and `PlainText` | `html` and `text` |
| `Content.Headers` | `headers` |
| `Content.Attachments[]` with `BinaryContent`, `Name`, `ContentType` | `attachments[]` with `content`, `filename`, `content_type` |
| `Content.AttachFiles` (files uploaded earlier) | `attachments[]` with a `url` that Emailit downloads |
| `Content.TemplateName` | `template`, a template alias or ID |
| `Content.Merge` | `variables` |
| `Options.ChannelName`, `Content.Postback` | `meta`, returned in webhook events |
| `Options.TrackOpens`, `Options.TrackClicks` | `tracking: { "loads": true, "clicks": true }` |
| `Options.TimeOffset` (minutes) | `scheduled_at` (ISO 8601 or plain English) |
| `Options.PoolName` | Not needed. A dedicated IP sends all of its workspace's email. |
| `Content.Utm` | Add UTM parameters to your links. Campaigns add them for you. |
| `POST /v4/emails` with `Recipients[].Fields` (bulk merge) | One request per recipient, each with its own `variables` |
| `Idempotency-Key` header | `Idempotency-Key` header, kept for 24 hours |
| Response with `TransactionID` and `MessageID` | `200` with `id` (`em_…`), `status: "accepted"` and, for several recipients, `ids` with one ID each |

If you still use API v2 (`/v2/email/send` with an `apikey` parameter), map its form fields the same way: `from` and `fromName` become `from`, `bodyHtml` and `bodyText` become `html` and `text`, `merge_*` fields become `variables`, and `template` becomes `template`. In v2, every address in `to` gets a separate message, like Bcc. In Emailit, `to` recipients see each other in the `To` header, so send one request per recipient to keep them apart. See [Send an email](/docs/email-api/send-email/).

## Switch SMTP settings

| Setting | Elastic Email | Emailit |
| --- | --- | --- |
| Host | `smtp.elasticemail.com` | `smtp.emailit.com` |
| Port | `2525`, `587` or `25` (STARTTLS), `465` (TLS) | `587`, `2587`, `2525` or `25` (STARTTLS), `465` (TLS) |
| Username | The SMTP credential's name, an email address | `emailit` |
| Password | The SMTP credential's token | Your Emailit API key |

Emailit doesn't read Elastic Email's control headers, such as `X-ElasticEmail-Channel`, `X-ElasticEmail-Postback`, `IsTransactional`, `trackopens` or `trackclicks`. Remove them, and set tracking on the domain instead. See [SMTP settings](/docs/smtp/settings/).

## Map webhook events

| Elastic Email notification | Emailit event |
| --- | --- |
| `Sent` (the recipient's server accepted the message) | `email.delivered` |
| `Opened` | `email.loaded` |
| `Clicked` | `email.clicked` |
| `Error` | `email.bounced` for permanent failures. Temporary failures send `email.attempted` while Emailit retries. |
| `AbuseReport` | `email.complained` |
| `Unsubscribed` | `email.unsubscribed`, for campaign email only |
| Inbound route that notifies a URL | `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, and `email.suppressed` when a `recipient` suppression blocks an address. See [Event types](/docs/webhooks/event-types/).

The request format changes:

- Elastic Email sends one event per request, in the query string or as a flat JSON object. Emailit posts a JSON array of up to 100 events, so loop over the body.
- The event name moves from `status` to `type`, and the email is in `data.object`. Use `data.object.id`, the `em_` ID from the send response, instead of `messageid`, and `data.object.to` instead of `to`. Your `meta` values, which replace `channel` and `postback`, 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.
- Emailit signs every request. Verify `X-Emailit-Signature`, the hex HMAC-SHA256 of `<timestamp>.<raw body>`, against `X-Emailit-Timestamp` and your `whsec_` secret. Elastic Email's optional signing also uses `whsec_` secrets, but it signs a different string, so update your verification code. 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 addresses Elastic Email blocks, from **Suppressions** in the dashboard or with the API (`/v4/suppressions/bounces`, `/complaints` and `/unsubscribes`).

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

   | Elastic Email status | Emailit type |
   | --- | --- |
   | Invalid (`Bounced`) | `recipient` |
   | Complaint (`Abuse`) | `recipient` |
   | Unsubscribed | `unsubscribe`, which stops campaigns but still lets transactional email through. Use `recipient` to block all email. |

```csv
email,type,reason
old-address@example.com,recipient,elastic email bounced
left@example.com,unsubscribe,elastic email unsubscribed
```

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.

See [Manage suppressions](/docs/suppressions/manage/).

## Move contacts and campaigns

Export your contacts from **Contacts** (select them, then **More actions > Export**) or with `POST /v4/contacts/export`, and export each list you send campaigns to. Then bring them over by status:

| Elastic Email status | Where it goes |
| --- | --- |
| Engaged, Active | Import into the matching audience in **Email Marketing → Contacts** with **Import**. |
| Transactional | Leave them out of audiences. They never subscribed to your marketing email. |
| Invalid, Complaint, Unsubscribed | The suppression list, as above. |
| Inactive, Stale, Not Confirmed | Leave them out. |

Create [custom fields](/docs/contacts/custom-fields/) for your contact fields before you import, and split files into parts of up to 2,500 rows. The import adds everyone in the file as subscribed, so only import people who should get your campaigns. See [Import and export contacts](/docs/contacts/import-export/).

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

## Move templates

Copy each template's HTML with **Edit as HTML** in Elastic Email, or get it with `GET /v4/templates/{name}`, which returns it in `Body`. Import it in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/), and use the template name as the alias if it fits the alias format of lowercase letters, numbers, `-` and `_`.

Elastic Email merge fields use single braces, and Temple uses double braces. Single-brace fields left in a template are sent as plain text, so convert all of them:

| Elastic Email | Emailit (Temple) |
| --- | --- |
| `{firstname}`, `{lastname}`, `{email}` | `{{first_name}}`, `{{last_name}}`, `{{email}}` in campaigns. In API sends, the names you pass in `variables`. |
| `{firstname:friend}` | `{{first_name\|"friend"}}` |
| `{company}` or another custom field | `{{cf.company}}` in campaigns |
| `{unsubscribe}` | `{{unsubscribe_url}}` in campaigns |
| `{contactprofile}` | `{{manage_subscriptions_url}}` in campaigns |
| `{view}` | `{{webview_url}}` in campaigns |
| `{accountaddress}` and other account fields | Write them into the template, or keep them in [global values](/docs/contacts/global-values/) |
| Template scripting in `{{ … }}` | Not supported. Compute values in your code and use `{{#if}}` for conditional content. |

See [Merge tags](/docs/campaigns/merge-tags/) and [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 Elastic Email's `api._domainkey` DKIM record, its `tracking` CNAME or a custom bounce domain. Keep your DMARC record. See [DNS records](/docs/domains/dns-records/).

After the cutover, remove the Elastic Email DKIM and tracking records and `include:_spf.elasticemail.com` from your SPF record. If you receive mail with Elastic Email inbound routes, move it to an Emailit [inbound subdomain](/docs/inbound/set-up/) first. Emailit receives on a subdomain, such as `inbound.acme.com`, so the receiving addresses change.

## 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/elastic-email/
