Aller au contenu principal

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 (et view_transactional_messages pour 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"
}'
ChampObligatoireDescription
toouiAdresse du destinataire. Une seule par message.
subjectouiL'objet, sur une ligne, 998 caractères au plus.
htmloui, ou textLe corps en HTML, 1 Mo au plus.
textoui, ou htmlLe corps en texte. Sans html, il est envoyé avec ses retours à la ligne.
fromnonUn expéditeur e-mail vérifié de votre compte. Sans from, votre expéditeur par défaut.
reply_tononL'adresse qui reçoit les réponses.
referencenonVotre 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).

statusSignification
queuedAccepté et facturé, en cours d'envoi.
sentPris en charge par le service d'envoi (sent_at).
deliveredAccepté par le serveur de messagerie du destinataire (delivered_at).
failedNon 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_codeCauseFacturé
rejectedRefusé par le service d'envoi (adresse ou contenu).Non, recrédité
not_sentJamais transmis.Non, recrédité
bouncedAdresse 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.

StatutcodeCauseConduite à tenir
400invalid_to, invalid_reply_to, invalid_subject, invalid_body, invalid_referenceRequête invalideCorriger
402insufficient_creditsSolde insuffisant (details.credits_needed, details.wallet_balance)Recharger, puis réessayer
403account_suspendedAbonnement suspenduRégulariser
413body_too_longCorps de plus de 1 MoAlléger le message
422sender_not_allowedfrom n'est pas un expéditeur e-mail vérifié du compteCorriger from
422sender_requiredPas de from et aucun expéditeur vérifié par défautIndiquer from, ou définir un expéditeur par défaut
422idempotency_key_reusedClé déjà utilisée pour un autre messageNouvelle clé
429daily_limit_reachedPlafond e-mail de votre offre atteint pour la période (details.limit, details.used)Attendre, ou changer d'offre
503temporarily_unavailableIncident passagerRé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.