Migrate from SendGrid

This guide maps SendGrid concepts, API calls, webhooks, suppressions and templates to their Emailit equivalents. Read Migrate to Emailit first for the overall order and how to run both providers in parallel.

Concepts

Update your API calls

SendGrid’s POST /v3/mail/send becomes POST /v2/emails. The request is flatter: there are no personalizations, and addresses are plain strings.

curl https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ada@example.com" }] }],
    "from": { "email": "hello@acme.com", "name": "Acme" },
    "subject": "Your receipt",
    "content": [
      { "type": "text/plain", "value": "Thanks for your order." },
      { "type": "text/html", "value": "<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>"
  }'

Each recipient in an Emailit request becomes its own email with its own ID. To send different variables to different people, which SendGrid does with several personalizations, send one request per recipient. Add an Idempotency-Key header so retries are safe. See Send an email.

Switch SMTP settings

Emailit doesn’t read the X-SMTPAPI header. Remove it, and set tracking on the domain instead. See SMTP settings.

Map webhook events

Like SendGrid, Emailit posts a JSON array of events. The fields differ:

• The event name is in type, and the email is in data.object. Use data.object.id (the em_ ID from the send response) instead of sg_message_id, and data.object.to instead of email.
• Your meta values come back in data.object.meta.
• Emailit signs requests with HMAC-SHA256 instead of SendGrid’s ECDSA public key. Verify X-Emailit-Signature with your whsec_ 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

1. In SendGrid, export your Bounces, Spam Reports, Invalid Emails and Global Unsubscribes, from the suppression pages or with the /v3/suppression/* API endpoints. Blocks are usually temporary, so you can leave them out.

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

   CSV

   email,type,reason
   old-address@example.com,recipient,sendgrid bounce
   angry@example.com,recipient,sendgrid spam report

   Use the type recipient for addresses that must never receive email. It blocks API, SMTP and campaign sends. The types bounce, complaint and unsubscribe only stop campaigns.

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, so split larger lists. Duplicates are skipped.

For group unsubscribes from marketing email, import those people as contacts with unsubscribed set, rather than suppressing them from all email. See Manage suppressions.

Move templates

Export each dynamic template’s HTML from SendGrid, then import it in Email Marketing›Templates or create it with the Templates API. Give each template an alias, such as receipt, and send it with "template": "receipt".

Both use double curly braces, but Temple is smaller than Handlebars:

See Temple and Import and export templates.

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 SendGrid’s domain authentication or link branding CNAMEs. Keep your DMARC record. After the cutover, remove the SendGrid CNAMEs. See DNS records.

If you used Inbound Parse, point the MX record of your parse hostname at Emailit instead. To keep the same hostname, such as parse.acme.com, set the domain’s inbound_key to parse with the API. See Set up inbound.

Next steps

• Go-live checklist
• Set up webhooks
• Priority migration: let Emailit engineers do the move with you