Migrate from Amazon SES

This guide maps Amazon SES concepts, API calls, event notifications, 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

SES calls are signed with your AWS credentials, so you usually make them through an AWS SDK. With Emailit, you send a JSON request with an API key, or use the Emailit SDK for your language. In Node.js:

import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';

const ses = new SESv2Client({ region: 'eu-west-1' });

await ses.send(new SendEmailCommand({
  FromEmailAddress: 'Acme <hello@acme.com>',
  Destination: { ToAddresses: ['ada@example.com'] },
  Content: {
    Simple: {
      Subject: { Data: 'Your receipt' },
      Body: {
        Text: { Data: 'Thanks for your order.' },
        Html: { Data: '<p>Thanks for your order.</p>' },
      },
    },
  },
}));

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Your receipt',
  text: 'Thanks for your order.',
  html: '<p>Thanks for your order.</p>',
});

Emailit also supports scheduling with scheduled_at and safe retries with an Idempotency-Key header, which SES doesn’t offer on send. See Send an email.

Switch SMTP settings

Emailit doesn’t read SES headers such as X-SES-CONFIGURATION-SET. Remove them. See SMTP settings.

Map event notifications

SES publishes events through configuration sets to SNS, EventBridge or Firehose. Emailit sends them directly to your HTTPS endpoint as webhooks, so there’s no topic to subscribe to or confirm.

The payload changes too:

• Each Emailit request is a JSON array of up to 100 events, with the name in type and the email in data.object.
• Use data.object.id, the em_ ID from the send response, instead of the SES messageId. Your meta values are in data.object.meta.
• Instead of checking SNS message signatures, verify X-Emailit-Signature against X-Emailit-Timestamp and 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. Export the SES account-level suppression list with the AWS CLI. If the output includes a NextToken, repeat the command with --next-token until you have every page.

   Terminal

   aws sesv2 list-suppressed-destinations --output json \
     | jq -r '(["email","type","reason"] | @csv),
              (.SuppressedDestinationSummaries[] | [.EmailAddress, "recipient", ("ses " + .Reason)] | @csv)' \
     > suppressions.csv

   This writes a CSV with the columns email,type,reason. Every row uses the type recipient, which blocks API, SMTP and campaign sends to the address.

2. If you keep your own list of bounces and complaints from SNS notifications, add those addresses too.

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.

See Manage suppressions.

Move templates

Get each template with aws sesv2 get-email-template --template-name <name>, then import its HTML in Email Marketing›Templates or create it with the Templates API. Use the SES template name as the Emailit alias, if it fits the alias format of lowercase letters, numbers, - and _.

SES templates use Handlebars-style tags. Temple covers the common parts:

Temple never escapes HTML, so escape user input before you pass it. See Temple.

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 the SES Easy DKIM CNAMEs or a custom MAIL FROM subdomain. Keep your DMARC record. See DNS records.

After the cutover, remove the SES DKIM CNAMEs and the custom MAIL FROM records, and delete the identities in SES. If you receive mail with SES receipt rules, move it to an Emailit inbound subdomain first.

Next steps

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