Votre application envoie des données structurées à un point de terminaison HTTP et reçoit une réponse contenant le résultat du message ou une erreur. Cette requête et cette réponse constituent la surface de travail d'une API e-mail.
Que gère une API e-mail ?
Un point de terminaison d'envoi accepte des destinataires, un objet et du contenu texte ou HTML. Il peut aussi accepter des en-têtes, des tags, des modèles et des pièces jointes lorsque le fournisseur les prend en charge.
Un point de terminaison d'événements ou un webhook signale ce qui s'est passé après l'acceptation. Les événements courants incluent la livraison, le rebond, la plainte, l'ouverture et le clic. Une API de réception transforme le courrier entrant en messages structurés pour votre application, au lieu de vous obliger à interroger une boîte aux lettres.
En quoi une API e-mail diffère-t-elle de SMTP ?
SMTP exige que votre application ouvre une connexion, s'authentifie, envoie des commandes et lise les codes de réponse. Une API e-mail utilise des requêtes HTTP à la place, de sorte qu'une bibliothèque cliente peut gérer la réutilisation des connexions, l'encodage JSON, les réessais et l'analyse des réponses.
Choisissez une API lorsque votre application utilise déjà HTTP, a besoin d'événements structurés ou s'exécute dans un environnement où ouvrir des connexions SMTP est difficile. Choisissez un relais SMTP lorsqu'une bibliothèque de messagerie ou un serveur de messagerie existant parle déjà SMTP. Les deux chemins peuvent livrer le même message.
| Tâche | API d'envoi | Relais SMTP | API de boîte aux lettres |
|---|---|---|---|
| Envoyer un message | Oui | Oui | Répondre ou rédiger |
| Recevoir du courrier analysé | Certains fournisseurs | Non | Oui |
| Lire l'historique des conversations | Certains fournisseurs | Non | Oui |
| Observer la livraison | Événements ou webhooks | Codes de réponse et événements | Statut du message et événements |
Les produits utilisent le terme API e-mail pour des ensembles de fonctionnalités différents. Vérifiez le schéma du fournisseur avant de supposer qu'une seule API couvre chaque ligne.
Que doit contenir une requête API ?
Envoyez les champs exigés par votre fournisseur. Enregistrez l'identifiant de message renvoyé. Conservez votre propre clé d'idempotence lorsqu'un réessai ne doit pas créer un envoi en double. Validez les destinataires avant l'envoi. Gardez les secrets sur votre serveur.
Un exemple de requête transactionnelle contient from, to, subject, text, category: transactional et une clé d'idempotence conservée sur le serveur. Utilisez un domaine d'envoi vérifié avant de l'envoyer.
La réponse HTTP signifie que le service a accepté la requête. Les événements de livraison, de rebond et de plainte arrivent plus tard, donc une réponse d'acceptation ne garantit pas le placement en boîte de réception.
Utilisez des webhooks pour les événements ultérieurs au lieu de considérer une requête acceptée comme preuve qu'un message a atteint une boîte de réception. Les événements de livraison et de plainte décrivent ce qui s'est passé après l'acceptation.
Comment envoyer avec Bird ?
Vous appelez createEmailMessage API de Bird avec votre clé API d'espace de travail, l'expéditeur, les destinataires, le contenu et des métadonnées optionnelles. Le guide d'envoi d'e-mails présente les champs de requête et de réponse.
Pour les réponses et le courrier entrant, créez une boîte aux lettres et consommez ses événements de message et de livraison. Le guide des boîtes aux lettres couvre ces points de terminaison et noms de webhooks.
En résumé
- Une API e-mail expose l'envoi et les événements de message via HTTP.
- La réponse confirme l'acceptation par API, pas le placement en boîte de réception.
- Les clés d'idempotence rendent les réessais sûrs.
- Bird fournit des API d'envoi et de boîte aux lettres avec des guides pour chaque chemin.