Guide
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 first for the overall order and how to run both providers in parallel.
Concepts
| Elastic Email | Emailit |
|---|---|
| Account and subaccounts | Account and workspaces. Each workspace has its own domains, keys, members and credits. |
| API keys with access levels | 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. Single sender addresses aren’t available. |
| Channels and postback values | meta |
| Templates, addressed by name | Templates with an alias and versions |
| Merge fields and template scripting | Temple: variables, defaults and conditionals |
| HTTP web notifications | Webhooks |
| Inbound routes | Inbound email |
| Suppressions and blocking contact statuses | Suppressions |
| Contacts and lists | Contacts and audiences |
| Segments | Pick and exclude audiences in each campaign. Segments are in alpha and open to the Emailit team only. |
| Campaigns and automations | Campaigns and automations (beta) |
| Forms | Forms (early access), or an audience’s subscribe URL |
| Email verification | Email verification |
| Private IPs and IP pools | 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 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.
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:
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." }
]
}
}'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.
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.
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} |
Emailit also sends email.accepted when the API accepts an email, and email.suppressed when a recipient suppression blocks an address. See 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
statustotype, and the email is indata.object. Usedata.object.id, theem_ID from the send response, instead ofmessageid, anddata.object.toinstead ofto. Yourmetavalues, which replacechannelandpostback, 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. - Emailit signs every request. Verify
X-Emailit-Signature, the hex HMAC-SHA256 of<timestamp>.<raw body>, againstX-Emailit-Timestampand yourwhsec_secret. Elastic Email’s optional signing also useswhsec_secrets, but it signs a different string, so update your verification code. 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 addresses Elastic Email blocks, from Suppressions in the dashboard or with the API (
/v4/suppressions/bounces,/complaintsand/unsubscribes). -
Build one CSV with the columns
email,type,reason:Elastic Email status Emailit type Invalid ( Bounced)recipientComplaint ( Abuse)recipientUnsubscribed unsubscribe, which stops campaigns but still lets transactional email through. Userecipientto block all email.email,type,reason old-address@example.com,recipient,elastic email bounced left@example.com,unsubscribe,elastic email unsubscribed -
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.
See Manage suppressions.
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 MarketingContacts 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 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.
Recreate your campaigns and automations in Email MarketingCampaigns 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 MarketingTemplates or create it with the Templates API, 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 |
Template scripting in {{ … }} |
Not supported. Compute values in your code and use {{#if}} for conditional content. |
See Merge tags and Temple.
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 Elastic Email’s api._domainkey DKIM record, its tracking CNAME or a custom bounce domain. Keep your DMARC record. See 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 first. Emailit receives on a subdomain, such as inbound.acme.com, so the receiving addresses change.
Next steps
- Go-live checklist
- Set up webhooks
- Priority migration: let Emailit engineers do the move with you