Migrer depuis Mailgun

Ce guide fait correspondre les concepts, les appels API, les webhooks, les adresses bloquées et les modèles de Mailgun à 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/<domain>/messages de Mailgun reçoit des champs de formulaire avec une authentification basique. Le POST /v2/emails d’Emailit reçoit du JSON avec un jeton bearer :

curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v3/mg.acme.com/messages \
  -F from='Acme <hello@mg.acme.com>' \
  -F to='ada@example.com' \
  -F subject='Your receipt' \
  -F text='Thanks for your order.' \
  --form-string html='<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@mg.acme.com>",
    "to": "ada@example.com",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

Si vous envoyiez depuis un sous-domaine comme mg.acme.com, ajoutez exactement ce sous-domaine dans Emailit. Les sous-domaines sont vérifiés séparément du domaine parent. Les hôtes d’API UE et US de Mailgun correspondent tous deux à l’unique endpoint d’Emailit. Consultez Envoyer un e-mail.

Changer les paramètres SMTP

Emailit ne lit pas les en-têtes X-Mailgun-*. Supprimez-les et réglez plutôt le suivi au niveau du domaine. Consultez Paramètres SMTP.

Faire correspondre les événements webhook

Le format des requêtes change :

• Mailgun envoie un événement par requête, avec les détails dans event-data. Emailit envoie un tableau JSON de 100 événements au maximum. Parcourez le tableau avec une boucle.
• 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, pour associer les événements aux messages. Vos valeurs meta se trouvent dans data.object.meta.
• Mailgun signe un horodatage et un jeton à l’intérieur du corps. Emailit signe l’intégralité du corps brut : 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 les listes Bounces, Complaints et Unsubscribes de chaque domaine Mailgun depuis lequel vous envoyez, depuis le panneau de contrôle ou avec l’API de suppressions (/v3/<domain>/bounces, /complaints et /unsubscribes).

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

   CSV

   email,type,reason
   old-address@example.com,recipient,mailgun bounce
   angry@example.com,recipient,mailgun complaint

   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. Les doublons sont ignorés.

Emailit a une seule liste d’adresses bloquées par espace de travail : les adresses de tous vos domaines Mailgun vont donc dans la même liste. Il n’existe pas de liste d’autorisation (allowlist). Consultez Gérer les adresses bloquées.

Transférer les modèles

Copiez le HTML de chaque modèle depuis Mailgun, puis importez-le dans Email Marketing›Templates ou créez-le avec l’API des modèles. Donnez-lui un alias et envoyez-le avec "template": "<alias>" et variables.

Les modèles Mailgun utilisent Handlebars. Temple couvre les usages courants :

Consultez Temple et Importer et exporter des modèles.

Modifier le DNS

Ajoutez chaque 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 l’enregistrement DKIM de Mailgun ni avec son CNAME de suivi email.<domain>. Vous n’avez pas besoin de modifier l’enregistrement SPF de votre domaine racine pour Emailit. Conservez votre enregistrement DMARC. Consultez Enregistrements DNS.

Après la bascule, supprimez les enregistrements DKIM et de suivi de Mailgun, et retirez include:mailgun.org de votre enregistrement SPF. Si vous recevez des e-mails via les routes Mailgun, conservez ses enregistrements MX jusqu’à ce que vous ayez déplacé ce trafic vers la réception Emailit, qui reçoit sur un sous-domaine comme inbound.acme.com.

É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