Migrer depuis Postmark

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

Pour séparer la réputation transactionnelle et la réputation marketing, envoyez-les depuis des domaines ou sous-domaines différents, comme mail.acme.com pour les reçus et news.acme.com pour les newsletters.

Mettre à jour vos appels API

Le POST /email de Postmark avec un X-Postmark-Server-Token devient POST /v2/emails avec un jeton bearer. Les noms de champs passent du PascalCase au snake_case :

curl https://api.postmarkapp.com/email \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -d '{
    "From": "Acme <hello@acme.com>",
    "To": "ada@example.com",
    "Subject": "Your receipt",
    "TextBody": "Thanks for your order.",
    "HtmlBody": "<p>Thanks for your order.</p>",
    "MessageStream": "outbound"
  }'

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

Emailit n’a pas d’endpoint d’envoi par lots. Envoyez une requête par message, avec 50 destinataires au maximum chacune, et 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 les en-têtes X-PM-* comme X-PM-Message-Stream ou X-PM-Tag. Supprimez-les et réglez plutôt le suivi au niveau du domaine. Consultez Paramètres SMTP.

Faire correspondre les événements webhook

Emailit envoie aussi email.accepted quand l’API accepte un e-mail, ce pour quoi Postmark n’a pas de webhook.

Le format des requêtes change :

• Postmark envoie un enregistrement par requête et le nomme dans RecordType. Emailit envoie 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 de MessageID. Vos valeurs meta se trouvent dans data.object.meta.
• Les webhooks Postmark sont généralement protégés par des identifiants d’authentification basique dans l’URL. Emailit signe plutôt chaque requête : 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 adresses bloquées (suppressions) de chaque flux de messages Postmark depuis lequel vous envoyez, depuis la page des suppressions du flux ou avec l’API de dump des suppressions. Incluez les rebonds définitifs (hard bounces), les plaintes pour spam et les blocages manuels.

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

   CSV

   email,type,reason
   old-address@example.com,recipient,postmark hard bounce
   angry@example.com,recipient,postmark spam 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. Pour les personnes qui se sont seulement désinscrites de vos envois broadcast, utilisez le type unsubscribe, qui arrête les campagnes mais laisse passer les e-mails transactionnels.

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

Copiez le HTML de chaque modèle depuis Postmark, layout compris, puis importez-le dans Email Marketing›Templates ou créez-le avec l’API des modèles. Emailit n’a pas de layouts : fusionnez donc le layout et le contenu en un seul modèle. Reprenez l’alias que vous utilisiez dans Postmark pour limiter les modifications de code.

Les modèles Postmark utilisent Mustachio. Temple couvre les valeurs simples et les conditions :

Temple n’échappe jamais le HTML : échappez les saisies des utilisateurs avant de les transmettre. Une valeur manquante produit une chaîne vide, sauf si vous ajoutez une valeur par défaut, comme {{name|"there"}}. 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 l’enregistrement DKIM de Postmark ni avec son CNAME de return-path pm-bounces. Conservez votre enregistrement DMARC. Après la bascule, supprimez les enregistrements Postmark. Consultez Enregistrements DNS.

Si vous traitez les e-mails entrants avec Postmark, déplacez-les vers un sous-domaine de réception Emailit et mettez à jour les adresses que votre application communique. 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