Guide
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 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:
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>"
}
}'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
msysand a class such asmessage_event. Emailit puts the name intypeand the email indata.object, with up to 100 events per request. - Use
data.object.id, theem_ID from the send response, instead ofmessage_idandtransmission_id, anddata.object.toinstead ofrcpt_to. Yourmetavalues, which replacercpt_metaandrcpt_tags, are indata.object.meta. - For
email.loadedandemail.clicked,data.objectis the load or the click. Usedata.object.email_idfor the email’s ID, anddata.object.email.rcpt_toanddata.object.email.metafor the recipient and yourmetavalues. - SparkPost protects webhooks with basic authentication or OAuth 2.0, without a signature. Emailit signs every request: verify
X-Emailit-SignatureagainstX-Emailit-Timestampand yourwhsec_secret. See Request signature.
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
-
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 itssubaccount_id. -
Build one CSV with the columns
email,type,reason:SparkPost entry Emailit type transactional, or both typesrecipient, which blocks API, SMTP and campaign sendsnon_transactionalonlyunsubscribe, which stops campaigns but still lets transactional email throughopen_trackingLeave it out. It doesn’t block sending. email,type,reason old-address@example.com,recipient,sparkpost bounce rule left@example.com,unsubscribe,sparkpost unsubscribe link -
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
- Go-live checklist
- Set up webhooks
- Priority migration: let Emailit engineers do the move with you