# Migrate from SparkPost

> Move from SparkPost (now Bird Email) to Emailit. Convert transmissions and substitution data, swap SMTP_Injection settings, and move event webhooks, suppressions, templates and DNS.

This guide maps SparkPost concepts, API calls, webhooks, suppressions and templates to their Emailit equivalents. SparkPost is now part of Bird and sold as Bird Email, and the SparkPost API at `api.sparkpost.com` still runs. This guide covers that API. Read [Migrate to Emailit](/docs/migrate/) first for the overall order and how to run both providers in parallel.

## Concepts

| SparkPost | Emailit |
| --- | --- |
| Primary account and subaccounts | Account and [workspaces](/docs/workspaces/). Each workspace has its own domains, keys, members and credits. |
| US and EU accounts, on separate API hosts | One API host, `api.emailit.com` |
| API keys with grants | [API keys](/docs/developers/api-keys/): **Full Access**, or **Sending Only** optionally restricted to one domain |
| Sending domains | [Sending domains](/docs/domains/) |
| Bounce domains | The return path `emailit.<your domain>`, which every domain has |
| Tracking domains | [Tracking subdomain](/docs/tracking/), such as `go.acme.com` |
| Transmissions | [Emails](/docs/email-api/), one request per message |
| Stored recipient lists | [Audiences](/docs/audiences/) and [campaigns](/docs/campaigns/) |
| Templates and snippets | [Templates](/docs/templates/) with an alias and versions. There are no snippets. |
| Event webhooks | [Webhooks](/docs/webhooks/) |
| Inbound domains and relay webhooks | [Inbound email](/docs/inbound/) |
| Suppression list | [Suppressions](/docs/suppressions/) |
| `metadata`, `tags`, `campaign_id` | `meta` |
| `options.sandbox` | No test mode. New workspaces are in [sandbox mode](/docs/workspaces/production-access/) and deliver only to workspace members. |
| IP pools | [Dedicated IPs](/docs/deliverability/dedicated-ips/) on request |

## Update your API calls

SparkPost's `POST /api/v1/transmissions` becomes `POST /v2/emails`. The content moves to the top level, and the recipients become `to`, `cc` and `bcc`:

```bash title="Before: SparkPost"
curl https://api.sparkpost.com/api/v1/transmissions \
  -H "Authorization: $SPARKPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [{ "address": { "email": "ada@example.com" } }],
    "content": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "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>"
  }'
```

| SparkPost | Emailit |
| --- | --- |
| `Authorization: `, without `Bearer` | `Authorization: Bearer secret_…` |
| `content.from`, a string or `{ email, name }` | `from: "Name "` |
| `recipients[].address` | `to`, a string or an array of up to 50 addresses |
| Cc and Bcc as extra recipients with `header_to` and a `CC` header | `cc` and `bcc` |
| `content.reply_to` | `reply_to` |
| `content.subject`, `content.text`, `content.html` | `subject`, `text`, `html` |
| `content.headers` | `headers` |
| `content.attachments[]` with `name`, `type`, `data` | `attachments[]` with `filename`, `content_type`, `content` |
| `content.inline_images[]` | `attachments[]` with a `content_id`, referenced as `cid:` in the HTML |
| `content.template_id` | `template`: an alias sends the published version, and a `tem_` ID sends that exact version, draft or not |
| `substitution_data` | `variables` |
| `metadata`, `recipients[].tags`, `campaign_id` | `meta`, an object of string values, returned in webhook events |
| `options.open_tracking`, `options.click_tracking` | `tracking: { "loads": true, "clicks": true }` |
| `options.start_time` (up to 3 days ahead) | `scheduled_at` (ISO 8601 or plain English) |
| `options.transactional` | Not needed. API email never gets `List-Unsubscribe` headers unless you add them. |
| `content.email_rfc822` | Send the MIME message through the [SMTP relay](/docs/smtp/) |
| `recipients: { "list_id": "…" }` | A [campaign](/docs/campaigns/) to an audience |
| `Idempotency-Key` header | `Idempotency-Key` header, kept for 24 hours |
| Response with the transmission `id` and recipient counts | `200` with `id` (`em_…`), `status: "accepted"` and, for several recipients, `ids` with one ID each |

SparkPost sends a separate message to each recipient of a transmission, and nobody sees the other addresses. In Emailit, everyone in `to` and `cc` appears in the headers of every copy. To keep recipients apart, or to give each one their own `substitution_data`, send one request per recipient. You get the email IDs right away, instead of finding message IDs in later events. See [Send an email](/docs/email-api/send-email/).

## Switch SMTP settings

| Setting | SparkPost | Emailit |
| --- | --- | --- |
| Host | `smtp.sparkpostmail.com`, or `smtp.eu.sparkpostmail.com` | `smtp.emailit.com` |
| Port | `587` or `2525` (STARTTLS) | `587`, `2587`, `2525` or `25` (STARTTLS), `465` (TLS) |
| Username | `SMTP_Injection` | `emailit` |
| Password | An API key with the **Send via SMTP** permission | Your Emailit API key |

Emailit doesn't read the `X-MSYS-API` header. Remove it. Put Cc and Bcc addresses in the message as normal recipients, set tracking on the domain, and use the API when you need metadata. See [SMTP settings](/docs/smtp/settings/).

## Map webhook events

| SparkPost event | Emailit event |
| --- | --- |
| `injection` | `email.accepted` (API only) |
| `delivery` | `email.delivered` |
| `delay` | `email.attempted` |
| `bounce`, `out_of_band` | `email.bounced` |
| `policy_rejection` | `email.suppressed` when the address has a `recipient` suppression |
| `generation_failure`, `generation_rejection` | No event. Problems such as an unknown template are errors in the API response. |
| `spam_complaint` | `email.complained` |
| `open`, `initial_open` | `email.loaded` |
| `click` | `email.clicked` |
| `list_unsubscribe`, `link_unsubscribe` | `email.unsubscribed`, for campaign email only |
| Relay webhook | `email.received`, then fetch the content with [`GET /emails/{id}`](/docs/api-reference/emails/get/) |

The request format changes:

- Both post a JSON array of events. SparkPost wraps each event in `msys` and a class such as `message_event`. Emailit puts the name in `type` and the email in `data.object`, with up to 100 events per request.
- Use `data.object.id`, the `em_` ID from the send response, instead of `message_id` and `transmission_id`, and `data.object.to` instead of `rcpt_to`. Your `meta` values, which replace `rcpt_meta` and `rcpt_tags`, 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.
- SparkPost protects webhooks with basic authentication or OAuth 2.0, without a signature. Emailit signs every request: verify `X-Emailit-Signature` against `X-Emailit-Timestamp` and your `whsec_` secret. 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 suppression list with `GET /api/v1/suppression-list?per_page=10000&cursor=initial`, and follow the cursor until you have every page. It includes your subaccounts' entries, each with its `subaccount_id`.

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

   | SparkPost entry | Emailit type |
   | --- | --- |
   | `transactional`, or both types | `recipient`, which blocks API, SMTP and campaign sends |
   | `non_transactional` only | `unsubscribe`, which stops campaigns but still lets transactional email through |
   | `open_tracking` | Leave it out. It doesn't block sending. |

```csv
email,type,reason
old-address@example.com,recipient,sparkpost bounce rule
left@example.com,unsubscribe,sparkpost unsubscribe link
```

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 subaccounts, split the file by subaccount and import each part into the matching workspace. See [Manage suppressions](/docs/suppressions/manage/).

## Move templates

Get each published template with `GET /api/v1/templates/{id}?draft=false`, which returns `content.html`, `content.text` and `content.subject`. Import it in **Email Marketing → Templates** or create it with the [Templates API](/docs/api-reference/templates/create/), and use the SparkPost template ID as the alias if it fits the alias format of lowercase letters, numbers, `-` and `_`.

Convert the SparkPost template language to Temple:

| SparkPost | Emailit (Temple) |
| --- | --- |
| `{{name}}`, `{{order.total}}` | The same |
| `{{address.name}}`, `{{address.email}}` (the recipient) | Pass them in `variables`, for example as `name` and `email` |
| `{{{html_block}}}` | `{{html_block}}`. Temple never escapes HTML, so escape user input yourself. |
| `{{name or 'Customer'}}` | `{{name\|"Customer"}}` |
| `{{if plan}}…{{else}}…{{end}}` | `{{#if plan}}…{{else}}…{{/if}}` |
| `{{if plan == 'pro'}}`, `{{elseif}}`, `and`, `or` | Not supported. Pass a boolean such as `is_pro` and use `{{#if is_pro}}`. |
| `{{each items}}…{{end}}` | Not supported. Render the list in your code and pass it as one variable. |
| `render_snippet()`, `render_dynamic_content()` | Not supported. Put the content into the template, or pass it as a variable. |
| `substitution_data` | `variables` |

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 SparkPost's DKIM record (a selector such as `scph0316._domainkey`), its bounce domain CNAME or its tracking domain CNAME. Keep your DMARC record. See [DNS records](/docs/domains/dns-records/).

If your SparkPost tracking domain or inbound domain already uses the name `go` or `inbound`, choose other names for Emailit with `tracking_key` and `inbound_key`. See [Custom tracking domain](/docs/tracking/custom-tracking-domain/) and [Set up inbound](/docs/inbound/set-up/).

After the cutover, remove the SparkPost DKIM, bounce and tracking records. If you receive mail with relay webhooks, move it to an Emailit inbound subdomain first, then remove SparkPost's `rx1`, `rx2` and `rx3` MX records.

## 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/sparkpost/
