Envoyer un e-mail transactionnel
Un e-mail transactionnel part à l'unité, au moment où votre système le décide : une confirmation de commande, un reçu, un code d'accès. Il est facturé au même tarif que vos campagnes et compte dans le même plafond.
Réservez cette API aux messages qui répondent à une action du destinataire. Les messages promotionnels passent par les campagnes, qui gèrent les désinscriptions. Un destinataire désinscrit de vos campagnes reçoit toujours vos e-mails transactionnels.
Prérequis
- Une clé API secrète dotée de la permission
send_transactional_email(etview_transactional_messagespour consulter les envois). Voir Authentification. - Des crédits.
- Un expéditeur e-mail vérifié (Paramètres › Expéditeurs). Il est obligatoire : vos e-mails partent toujours à votre nom.
Envoyer
curl https://api.metaventus.com/v1/transactional/email \
-H "X-API-Key: VOTRE_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-20481" \
-d '{
"to": "marie@exemple.fr",
"from": "contact@votre-domaine.fr",
"subject": "Votre commande est confirmée",
"html": "<p>Bonjour Marie,</p><p>Votre commande 20481 est confirmée.</p>",
"reference": "commande-20481"
}'
| Champ | Obligatoire | Description |
|---|---|---|
to | oui | Adresse du destinataire. Une seule par message. |
subject | oui | L'objet, sur une ligne, 998 caractères au plus. |
html | oui, ou text | Le corps en HTML, 1 Mo au plus. |
text | oui, ou html | Le corps en texte. Sans html, il est envoyé avec ses retours à la ligne. |
from | non | Un expéditeur e-mail vérifié de votre compte. Sans from, votre expéditeur par défaut. |
reply_to | non | L'adresse qui reçoit les réponses. |
reference | non | Votre identifiant (n° de commande…), 128 caractères au plus. Renvoyé tel quel, filtrable. |
Réponse 202 Accepted : le message est accepté, facturé et en route.
{
"id": "922c2bfd-32ec-4773-b348-63967731e3a7",
"channel": "email",
"to": "marie@exemple.fr",
"from": "contact@votre-domaine.fr",
"subject": "Votre commande est confirmée",
"body": "<p>Bonjour Marie,</p><p>Votre commande 20481 est confirmée.</p>",
"status": "queued",
"reference": "commande-20481",
"created_at": "2026-11-04T09:00:00Z",
"updated_at": "2026-11-04T09:00:00Z"
}
202 n'est pas une erreur : c'est la réponse normale d'un envoi.
Ne jamais envoyer deux fois
Passez un en-tête Idempotency-Key propre à chaque message. Si votre requête expire et
que vous la rejouez avec la même clé, le premier message est renvoyé avec un 200 et
l'en-tête Idempotent-Replayed: true : rien n'est renvoyé au destinataire, rien n'est
refacturé.
Réutiliser une clé pour un autre message (autre destinataire, objet ou contenu) est
refusé (422 idempotency_key_reused).
Suivre la remise
Les e-mails se suivent avec les mêmes routes que les SMS :
GET /v1/transactional/messages/{id} et GET /v1/transactional/messages
(voir Lister les envois).
status | Signification |
|---|---|
queued | Accepté et facturé, en cours d'envoi. |
sent | Pris en charge par le service d'envoi (sent_at). |
delivered | Accepté par le serveur de messagerie du destinataire (delivered_at). |
failed | Non remis — voir error_code. |
Pour être prévenu sans interroger l'API, abonnez une adresse à ces événements : voir Recevoir les événements de vos messages.
delivered signifie que le serveur du destinataire a accepté l'e-mail, pas qu'il a été lu
ni qu'il est arrivé en boîte de réception plutôt qu'en indésirables.
error_code | Cause | Facturé |
|---|---|---|
rejected | Refusé par le service d'envoi (adresse ou contenu). | Non, recrédité |
not_sent | Jamais transmis. | Non, recrédité |
bounced | Adresse refusée par le serveur du destinataire. | Oui |
Refus
Un envoi refusé n'est ni envoyé ni facturé. Le corps porte un code stable et une
phrase explicative dans error.
| Statut | code | Cause | Conduite à tenir |
|---|---|---|---|
400 | invalid_to, invalid_reply_to, invalid_subject, invalid_body, invalid_reference | Requête invalide | Corriger |
402 | insufficient_credits | Solde insuffisant (details.credits_needed, details.wallet_balance) | Recharger, puis réessayer |
403 | account_suspended | Abonnement suspendu | Régulariser |
413 | body_too_long | Corps de plus de 1 Mo | Alléger le message |
422 | sender_not_allowed | from n'est pas un expéditeur e-mail vérifié du compte | Corriger from |
422 | sender_required | Pas de from et aucun expéditeur vérifié par défaut | Indiquer from, ou définir un expéditeur par défaut |
422 | idempotency_key_reused | Clé déjà utilisée pour un autre message | Nouvelle clé |
429 | daily_limit_reached | Plafond e-mail de votre offre atteint pour la période (details.limit, details.used) | Attendre, ou changer d'offre |
503 | temporarily_unavailable | Incident passager | Réessayer avec la même Idempotency-Key |
Le plafond est partagé avec vos campagnes, scénarios et rappels de rendez-vous : c'est un seul forfait e-mail, quel que soit le canal d'envoi.