Après le paiement, votre application dispose d'une commande et d'un destinataire qui a besoin d'un reçu. Elle utilise une API d'e-mail pour soumettre le message. Elle enregistre la réponse en lien avec la commande.
La soumission n'est que la première étape. Votre application a aussi besoin de pouvoir réessayer une requête. Elle doit savoir ce qu'il est advenu du message après la soumission.
Comment un événement applicatif devient-il un e-mail ?
Votre application transforme une transaction terminée ou une demande liée au compte en opération d'envoi. Le service d'e-mail gère la livraison après la soumission.
Pour un reçu, la séquence est la suivante :
- Votre application confirme que la commande est prête pour un reçu.
- Elle sélectionne le destinataire et fournit les détails de la commande sous forme de contenu ou de valeurs de template.
- Elle soumet l'envoi et enregistre l'identifiant de message retourné en lien avec la commande.
- Elle met à jour l'enregistrement d'envoi lorsque les événements de livraison arrivent.
Une API d'e-mail peut prendre en charge à la fois les messages transactionnels et marketing. Utiliser une API ne rend pas un contenu promotionnel transactionnel et ne supprime pas les obligations CAN-SPAM.
Que signifie une réponse réussie ?
Une réponse de soumission réussie indique ce que le service a accepté. Elle est distincte de la décision ultérieure du serveur de messagerie destinataire.
Le statut 202 de HTTP signifie qu'une requête a été acceptée pour traitement. Le traitement n'est pas terminé, cette réponse ne peut donc pas établir la livraison.
La réponse exacte dépend de l'API. Le point de terminaison d'envoi de Bird, par exemple, retourne un message en file d'attente avec un id. Conservez cet identifiant à côté de la commande ou de l'événement de compte afin de pouvoir associer les résultats ultérieurs à la requête d'origine.
Si la validation échoue, Bird retourne 422 avec une erreur expliquant pourquoi la requête a été rejetée.
Comment les réessais évitent-ils les messages en double ?
Une clé d'idempotence identifie une opération d'envoi logique à travers les réessais. Une API qui la prend en charge peut reconnaître une requête répétée au lieu de créer un nouvel envoi.
Par exemple, un reçu pour la commande 8472 peut utiliser la clé receipt/order-8472. Réessayez la même requête avec cette clé si la connexion est interrompue avant que vous ne receviez la réponse.
Une nouvelle clé identifie une opération différente. Votre application doit donc conserver la clé d'origine à travers ses propres réessais et redémarrages.
L'idempotence a une fenêtre de rétention définie par le fournisseur. Une fois cette fenêtre expirée, la même clé peut être traitée comme une nouvelle requête.
Comment les webhooks signalent-ils la livraison ?
Un webhook envoie un événement à votre application lorsque l'état du message change. Il permet à votre application de mettre à jour ses enregistrements après la réponse initiale de l'API.
Les événements e-mail de Bird distinguent ces résultats :
| Événement | Ce qu'il établit |
|---|---|
email.delivered | Le serveur de messagerie destinataire a accepté la responsabilité du message |
email.deferred | Un échec de livraison temporaire fera l'objet d'un réessai |
email.bounced | Le serveur destinataire a refusé la livraison |
email.rejected | Le message n'a pas atteint une tentative de livraison |
L'acceptation par le serveur n'établit ni le placement en boîte de réception ni la lecture. Un serveur destinataire peut aussi signaler un rebond ultérieur après avoir accepté le message.
Votre gestionnaire de webhook doit vérifier la signature de l'expéditeur et gérer les livraisons en double. Le contrat de webhook de Bird exige la déduplication à l'aide de webhook-id.
Que changent les templates ?
Un template enregistré sépare le contenu réutilisable du message des valeurs fournies pour chaque envoi. Votre application peut fournir un numéro de commande et un nom de client sans assembler le corps complet de l'e-mail.
Avec les templates de Bird, un envoi nomme un template publié et fournit ses paramètres. Le template fournit l'objet et le corps du message.
Un template ne décide pas quand une commande est terminée ni si une réinitialisation de mot de passe est autorisée. Ces décisions restent dans votre application.
En quoi est-ce différent du relais SMTP ou d'une plateforme marketing ?
Une API HTTP et un relais SMTP sont des interfaces de soumission différentes. Une plateforme marketing gère aussi le travail de campagne, comme la sélection d'une audience et la planification d'un envoi.
| Interface ou produit | Ce que votre application fournit |
|---|---|
| API d'e-mail | Une requête HTTP structurée contenant les destinataires et le contenu ou un template |
| Relais SMTP | Une conversation SMTP soumettant les destinataires et un message e-mail formaté |
| Plateforme marketing | Contenu de campagne, sélection d'audience et instructions d'envoi |
SMTP définit l'échange pour soumettre un message et ses destinataires. Il peut transporter du courrier transactionnel ou marketing.
Le relais SMTP de Bird et HTTP API utilisent le même produit de livraison, y compris les événements et la gestion des suppressions. Choisir SMTP ne supprime pas ces fonctionnalités.
Comment envoyer un e-mail transactionnel via Bird ?
Vous appelez POST /v1/email/messages avec un expéditeur vérifié, des destinataires et du contenu en ligne ou un template publié. Définissez category: "transactional" pour le courrier opérationnel. La réponse est 202 Accepted avec un identifiant de message ; la livraison se poursuit de manière asynchrone.
Utilisez une Idempotency-Key pour chaque envoi logique. Bird conserve une réponse terminée pendant trois heures. Un réessai après cette fenêtre peut créer un autre message, conservez donc votre propre enregistrement des événements métier terminés.
Abonnez-vous aux événements e-mail et associez email_id et recipient_id à vos enregistrements. Un message avec plusieurs destinataires a des résultats distincts pour chaque destinataire.
Pour le choix d'un fournisseur, la checklist des services d'e-mail transactionnel couvre les capacités de livraison et opérationnelles à comparer.