API d'envoi d'emails
Mettez des emails en file et suivez leur livraison destinataire par destinataire. Il y a deux façons d'envoyer — avec le contenu dans la requête elle-même, ou avec un modèle stocké — et deux endpoints de consultation pour savoir ce qui s'est passé ensuite.
Chaque requête utilise l'en-tête X-API-KEY. Voir Authentification.
Endpoints
| Endpoint | Ce qu'il fait |
|---|---|
POST /v1/mailing/send | Met en file un envoi avec le contenu dans la requête |
POST /v1/mailing/send-template | Met en file un envoi à partir d'un modèle stocké |
GET /v1/mailing/email-request/{uuid} | Statut de la demande et messages qu'elle a générés |
GET /v1/mailing/email-message/{uuid} | Statut de livraison et validation pour un destinataire |
L'envoi est asynchrone
L'API accepte la requête et la met en file ; elle ne livre pas sur-le-champ. C'est pourquoi une requête réussie ne signifie pas encore une livraison réussie, et le suivi se fait en deux étapes :
POST /v1/mailing/send -> uuid de la demande
GET /v1/mailing/email-request/{uuid} -> email_messages[] (un uuid par destinataire)
GET /v1/mailing/email-message/{uuid} -> statut et validation de ce destinataireUne demande (email_request) génère un message par destinataire (email_message). Le statut de livraison, les ouvertures, les clics et le résultat de validation vivent sur le message, pas sur la demande.
Les trois états de réponse
Les deux endpoints d'envoi renvoient une réponse enveloppée, qui peut se résoudre de trois façons selon le nombre de destinataires acceptés :
status | HTTP | Signification |
|---|---|---|
success | 200 | Tous les destinataires ont été acceptés |
warning | 200 | Certains acceptés et certains rejetés ; vérifiez rejected_recipients |
error | 400 | Aucun destinataire accepté, ou requête invalide |
Vérifiez toujours rejected_recipients
Un 200 ne garantit pas que tous vos destinataires sont passés. Avec status = warning, la requête n'est mise en file que pour les destinataires acceptés, et les écartés reviennent avec leur motif dans data.rejected_recipients. Quand aucun n'est accepté, cette même liste arrive dans error.details.rejected_recipients.
Destinataires
to, cc et bcc acceptent les mêmes quatre formats (une adresse seule, une liste, un objet avec un nom, ou une liste d'objets), documentés dans Format des destinataires.
Un maximum de 50 destinataires valides par requête est autorisé. Si plus de 50 sont acceptés après prétraitement, la requête est rejetée.
Validation des destinataires
Avant de livrer, Mailiqo vérifie que chaque destinataire existe et est joignable. Elle se configure par domaine, et tout envoi peut la renforcer avec l'objet validation :
- Validation pour cet envoi — le paramètre, avec un exemple
- Validation des destinataires — ce qui est vérifié et comment c'est configuré
- API de validation d'emails — vérifier des adresses sans rien leur envoyer
Le résultat par destinataire ne revient pas dans la réponse d'envoi : la vérification avancée a lieu après que vous avez reçu la réponse. Vous le lisez dans le bloc validation de GET /email-message/{uuid}.
Erreurs
Les codes d'envoi vont de 1400 à 1422 et sont listés dans la référence des erreurs. Les plus courants :
| Code | Signification |
|---|---|
1412 | Aucun destinataire valide trouvé |
1413 | Plus de 50 destinataires valides dans une requête |
1417 | Quota mensuel d'emails épuisé |
1418 | Limite d'emails supplémentaires atteinte |
1419 | Options de validation invalides |
1421 | Limite d'envoi horaire ou quotidienne atteinte (HTTP 429). Voir Limites d'envoi |
1422 | Le message dépasse à lui seul la limite d'envoi horaire ou quotidienne (HTTP 400). Divisez-le en messages plus petits |
