Migrer depuis SparkPost

Utilisez ce guide pour transférer l'envoi d'e-mails sortants de SparkPost vers Bird. Suivez la checklist de migration principale, en utilisant les correspondances ci-dessous pour votre intégration HTTP ou SMTP.

Avant de commencer

Vous devez avoir accès à votre compte SparkPost et à vos sous-comptes, au DNS du domaine d'envoi, à la configuration de l'application et au gestionnaire de webhooks. Préparez un espace de travail Bird et une clé API dans la région de votre choix. L'import des désinscriptions nécessite également la permission d'écriture preferences sur la clé.

Inventoriez les expéditeurs, templates, snippets, listes de destinataires, suppressions, envois programmés, pools d'IP et webhooks. Incluez les SDK, les adaptateurs mail de framework, les tâches en arrière-plan et les flux d'e-mails entrants. Notez les nouveaux identifiants de ressource au fur et à mesure de leur création ; les identifiants et identifiants d'authentification SparkPost ne fonctionnent pas dans Bird. Utilisez les SDK Bird pour remplacer un client SparkPost, et vérifiez ses réessais, délais d'attente et pagination.

Si vous utilisez les sous-comptes SparkPost, contactez-nous avant de choisir l'organisation de vos espaces de travail. Confirmez les espaces de travail disponibles, les permissions, les ressources partagées et le workflow de provisionnement des tenants. Une clé API d'espace de travail ne peut pas changer de tenant avec X-MSYS-SUBACCOUNT. Conservez les tenants suspendus et les restrictions d'envoi spécifiques à chaque tenant pendant la migration.

Vérifiez que vos quotas de plan Bird et vos limites de débit couvrent votre volume d'envoi, le nombre de ressources et le trafic de pointe.

Enregistrez vos domaines d'envoi tôt. Conservez le DNS SparkPost fonctionnel et choisissez des noms d'hôte distincts pour le return-path et le tracking si nécessaire. Si l'enregistrement signale un conflit de propriété, contactez le support avant de supprimer un domaine actif.

IP dédiées : Contactez-nous ou votre équipe de compte avant de migrer. Demandez-nous de confirmer si vos IP SparkPost existantes peuvent être transférées vers Bird et convenez de la configuration du pool, du calendrier et de tout warmup nécessaire. Incluez la région de votre compte, les adresses IP, les noms de pool et le volume d'envoi. Gardez vos IP actuelles actives jusqu'à ce que le plan de migration soit confirmé.

Confirmez la sélection du pool et les listes d'autorisation d'IP ou de noms d'hôte des destinataires avant le basculement. L'achat d'une IP ne modifie pas le pool par défaut. Les IP nouvellement achetées peuvent envoyer le surplus via l'infrastructure partagée pendant le warmup, ce qui compte si les destinataires n'acceptent le courrier que depuis des IP spécifiques.

Transmettez ceci à votre agent

Collez ceci dans votre agent de codage dans le dépôt de votre application :

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Faire correspondre l'appel d'envoi

Remplacez POST /api/v1/transmissions par POST /v1/email/messages, ou par POST /v1/email/batches pour les messages indépendants. La vue d'ensemble API de SparkPost liste ses hôtes régionaux et son authentification. Bird utilise https://us1.platform.bird.com ou https://eu1.platform.bird.com, selon la région de votre clé API, avec Authorization: Bearer $BIRD_API_KEY.

Une transmission SparkPost peut générer des e-mails distincts et personnalisés pour ses destinataires. Bird partage le contenu et les paramètres entre les destinataires d'un même envoi. Utilisez un message séparé pour chaque personnalisation, éventuellement regroupé dans un lot. Les envois ne comportant que des destinataires To restent adressés individuellement ; vérifiez les en-têtes visibles lorsque vous ajoutez des copies Cc/Bcc.

Faites correspondre les champs de transmission SparkPost :

Pour les copies To/Cc/Bcc d'un même e-mail, reconstruisez le groupe de destinataires une seule fois. Les adresses affichées de SparkPost peuvent différer des destinataires de livraison ; to, cc et bcc de Bird ajoutent chacun des destinataires de livraison. Copier un en-tête CC de SparkPost dans le cc de chaque message étendu peut envoyer des copies en double. Vérifiez les en-têtes visibles et le nombre de destinataires avant de basculer.

Vérifiez les limites des champs d'envoi, la planification et les règles relatives aux pièces jointes. Mettez à jour les identifiants d'images inline et les références cid: correspondantes pour respecter les règles de Bird. Configurez le chemin de retour et le domaine de suivi sur le domaine.

Les champs d'envoi HTTP de Bird n'incluent pas content.email_rfc822, content.amp_html ou options.inline_css de SparkPost. Reconstruisez les messages bruts avec les champs pris en charge, fournissez des alternatives HTML/texte pour AMP, et insérez le CSS en ligne avant de soumettre le HTML. SMTP analyse et reconstruit les parties de message prises en charge ; validez le MIME reçu si vous dépendez de sa structure exacte. Les paramètres MIME des pièces jointes tels que method pour les calendriers ou charset pour le texte ne sont pas préservés.

Pour les messages API planifiés, Bird fige la version du template, la langue et les paramètres au moment de l'acceptation de la requête. Les modifications ultérieures du template ne mettent pas à jour ce message. Pour le modifier, annulez le message planifié avant le début du traitement, puis soumettez un remplacement. Conservez un groupe d'identifiants de message Bird si vous devez remplacer l'annulation par campagne de SparkPost.

Définissez BIRD_API_KEY sur votre clé Bird. Cet exemple sandbox ne nécessite pas de domaine vérifié et n'atteint aucune boîte de réception réelle. Pour une clé EU, utilisez https://eu1.platform.bird.com :

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Attendez 202 Accepted et un identifiant de message em_. Enregistrez cet identifiant et suivez les résultats par destinataire via les événements. L'acceptation n'établit pas la livraison : un destinataire sur la liste de suppression peut être accepté puis rejeté par la suite. Mettez à jour l'analyse des réponses, la gestion des erreurs et les réessais idempotents avec l'appel d'envoi.

Pour un lot, lisez le tableau data et enregistrez l'ID de chaque message en regard de votre propre enregistrement d'envoi. Bird valide le lot avant de le mettre en file d'attente : un seul message invalide peut entraîner le rejet de la requête entière. Découpez les transmissions volumineuses pour respecter les limites de lot et suivez les règles de nouvel essai de Bird lorsqu'une réponse est ambiguë.

Attribuez à chaque requête ou segment de lot sa propre clé d'idempotence stable. La fenêtre de rejeu de Bird diffère de celle de SparkPost ; conservez les enregistrements d'envoi de votre application au-delà de cette fenêtre pour éviter les doublons lors du basculement ou d'un retour en arrière.

Migrer les expéditeurs SMTP

Utilisez les paramètres de connexion SMTP de Bird, le nom d'utilisateur bird et une clé API avec l'envoi d'e-mails activé. Vérifiez la région, TLS et la configuration de la clé.

Convertissez les options X-MSYS-API de SparkPost avant de supprimer l'en-tête. Définissez les valeurs par défaut de catégorie, tags, suivi et pool dans la configuration SMTP de Bird. Ces paramètres s'appliquent par clé API ; utilisez des clés configurées séparément ou HTTP lorsqu'ils varient entre les messages. Utilisez HTTP pour les métadonnées ou les paramètres de modèle par message.

Placez chaque destinataire de livraison dans l'enveloppe SMTP, les destinataires visibles dans les en-têtes MIME To/Cc, et les destinataires Bcc uniquement dans l'enveloppe. Inventoriez X-MSYS-API.archive séparément : les copies d'archive de SparkPost conservent les URL de suivi du destinataire d'origine, le Bcc ordinaire n'est donc pas équivalent. Validez un remplacement avant de basculer ce flux.

Copiez explicitement vos paramètres de suivi effectifs : la clé SMTP non configurée de Bird active le suivi des ouvertures et des clics, tandis que les valeurs par défaut de SparkPost varient selon le compte. Définissez aussi la catégorie : Bird SMTP est transactionnel par défaut et HTTP inline est marketing par défaut. Les expéditeurs de newsletters ont besoin de marketing sur l'un ou l'autre chemin.

Pour les nouvelles tentatives SMTP, réutilisez la clé d'idempotence, l'enveloppe et les octets MIME exacts. Régénérer Date, Message-ID ou les frontières MIME modifie le contenu et peut empêcher une nouvelle tentative sûre.

Convertir les modèles

Exportez les versions que vous envoyez réellement via l'API Templates de SparkPost : listez avec GET /api/v1/templates?draft=false, puis récupérez le contenu avec GET /api/v1/templates/{id}?draft=false. Enregistrez les brouillons séparément si nécessaire. Incluez les modèles partagés avec les sous-comptes et les snippets référencés dans l'inventaire.

Le langage de modèles de SparkPost et la syntaxe Liquid de Bird diffèrent. Convertissez les conditions, boucles, valeurs par défaut et valeurs imbriquées. Résolvez les surcharges de destinataire et les métadonnées utilisées pour le rendu en paramètres explicites. Par exemple, {{ if ... }} devient {% if ... %}. La syntaxe {{ name }} partagée seule n'établit pas la compatibilité.

Développez les snippets avant de publier ; le Liquid de Bird ne prend pas en charge include ni render. Pour les modèles stockés, remplacez les références externes telles que {{ user.name }} par des paramètres plats tels que {{ user_name }}. Si vous insérez du HTML dynamique via des paramètres SparkPost, effectuez le rendu dans votre application et soumettez le corps complet sans parameters inline ; les valeurs de paramètres HTML ordinaires sont échappées.

Créez, prévisualisez et publiez un modèle Bird, puis suivez l'envoi avec un modèle. Reportez l'expéditeur effectif, le Reply-To et les en-têtes personnalisés de SparkPost dans la requête d'envoi ; les modèles Bird fournissent le contenu.

Pour du Liquid en ligne, incluez parameters, même {} ; l'omettre laisse les jetons inchangés. Vérifiez les valeurs manquantes, l'échappement et les URL.

Remplacez les espaces réservés de désinscription par {{ bird.unsubscribe_url }}. Bird fournit les en-têtes de désinscription marketing ; supprimez les en-têtes personnalisés List-Unsubscribe et List-Unsubscribe-Post des envois marketing pour éviter un rejet 422.

Les liens de désinscription de Bird excluent l'adresse de l'e-mail marketing dans tout l'espace de travail. Ces liens ne permettent pas de désinscriptions par liste. Vérifiez ce comportement si votre intégration SparkPost propose des abonnements distincts.

Migrer les listes de destinataires

Exportez chaque liste de destinataires stockée avec GET /api/v1/recipient-lists/{id}?show_recipients=true pour inclure l'appartenance et la personnalisation. Créez les audiences de destination et enregistrez les propriétés de contact avant d'importer. Examinez chaque résultat d'import et rapprochez les effectifs.

Les propriétés de contact appartiennent au contact dans toutes ses audiences. Si la même adresse possède des données de substitution différentes dans plusieurs listes SparkPost, rapprochez ces valeurs avant l'import pour éviter de les écraser. Les propriétés de contact Bird ont des types scalaires ; conservez la personnalisation par liste ou structurée dans votre application lorsqu'elle ne peut pas être représentée de manière fiable.

Utilisez les broadcasts lorsqu'un modèle publié peut être alimenté par les propriétés de contact. L'appartenance à l'audience est résolue au démarrage de l'envoi, et les quotas d'envoi et de simultanéité des broadcasts s'appliquent. Utilisez des messages par lot indépendants pour des paramètres propres à la requête ou un instantané fixe de destinataires. Validez la gestion du consentement et des suppressions avant d'activer une liste migrée.

Exporter les suppressions

Exportez avant tout envoi en production. Commencez par GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking, puis suivez la pagination jusqu'au bout. Enregistrez l'intégralité des enregistrements, y compris le type, la source, l'identifiant de liste, le sous-compte et les horodatages. Utilisez X-MSYS-SUBACCOUNT: 0 pour le compte principal et l'identifiant de chaque sous-compte pour sa propre liste. Consultez la documentation Suppression List API de SparkPost.

Classez les enregistrements par type, source et portée avant d'utiliser la boucle d'import du guide principal. L'endpoint POST /v1/email/suppressions de Bird accepte un email et crée un blocage manuel à l'échelle de l'espace de travail sur les deux catégories :

• Adresses bloquées pour la réception d'e-mails : importez celles qui doivent être bloquées toutes catégories confondues. Conservez l'export d'origine pour le rapprochement ; les enregistrements importés portent le motif manuel de Bird.
• Désinscriptions marketing à l'échelle du compte : utilisez POST /v1/preferences avec channel: "email", l'adresse dans handle, status: "revoked" et coverage: "non_transactional". Définissez source: "sparkpost-migration" pour la réconciliation. Examinez d'abord les préférences Bird existantes et conservez les restrictions les plus strictes ; inspectez applied et la préférence renvoyée après chaque écriture.
• Restrictions spécifiques à une liste ou limitées au transactionnel : conservez leur portée dans l'éligibilité d'envoi de votre application. Les préférences e-mail de Bird s'appliquent à l'ensemble du canal et ne peuvent pas représenter ces portées. Une suppression manuelle peut aussi bloquer les réinitialisations de mot de passe. Maintenez le trafic concerné en pause jusqu'à ce que vous vérifiiez le remplacement.
• Désinscriptions du suivi d'ouverture : définissez track_opens: false pour le message indépendant, en plus de toute restriction d'envoi. Pour SMTP, utilisez une clé avec le suivi d'ouverture désactivé ou utilisez HTTP pour un contrôle par message.

La requête de préférence ci-dessus enregistre la restriction au moment de l'import. Conservez les horodatages originaux de SparkPost dans votre export et réconciliez tout consentement ultérieur avant l'écriture. Réconciliez les enregistrements importés et les écritures échouées, puis testez les deux catégories. Synchronisez les nouvelles désinscriptions et suppressions tant que les deux fournisseurs envoient. Continuez à appliquer les désinscriptions issues des e-mails SparkPost précédemment distribués vers Bird après la bascule. Consultez Suppressions pour la gestion native des rebonds et des plaintes.

Convertir les événements webhook

SparkPost envoie des événements webhook groupés dans des enveloppes msys. Bird distribue un événement par requête avec type, timestamp et data. Enregistrez un endpoint Bird avec des abonnements d'événements explicites et une vérification de signature. Maintenez le handler SparkPost actif pour son trafic restant.

Les envois directs API et SMTP émettent email.accepted avant le traitement. Les broadcasts enregistrent l'acceptation dans les événements API et le journal d'e-mails, mais omettent ce webhook. Les événements policy_rejection, generation_failure et generation_rejection de SparkPost correspondent à email.rejected ; inspectez rejection_reason. Dédupliquez les ouvertures séparément lorsque vous comptez l'engagement unique.

Utilisez data.email_id et data.recipient_id pour la corrélation Bird, et transmettez vos propres identifiants dans metadata. Remplacez la gestion des batch ID de SparkPost par les règles de déduplication et d'ordonnancement des webhooks de Bird. Lisez les détails du rebond avant de décider si une adresse doit être sur la liste de suppression ; la classification des rebonds distingue les échecs d'adresse permanents des échecs temporaires ou liés aux politiques.

Conserver l'historique des rapports

Exportez l'historique des événements SparkPost et les rapports agrégés dont vous avez besoin avant l'expiration de leurs fenêtres de rétention. Suivez la pagination des événements jusqu'au bout et conservez les identifiants du fournisseur, la portée compte/sous-compte, les horodatages et les filtres de rapport. Continuez à collecter les événements tardifs pendant la période de chevauchement, et conservez l'historique SparkPost dans une archive séparée.

Enregistrez une référence de base pour chaque flux d'envoi. Comparez les populations de destinataires et les fenêtres de rapport correspondantes, et vérifiez les définitions des métriques : acceptation par le fournisseur, livraison par le serveur destinataire, engagement unique et ouvertures pré-récupérées sont des mesures différentes. Des noms de métriques identiques ne suffisent pas à établir des taux comparables.

Migrer les e-mails entrants séparément

Si vous utilisez les webhooks relais de SparkPost, suivez Réception d'e-mails pour ce flux. Le webhook email.received de Bird fournit un inbound_message_id ; récupérez le corps, les pièces jointes ou le MIME brut via l'API au lieu d'attendre le message complet dans le webhook. Testez votre gestionnaire avec une adresse de transfert Bird, puis préparez la réception de domaine avant de modifier les enregistrements MX. Vérifiez le routage des réponses après le changement DNS et archivez le contenu dont vous avez besoin au-delà de la période de rétention de réception de Bird.

Vérifier et basculer

1. Vérifiez la capacité d'envoi de chaque domaine. Exécutez le test de fumée en bac à sable et les cas de plainte. Confirmez que les événements signés atteignent votre gestionnaire, correspondent au bon message et gèrent les livraisons en double. Les événements du bac à sable ne prouvent pas la livraison en boîte de réception, le rendu ou le suivi.
2. Envoyez depuis votre domaine vérifié vers des boîtes de réception réelles contrôlées. Vérifiez la personnalisation, la visibilité To/Cc/Bcc, les pièces jointes, l'authentification et le suivi. Testez un désabonnement : le marketing doit s'arrêter tandis que le courrier transactionnel éligible continue. Testez séparément que les blocages toutes catégories rejettent les deux. Gardez ces vérifications distinctes des résultats simulés en bac à sable.
3. Attribuez les envois programmés en attente à un seul fournisseur. Videz ou annulez l'original avant de le recréer ailleurs. Maintenez un enregistrement applicatif indiquant quel fournisseur a accepté chaque envoi logique, afin que les nouvelles tentatives ou le retour en arrière n'envoient pas un deuxième exemplaire.
4. Déplacez une portion contrôlée du trafic et surveillez les métriques de livraison et le traitement des webhooks. Pour les IP dédiées, suivez le plan de migration convenu avec notre équipe, y compris tout préchauffage. Augmentez le trafic une fois que les résultats observés répondent à vos exigences de livraison.
5. Si la validation échoue, suspendez le trafic Bird concerné et dirigez les nouveaux envois via le chemin SparkPost conservé avec les désinscriptions actuelles appliquées. Réconciliez les envois ambigus avant de les réessayer. Retirez les anciens identifiants, webhooks et DNS une fois les files d'attente et les événements tardifs pris en compte ; maintenez les anciens liens de suivi et de désabonnement fonctionnels pour le courrier précédemment livré.

Si l'authentification échoue, vérifiez le jeton bearer Bird et la région. Si les imports de préférences renvoient 403, vérifiez la permission d'écriture preferences de la clé avant de continuer. Si la personnalisation s'affiche incorrectement, inspectez la conversion Liquid et les paramètres. Si le courrier transactionnel est rejeté de manière inattendue, vérifiez les suppressions manuelles importées. Utilisez le journal d'e-mails et les détails des événements pour vérifier chaque correction.

Étapes suivantes

• Envoi d'e-mails : champs du payload, personnalisation et résultats asynchrones
• Modèles d'e-mails : prévisualisation, publication et support Liquid
• Suppressions : raisons de suppression et gestion
• Webhooks et événements : signatures, réessais et rejeu