Migrer depuis Amazon SES

Ce guide fait correspondre les concepts, les appels API, les notifications d’événements, les adresses bloquées et les modèles d’Amazon SES à leurs équivalents dans Emailit. Lisez d’abord Migrer vers Emailit pour l’ordre général et la façon de faire fonctionner les deux fournisseurs en parallèle.

Concepts

Mettre à jour vos appels API

Les appels SES sont signés avec vos identifiants AWS : vous les effectuez donc généralement via un SDK AWS. Avec Emailit, vous envoyez une requête JSON avec une clé API, ou vous utilisez le SDK Emailit de votre langage. En 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 prend aussi en charge la programmation avec scheduled_at et les relances sûres avec un en-tête Idempotency-Key, ce que SES ne propose pas à l’envoi. Consultez Envoyer un e-mail.

Changer les paramètres SMTP

Emailit ne lit pas les en-têtes SES comme X-SES-CONFIGURATION-SET. Supprimez-les. Consultez Paramètres SMTP.

Faire correspondre les notifications d’événements

SES publie les événements via les configuration sets vers SNS, EventBridge ou Firehose. Emailit les envoie directement à votre endpoint HTTPS sous forme de webhooks : il n’y a donc aucun topic auquel s’abonner ni aucun abonnement à confirmer.

Le payload change aussi :

• Chaque requête Emailit est un tableau JSON de 100 événements au maximum, avec le nom dans type et l’e-mail dans data.object.
• Utilisez data.object.id, l’ID em_ de la réponse d’envoi, au lieu du messageId de SES. Vos valeurs meta se trouvent dans data.object.meta.
• Au lieu de vérifier les signatures des messages SNS, vérifiez X-Emailit-Signature à l’aide de X-Emailit-Timestamp et de votre secret whsec_. Consultez Signature des requêtes.

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);
}

Transférer les adresses bloquées

1. Exportez la liste de suppression SES au niveau du compte avec l’AWS CLI. Si la sortie contient un NextToken, répétez la commande avec --next-token jusqu’à obtenir toutes les pages.

   Terminal

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

   Cette commande produit un CSV avec les colonnes email,type,reason. Chaque ligne utilise le type recipient, qui bloque les envois par l’API, par SMTP et par les campagnes vers l’adresse.

2. Si vous tenez votre propre liste de rebonds et de plaintes issus des notifications SNS, ajoutez aussi ces adresses.

3. Dans Email API›Suppressions, sélectionnez Import et chargez le fichier. Chaque fichier peut contenir 10 000 lignes et peser 8 Mo au maximum. Les doublons sont ignorés.

Consultez Gérer les adresses bloquées.

Transférer les modèles

Récupérez chaque modèle avec aws sesv2 get-email-template --template-name <name>, puis importez son HTML dans Email Marketing›Templates ou créez-le avec l’API des modèles. Utilisez le nom du modèle SES comme alias Emailit, s’il respecte le format des alias : lettres minuscules, chiffres, - et _.

Les modèles SES utilisent des balises de type Handlebars. Temple couvre les usages courants :

Temple n’échappe jamais le HTML : échappez les saisies des utilisateurs avant de les transmettre. Consultez Temple.

Modifier le DNS

Ajoutez votre domaine dans Email API›Domains et publiez les enregistrements Emailit. Ils utilisent leurs propres noms (emailit._domainkey, emailit.<domain>, et éventuellement go et inbound) : ils n’entrent donc pas en conflit avec les CNAME Easy DKIM de SES ni avec un sous-domaine MAIL FROM personnalisé. Conservez votre enregistrement DMARC. Consultez Enregistrements DNS.

Après la bascule, supprimez les CNAME DKIM de SES et les enregistrements MAIL FROM personnalisés, puis supprimez les identités dans SES. Si vous recevez des e-mails avec des règles de réception SES, déplacez-les d’abord vers un sous-domaine de réception Emailit.

Étapes suivantes

• Liste de contrôle avant la mise en production
• Configurer des webhooks
• Migration prioritaire : laissez les ingénieurs d’Emailit effectuer la migration avec vous