Sign inGet Started

Migrer depuis un autre fournisseur

Suivez ce guide pour transférer vos e-mails de production depuis un autre fournisseur. Adaptez la requête d'envoi, publiez les enregistrements DNS, importez les suppressions, traduisez les événements webhook, et testez l'intégration avant de diriger le trafic de production vers Bird.

La checklist de migration :

  1. Adapter votre appel d'envoi vers POST /v1/email/messages
  2. Rediriger vos domaines d'envoi et le DNS
  3. Importer votre liste de suppression
  4. Basculer les webhooks vers notre vocabulaire d'événements
  5. Vérifier avec le sandbox d'e-mails avant la bascule

Les étapes 1, 3 et 4 dépendent du fournisseur que vous quittez. Votre guide fournisseur contient le mapping champ par champ du payload, l'emplacement d'export de votre liste de suppression, et la table de correspondance des noms d'événements webhook.

1. Adapter l'appel d'envoi

Pour envoyer un message individuel, utilisez l'endpoint POST /v1/email/messages. Vous construisez un payload JSON plat (pas de wrapper personalizations, pas d'assemblage MIME) avec from, les tableaux to/cc/bcc, subject, html et/ou text, une liste reply_to optionnelle, et headers pour les en-têtes d'e-mail personnalisés. Un envoi réussi renvoie 202 Accepted avec un identifiant de message préfixé par em_. Les résultats de livraison arrivent de façon asynchrone via les webhooks et les endpoints de lecture. Le payload complet, avec chaque limite de champ et valeur par défaut, se trouve dans Envoi d'e-mails. Le mapping champ par champ depuis votre payload actuel est dans votre guide fournisseur. Si votre application envoie via SMTP aujourd'hui, vous n'avez peut-être pas besoin de porter l'appel : nous acceptons la soumission SMTP dans le même pipeline, ce qui réduit cette étape à un changement d'identifiants.

Utilisez tags pour les dimensions de filtrage dans les listes de messages, les analytics et les agrégations du tableau de bord. Utilisez metadata pour le contexte structuré que Bird stocke sur le message et renvoie lors des lectures API. Les événements webhook peuvent aussi contenir ce contexte, mais les événements de désinscription peuvent renvoyer des valeurs null. Consultez Tags vs metadata pour les limites.

Avant de porter votre code, tenez compte de ces différences :

  • La planification, les templates stockés et les pièces jointes se portent directement. Utilisez scheduled_at pour l'envoi planifié. Utilisez template au lieu du contenu en ligne pour les templates stockés. Associez les fichiers au tableau attachments.
  • Les destinataires sur la liste de suppression sont rejetés, de façon visible. Une adresse sur la liste de suppression reçoit tout de même un recipient_id et apparaît dans la liste des destinataires du message avec le statut rejected et un événement email.rejected (rejection_reason: recipient_suppressed), jamais un rejet silencieux. Même quand tous les destinataires sont sur la liste de suppression, la requête est acceptée avec un 202. Chaque destinataire revient comme rejeté. Voir Suppressions.
  • Définissez category: "transactional" pour les e-mails opérationnels. Un envoi est par défaut marketing, et la catégorie contrôle la politique de suppression : marketing bloque sur les plaintes et les désinscriptions, transactional passe outre. Les newsletters et les campagnes sont gérées correctement par la valeur par défaut. Marquez les reçus, les réinitialisations de mot de passe et les e-mails opérationnels similaires comme transactional pour qu'ils ne soient pas bloqués par une désinscription.

2. Rediriger les domaines et le DNS

Enregistrez chaque domaine d'envoi avec POST /v1/email/domains ou dans Email > Domains, puis publiez les enregistrements depuis dns_records. DKIM, le CNAME du return-path et une politique DMARC conditionnent l'envoi. Un enregistrement DMARC existant, y compris sur un domaine parent, suffit. Le CNAME de tracking conditionne uniquement le suivi des ouvertures et des clics avec votre marque. Domaines d'envoi couvre les enregistrements, le cycle de vie de la vérification et le modèle régional. Utilisez le DNS record splitter si votre fournisseur exige une valeur DKIM fractionnée, et le générateur de politique DMARC si vous avez besoin d'une politique.

Un enregistrement que la plupart des fournisseurs vous demandent de créer est volontairement absent : vous ne publiez pas d'enregistrement SPF sur l'apex de votre domaine. SPF est évalué par rapport au domaine envelope-from, vers lequel le CNAME du return-path pointe chez nous, donc SPF passe et s'aligne sans toucher à votre apex. Si votre ancien fournisseur vous avait fait ajouter un include: à votre enregistrement SPF d'apex, laissez-le en place pendant la transition et supprimez-le après la bascule. Il n'aide ni ne nuit aux e-mails envoyés par notre intermédiaire, et le supprimer libère l'une des 10 résolutions DNS que SPF d'apex autorise. L'explication complète se trouve dans DKIM, SPF & DMARC.

Vous pouvez publier nos enregistrements pendant que ceux de votre ancien fournisseur sont encore actifs. L'enregistrement DKIM utilise un sélecteur qui nous appartient. Les CNAME de return-path et de tracking sont de nouveaux noms d'hôtes que vous choisissez, et votre enregistrement DMARC existant satisfait la condition tel quel. Les deux fournisseurs authentifient en parallèle jusqu'à ce que vous soyez prêt à basculer le trafic. L'état du domaine est régional : enregistrez le domaine dans chaque région depuis laquelle vous envoyez.

3. Importer les suppressions

Transférez votre liste de suppression avant d'envoyer du trafic de production par notre intermédiaire. Sinon, vos premiers envois atteindront des adresses qui ont déjà rebondi ou généré des plaintes chez votre ancien fournisseur, ce qui endommage la réputation que vous essayez de protéger.

Exportez la liste depuis votre fournisseur actuel (votre guide fournisseur indique les endpoints exacts), puis ajoutez chaque adresse ici avec POST /v1/email/suppressions :

Exemple de code
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

Deux points à connaître sur cette méthode d'import :

  • Vous importez une adresse par requête. L'endpoint API de suppressions est un CRUD à entrée unique, donc une grande liste implique une boucle sur les adresses exportées. L'appel est idempotent (201 pour un nouvel enregistrement, 200 avec l'enregistrement existant si l'adresse est déjà supprimée manuellement), donc relancer un import partiel est sans risque.
  • Les adresses importées reçoivent reason: manual, applies_to: all, ce qui bloque toutes les catégories, y compris transactionnelle. C'est plus strict qu'un enregistrement de plainte natif, qui bloque uniquement les envois non transactionnels. Si vous avez besoin du comportement adapté aux catégories pour certaines adresses, consultez la taxonomie des raisons dans Suppressions.

Désormais, les rebonds définitifs créent des suppressions au niveau de l'espace de travail et émettent email_suppression.created, quelle que soit l'attribution à une Brand. Les plaintes sans attribution fiable à une Brand créent elles aussi des suppressions au niveau de l'espace de travail et émettent email_suppression.created. Les plaintes attribuées à une Brand enregistrent des préférences protégées. Les désinscriptions enregistrent des préférences. Abonnez-vous également aux événements de préférence, même pour un espace de travail avec une seule Brand, afin que votre système reflète ces désinscriptions et les consentements accordés ensuite. Les événements email.complained, email.unsubscribed et email.list_unsubscribed au niveau du message restent disponibles. Consultez Email events pour la distinction.

4. Basculer les webhooks

Enregistrez un endpoint avec POST /v1/webhooks et abonnez-le à une liste explicite de types d'événements. Nos noms d'événements suivent resource.action : email.accepted → email.processed → email.delivered sur le chemin nominal, avec email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked, et la paire de désinscription pour couvrir le reste. La correspondance des noms d'événements depuis le vocabulaire de votre fournisseur actuel se trouve dans votre guide fournisseur. Les schémas de payload par événement sont dans la référence des événements.

Corrélez les événements des messages sortants à l'aide de email_id et workspace_id ; les événements du cycle de vie des destinataires contiennent aussi recipient_id. Enregistrez cette correspondance entre message et client au moment de l'envoi. Traitez tags et metadata comme un contexte supplémentaire lorsqu'ils sont présents : email.unsubscribed et email.list_unsubscribed issus des liens de désinscription Bird renvoient des valeurs null pour les envois individuels, même si l'envoi les incluait. Les événements de désinscription des envois groupés peuvent aussi renvoyer null lorsque ce contexte n'est pas disponible.

Utilisez preference.revoked, preference.granted et preference.deleted comme signaux pour actualiser votre copie locale des préférences. Ces événements identifient preference_id et transition_id, avec le périmètre de canal, d'identifiant de contact, de Brand, d'expéditeur et de sujet ; ils ne contiennent ni identifiant de message ni métadonnées d'envoi. Leur timestamp est l'heure d'effet de la déclaration, pas une version de l'enregistrement. Une plainte tardive peut révoquer un consentement groupé accordé plus tard, et des changements différents peuvent avoir le même horodatage. Ne déterminez pas le statut ni la couverture actuels en triant les événements ou en traitant transition_id comme une séquence d'ordre.

Initialisez et maintenez une copie locale complète des préférences dans cet ordre :

  1. Abonnez-vous aux événements de préférence et conservez durablement les notifications reçues avant de lancer la lecture initiale.
  2. Alimentez la copie locale à partir de toutes les pages de la liste des préférences de l'espace de travail, sans filtre de canal, d'identifiant de contact ni de Brand. Cette lecture détecte les désinscriptions existantes qui n'ont jamais généré de notification pour votre endpoint. Conservez pour chaque enregistrement son identifiant, son canal, son identifiant de contact, sa Brand, son expéditeur et son périmètre de sujet.
  3. Traitez les notifications conservées et nouvelles en récupérant la préférence actuelle et en listant toutes les pages pour le canal et l'identifiant de contact concernés. Comparez les périmètres pour tenir compte d'une suppression puis d'une recréation sous un autre identifiant. Rapprochez aussi périodiquement la liste complète et non filtrée de l'espace de travail, y compris les destinataires absents des notifications ou de votre copie locale.

Les lectures peuvent refléter un changement avec du retard : réessayez en cas d'erreur transitoire ou d'état manquant ou plus ancien qu'attendu. Une lecture échouée ou incomplète ne doit jamais lever un blocage local. Ne retirez un enregistrement supprimé qu'après avoir confirmé son absence ; conservez les préférences et les suppressions indépendantes. Cette copie locale converge avec le temps et ne remplace pas les contrôles effectués par Bird au moment de l'envoi.

email_suppression.created identifie les ajouts par suppression_id, workspace_id et email. Il n'existe aucun événement de retrait d'une suppression créée par le client. Pour détecter les retraits effectués dans le tableau de bord ou via API, lisez périodiquement toutes les pages de la liste de suppression de l'espace de travail et rapprochez par identifiant de suppression. Ne retirez aucun enregistrement après une lecture échouée ou partielle ; confirmez l'absence lors d'une lecture ultérieure avant de le retirer. Séparez les enregistrements de suppression des préférences, afin que le retrait d'un blocage ne puisse pas en lever un autre.

Nous signons les livraisons selon la spécification Standard Webhooks, avec trois en-têtes : webhook-id, webhook-timestamp et webhook-signature, et un HMAC-SHA256 sur {id}.{timestamp}.{raw body}. Si vous vérifiez déjà les livraisons Standard Webhooks d'une autre plateforme, le même code de vérification fonctionne ici. Sinon, la procédure de vérification, le calendrier des nouvelles tentatives et les outils de rejeu sont dans Webhooks & events. Les livraisons sont at-least-once et non ordonnées : dédupliquez sur webhook-id. Utilisez les horodatages des événements de message pour afficher la chronologie des messages ; pour les préférences et les suppressions, rapprochez l'état actuel comme décrit ci-dessus.

5. Vérifier dans le sandbox avant la bascule

Avant de basculer le trafic de production, testez l'appel d'envoi porté et le handler d'événements de message avec le sandbox d'e-mails. Les envois sandbox utilisent des adresses magiques sur messagebird.dev et traversent le véritable pipeline de production : même 202, même séquence d'événements, mêmes livraisons webhook signées, sans jamais atteindre une boîte de réception ni affecter votre réputation.

Les signaux du sandbox n'écrivent aucun enregistrement de suppression ni de préférence liée aux plaintes. Testez votre copie locale séparément avec des payloads email_suppression.created, preference.revoked, preference.granted et preference.deleted représentatifs issus des contrats d'événements webhook, y compris avec deux Brands partageant le même destinataire. Incluez ces cas :

  • Une désinscription inchangée est antérieure à l'enregistrement du webhook. L'inventaire initial non filtré la détecte sans notification ; l'inventaire périodique détecte aussi un enregistrement absent de votre copie locale.
  • Une désinscription d'un envoi individuel a des valeurs tags et metadata null ; votre correspondance de messages enregistrée identifie tout de même le client.
  • Une plainte arrive après un consentement groupé plus récent, ou une désinscription plus ancienne portant sur toutes les catégories étend la protection liée aux plaintes sans avancer son horodatage d'effet. Livrez les événements dans l'ordre inverse et vérifiez que le rapprochement conserve le statut révoqué et la couverture actuels.
  • Une préférence est supprimée puis recréée, ou une suppression manuelle est retirée dans le tableau de bord. Le rapprochement retire uniquement les enregistrements dont l'absence est confirmée et conserve les blocages sans rapport.
  • Une actualisation échoue ou renvoie temporairement un état plus ancien. Votre handler réessaie, et le rapprochement périodique répare la copie locale sans lever de blocage lors de la lecture échouée.

Un smoke test minimal avant la bascule :

  1. Envoyez à delivered@messagebird.dev et vérifiez que votre handler traite email.accepted → email.processed → email.delivered.
  2. Envoyez à bounce@messagebird.dev et vérifiez que votre gestion des rebonds se déclenche sur email.bounced (les rebonds simulés n'écrivent pas dans votre liste de suppression, donc l'adresse reste réutilisable).
  3. Envoyez à suppressed@messagebird.dev et vérifiez que vous traitez email.accepted suivi de email.rejected, sans email.processed ni événement de livraison après. C'est la forme que chaque destinataire sur la liste de suppression produit en production ; le détail rejection_reason: recipient_suppressed se trouve sur l'enregistrement du destinataire et les événements API.
  4. Envoyez un message category: "marketing" et confirmez que la catégorie apparaît où vous l'attendez lors de la lecture du message.

Utilisez le sous-adressage +label (bounce+cutover-test@messagebird.dev) pour corréler les cas de test. L'adresse complète apparaît dans vos événements. Une fois le smoke test réussi, basculez le trafic. Dirigez votre application vers nous et conservez le DNS de l'ancien fournisseur jusqu'à ce que vos domaines ici affichent capabilities.sending vérifié. Surveillez les premières heures de livraisons réelles dans le tableau de bord et votre flux webhook.

Migrer depuis un fournisseur spécifique

  • SparkPost : transmissions et SMTP, conversion de templates, suppressions par périmètre, et événements webhook
  • SendGrid : personalizations → payload plat, categories/custom_args → tags/metadata, l'équivalence dropped ↔ email.rejected
  • Mailgun : paramètres o:*/v:*/h:* → champs de premier niveau, export des rebonds, plaintes et désinscriptions
  • Amazon SES : SendEmail v2 → un seul endpoint, configuration sets → flags de tracking par message, SNS → webhooks signés
  • Resend : structure de payload quasi identique, webhooks signés Svix → Standard Webhooks
  • Postmark : destinataires séparés par des virgules → tableaux, exports de suppressions par stream, webhooks non signés → signés
  • Brevo : objets d'adresse → adresses simples, deux blocklists distinctes à exporter, params → template.parameters
  • MailerSend : cinq listes de suppression, dont la liste temporaire n'est pas transférée, personalization → paramètres par envoi
  • Mailjet : le tableau Messages → un payload plat, EventPayload → metadata, export de la blocklist
  • Mandrill : le wrapper message et l'authentification dans le corps → payload plat et authentification par bearer, export de la rejection blacklist

Étapes suivantes

  • Envoi d'e-mails : le payload d'envoi complet, tags vs metadata, le modèle asynchrone 202
  • Domaines d'envoi : enregistrement, cycle de vie de la vérification, configuration multirégion
  • DKIM, SPF & DMARC : ce que chaque enregistrement prouve, et pourquoi SPF sur l'apex n'est pas requis
  • Suppressions : raisons, catégories et API de gestion
  • Webhooks & events : configuration de l'endpoint, vérification Standard Webhooks, réessais et rejeu
  • Events : schémas de payload par événement
  • Sandbox de test : la liste complète des adresses magiques et les procédures pas à pas
  • Référence API : schémas de requête et de réponse pour l'endpoint d'envoi

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.