Base de connaissances
API d’envoi d’e-mails
Envoyez un message ou cent par appel, maintenant ou plus tard, et réessayez sans jamais envoyer deux fois.
Détails
- POST /emails envoie un message et POST /emails/batch jusqu’à 100 messages indépendants. Un lot n’est jamais tout ou rien : une mauvaise adresse à l’élément 7 fait échouer l’élément 7, le reste part quand même, et la réponse rend compte de chaque élément séparément.
- Le contenu vient d’une seule source : html et/ou text, un modèle enregistré par identifiant ou slug (figez sa version quand le texte appartient à quelqu’un d’autre), ou un brouillon existant. Jusqu’à 10 tags l’accompagnent et sont renvoyés à chaque lecture.
- scheduledAt retient un message jusqu’à 365 jours, sous forme d’instant ISO 8601 ou de durée comme PT1H. cancellableForSeconds donne à un envoi immédiat un délai d’annulation jusqu’à 900 secondes. Les deux peuvent être annulés, et un envoi planifié replanifié, tant qu’il n’est pas parti.
- Chaque envoi porte un Idempotency-Key réservé avant tout départ, de sorte qu’une nouvelle tentative après un délai dépassé renvoie le premier résultat avec Idempotency-Replayed: true. La même clé avec un autre contenu est refusée comme idempotency_key_reuse.
- Chaque envoi a un identifiant msg_ dès qu’il est accepté. GET /emails/{id} le lit, /events donne la trace de chaque destinataire et /tracking les ouvertures et les clics.
- Ajoutez translate et le message est livré dans la langue du destinataire. Il est traduit à l’acceptation de la requête, donc un envoi planifié porte le texte que vous avez approuvé, et une traduction impossible refuse l’envoi plutôt que de se rabattre sur l’original.
- Pièces jointes : jusqu’à 20 fichiers, 5 Mo au total pour les fichiers intégrés. Un fichier plus lourd s’envoie en désignant un fichier de l’espace de travail par son identifiant, et voyage sous forme de lien de téléchargement.
- Ce qui manque : il n’y a pas encore de mode test, donc chaque clé livre pour de vrai, et l’envoi n’a pas de statut de rebond. Un rebond est étiqueté sur le fil et émis comme webhook email.bounced, tandis que GET /emails affiche toujours sent.
- La liste de suppression, Adresses bloquées dans les Paramètres, est aussi dans l'API. GET /suppressions la lit avec une recherche et un filtre par motif, POST /suppressions bloque une adresse à la main, et DELETE /suppressions/{id} en autorise une à nouveau, sauf un rebond définitif, qui reste. Le SDK et le serveur MCP font de même, et chaque changement déclenche le webhook suppression.added ou suppression.removed.