Migrer depuis un autre fournisseur

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 suppressions
4. Basculer les webhooks vers notre vocabulaire d'événements
5. Vérifier avec le sandbox d'e-mails avant la bascule

1. Adapter l'appel d'envoi

• 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 supprimés sont rejetés, de façon visible. Une adresse supprimée 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 supprimés, 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

3. Importer les suppressions

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

• 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.

4. Basculer les webhooks

5. Vérifier dans le sandbox 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 suppressions, 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 supprimé 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.

Migrer depuis un fournisseur spécifique

• 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 bounces/complaints/unsubscribes
• 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 suppressions dont la temporaire reste en arrière, 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