Migrer depuis SendGrid

Ce guide fait correspondre les concepts, les appels API, les webhooks, les adresses bloquées et les modèles de SendGrid à 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

Le POST /v3/mail/send de SendGrid devient POST /v2/emails. La requête est plus plate : il n’y a pas de personalizations, et les adresses sont de simples chaînes.

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>"
  }'

Chaque destinataire d’une requête Emailit devient un e-mail distinct avec son propre ID. Pour envoyer des variables différentes à différentes personnes, ce que SendGrid fait avec plusieurs personalizations, envoyez une requête par destinataire. Ajoutez un en-tête Idempotency-Key pour sécuriser les relances. Consultez Envoyer un e-mail.

Changer les paramètres SMTP

Emailit ne lit pas l’en-tête X-SMTPAPI. Supprimez-le et réglez plutôt le suivi au niveau du domaine. Consultez Paramètres SMTP.

Faire correspondre les événements webhook

Comme SendGrid, Emailit envoie (POST) un tableau JSON d’événements. Les champs diffèrent :

• Le nom de l’événement se trouve dans type, et l’e-mail dans data.object. Utilisez data.object.id (l’ID em_ de la réponse d’envoi) au lieu de sg_message_id, et data.object.to au lieu de email.
• Vos valeurs meta reviennent dans data.object.meta.
• Emailit signe les requêtes avec HMAC-SHA256 au lieu de la clé publique ECDSA de SendGrid. Vérifiez X-Emailit-Signature avec 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. Dans SendGrid, exportez vos Bounces, Spam Reports, Invalid Emails et Global Unsubscribes, depuis les pages Suppressions ou avec les endpoints API /v3/suppression/*. Les Blocks sont généralement temporaires : vous pouvez les laisser de côté.

2. Constituez un seul CSV avec les colonnes email,type,reason :

   CSV

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

   Utilisez le type recipient pour les adresses qui ne doivent jamais recevoir d’e-mail. Il bloque les envois par l’API, par SMTP et par les campagnes. Les types bounce, complaint et unsubscribe n’arrêtent que les campagnes.

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 : découpez donc les listes plus longues. Les doublons sont ignorés.

Pour les désinscriptions de groupe des e-mails marketing, importez ces personnes comme contacts avec unsubscribed activé, plutôt que de les bloquer pour tous les e-mails. Consultez Gérer les adresses bloquées.

Transférer les modèles

Exportez le HTML de chaque modèle dynamique depuis SendGrid, puis importez-le dans Email Marketing›Templates ou créez-le avec l’API des modèles. Donnez à chaque modèle un alias, comme receipt, et envoyez-le avec "template": "receipt".

Les deux utilisent des doubles accolades, mais Temple est plus restreint que Handlebars :

Consultez Temple et Importer et exporter des modèles.

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 de domain authentication ou de link branding de SendGrid. Conservez votre enregistrement DMARC. Après la bascule, supprimez les CNAME de SendGrid. Consultez Enregistrements DNS.

Si vous utilisiez Inbound Parse, faites plutôt pointer vers Emailit l’enregistrement MX de votre nom d’hôte de parsing. Pour conserver le même nom d’hôte, comme parse.acme.com, définissez l’inbound_key du domaine sur parse avec l’API. Consultez Configurer la réception.

É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