Skip to content
Docs

Guide

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.

Updated Oct 23, 2026

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 first for the overall order and how to run both providers in parallel.

Concepts

SparkPost Emailit
Primary account and subaccounts Account and 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: Full Access, or Sending Only optionally restricted to one domain
Sending domains Sending domains
Bounce domains The return path emailit.<your domain>, which every domain has
Tracking domains Tracking subdomain, such as go.acme.com
Transmissions Emails, one request per message
Stored recipient lists Audiences and campaigns
Templates and snippets Templates with an alias and versions. There are no snippets.
Event webhooks Webhooks
Inbound domains and relay webhooks Inbound email
Suppression list Suppressions
metadata, tags, campaign_id meta
options.sandbox No test mode. New workspaces are in sandbox mode and deliver only to workspace members.
IP pools 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:

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>"
    }
  }'
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: <API key>, without Bearer Authorization: Bearer secret_…
content.from, a string or { email, name } from: "Name <email>"
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
recipients: { "list_id": "…" } A campaign 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.

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.

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}

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.
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 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.

If you used subaccounts, split the file by subaccount and import each part into the matching workspace. See Manage suppressions.

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 MarketingTemplates or create it with the Templates API, 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 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 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.

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 and Set up inbound.

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

Was this page helpful?

Thanks for the feedback.

Thanks, we read every message.