E-mails transactionnels

Un e-mail transactionnel part vers une personne précise, à cause de ce qu’elle vient de faire. Il n’a pas besoin de liste ni de consentement marketing, et il est journalisé et suivi comme une campagne. Voir Vue d’ensemble.

Avec un modèle

Le plus propre : le contenu vit dans Lekalao, l’application n’envoie que les données. Créez un modèle nommé confirmation-commande (Modèles transactionnels), puis :

curl -X POST https://api.lekalao.com/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: commande-2026-00481-confirmation" \
  -d '{
    "template": "confirmation-commande",
    "to": ["ada@example.com"],
    "locale": "fr",
    "variables": {
      "customer": { "name": "Ada" },
      "order": {
        "number": "2026-00481",
        "total": "12 500 FCFA",
        "items": ["Pain complet", "Croissant x4"]
      }
    }
  }'

Dans le modèle :

<p>Bonjour {{ customer.name }},</p>
<p>Votre commande <strong>{{ order.number }}</strong> est confirmée.</p>
<ul>
    {% for item in order.items %}
    <li>{{ item }}</li>
    {% endfor %}
</ul>
<p>Total : {{ order.total }}</p>

Les variables sont échappées ; les boucles portent sur des listes de valeurs simples. Toute la syntaxe est dans Personnalisation.

Sans modèle

Envoyez le HTML tel quel :

curl -X POST https://api.lekalao.com/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "to": ["ada@example.com"],
    "subject": "Votre facture de septembre",
    "html": "<p>Bonjour Ada, votre facture est jointe.</p>",
    "from_email": "factures@maboulangerie.example",
    "from_name": "La Boulangerie",
    "attachments": [
      { "name": "facture-2026-09.pdf", "content": "JVBERi0xLjcKJcfsj6IK…", "mime": "application/pdf" }
    ]
  }'

Les champs

Champ
`template`	Nom d’un modèle transactionnel.
`html`	Le corps, si pas de modèle. L’un des deux est obligatoire.
`subject`	Objet. Avec un modèle, remplace celui du modèle.
`to`, `cc`, `bcc`	Tableaux d’adresses, 50 au plus ensemble. Sans `to`, les destinataires par défaut du modèle.
`variables`	Objet libre, qui remplit le modèle.
`locale`	Version linguistique du modèle. Voir ci-dessous.
`from_email`, `from_name`, `reply_to`	L’expéditeur, sinon celui du modèle, sinon celui de l’équipe.
`mailer`	Nom d’un fournisseur d’envoi de l’équipe, ou d’un fournisseur offert par le service, pour forcer le chemin. Le nom d’une autre équipe est refusé.
`attachments`	10 au plus : `name`, `content` en base64, `mime` facultatif.

Chaque adresse compte dans le quota du mois, copies comprises : un e-mail à une personne en to et deux en cc compte pour trois. Un e-mail transactionnel s’écrit à quelqu’un, il ne se diffuse pas : plus de 50 adresses répondent 422 too_many_recipients.

En plusieurs langues

Un modèle peut avoir une version par langue (Langues). locale choisit :

`locale` envoyé	Version utilisée
absent	La version de base.
`pt-BR`, et le modèle a `pt-BR`	`pt-BR`.
`pt-BR`, le modèle n’a que `pt`	`pt`.
`pt`, le modèle n’a que `pt-BR`	La version de base : une langue ne prend jamais une version régionale.
une langue sans version	La version de base.

Passez la langue de votre client telle que votre application la connaît : Lekalao se rabat tout seul.

La réponse

L’appel reçoit sa réponse dès que l’e-mail est écrit. Il part d’une file d’attente un instant plus tard.

Code	`status`	`code`	Quand
`202`	`pending`		La réponse habituelle : l’e-mail est journalisé et attend son tour dans la file.
`201`	`sent`		L’e-mail était déjà remis au fournisseur quand la réponse est partie.
`422`	`failed`	`recipients_suppressed`	Journalisé, pas envoyé : toutes les adresses de `to` sont sur la liste de suppression.
`429`	`failed`	`monthly_quota_exceeded`	Journalisé, pas envoyé : les e-mails du mois de la formule sont épuisés.
`422`	`failed`	`sending_paused`	Journalisé, pas envoyé : la période payée de l’équipe s’est terminée sans paiement.
`502`	`failed`	`queue_unavailable`, `provider_error`	Journalisé, pas envoyé : la file d’attente n’a pas pu le prendre, ou le fournisseur l’a refusé. Quand la file tourne à part, comme sur le service de Lekalao, les refus du fournisseur arrivent plus tard, dans la file ; avec une clé de test, `failed@sink.lekalao.dev` y répond tout de suite.
`422`	—	`validation_error`, `content_missing`, `recipient_missing`, `too_many_recipients`, `sender_not_allowed`, `template_error`	Rien n’est journalisé : un champ est invalide (un `template` inconnu, par exemple), ni `template` ni `html` n’est donné, aucun destinataire, plus de 50, ou l’expéditeur n’est pas autorisé.

Un refus est une erreur comme une autre — message, code, doc_url — avec l’e-mail journalisé sous data quand il y en a un :

429 Too Many Requests

{
    "message": "Votre formule envoie 10000 e-mails par mois, et ils sont épuisés.",
    "code": "monthly_quota_exceeded",
    "doc_url": "https://docs.lekalao.com/fr/errors#monthly_quota_exceeded",
    "data": { "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10", "status": "failed", "failure_code": "monthly_quota_exceeded", "…": "…" }
}

L’e-mail lui-même :

202 Accepted

{
    "data": {
        "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10",
        "template": "confirmation-commande",
        "subject": "Commande 2026-00481 confirmée",
        "from": "bonjour@maboulangerie.example",
        "to": ["ada@example.com"],
        "cc": [],
        "bcc": [],
        "status": "pending",
        "sandbox": false,
        "failure_reason": null,
        "failure_code": null,
        "opens": 0,
        "clicks": 0,
        "sent_at": null,
        "delivered_at": null,
        "bounced_at": null,
        "complained_at": null,
        "created_at": "2026-09-17T10:14:02+00:00"
    }
}

Traitez 201 et 202 de la même façon : Lekalao a l’e-mail. Gardez son id ; status dit s’il est déjà parti. Les adresses de la liste de suppression sont retirées de to, cc et bcc sans erreur. L’e-mail part aux autres, et n’échoue que s’il ne reste aucun to.

Ensuite, dans la file

Lekalao remet l’e-mail au fournisseur. Quand le fournisseur échoue (délai dépassé, erreur, refus), Lekalao réessaie après 5 secondes, puis 30 secondes, 2 minutes, 10 minutes et 30 minutes. Il abandonne après le sixième essai raté, et de toute façon six heures après l’appel. status passe alors à failed, avec failure_code: provider_error et la dernière erreur du fournisseur dans failure_reason. Un e-mail dont la tâche s’est perdue en route — un worker arrêté, une file vidée — ne reste pas pending pour toujours : sept heures après l’appel, il passe failed avec failure_code: lost. Son contenu n’a peut-être pas été gardé, il n’est donc pas renvoyé dans votre dos : renvoyez-le vous-même. Les e-mails transactionnels ont leur propre file : ils n’attendent jamais derrière une campagne. La limite de débit du fournisseur s’applique toujours.

`status`	Signifie	Final
`pending`	En file, ou en attente d’un nouvel essai.	Non
`sent`	Remis au fournisseur. Pas encore délivré : voir plus bas.	Oui
`failed`	Pas envoyé, abandonné. Pourquoi est dans `failure_code` et `failure_reason`.	Oui

`failure_code`	Signifie
`recipients_suppressed`	Toutes les adresses de `to` sont sur la liste de suppression.
`monthly_quota_exceeded`	Le quota du mois était épuisé.
`sending_paused`	La période payée de l’équipe s’est terminée sans paiement.
`provider_error`	Le fournisseur l’a refusé à chaque essai, pendant six heures.
`queue_unavailable`	La file d’attente n’a pas pu le prendre.
`lost`	Encore `pending` sept heures après l’appel : sa tâche s’est perdue.

Le suivre par les webhooks

Plutôt que de relire l’e-mail encore et encore, laissez Lekalao vous prévenir. Abonnez une adresse aux événements transactional.* (Webhooks) :

Événement	Quand
`transactional.sent`	Le fournisseur l’a pris.
`transactional.delivered`	Le fournisseur le signale délivré, pour chaque adresse.
`transactional.bounced`	Il a rebondi, durement ou non.
`transactional.complained`	Un lecteur l’a signalé comme spam.
`transactional.opened`	La première ouverture.
`transactional.clicked`	Le premier clic sur chaque lien.
`transactional.failed`	Il ne partira pas, quelle qu’en soit la raison : `failure_code` dit laquelle.

Chacun porte l’e-mail tel que l’API le montre : gardez son id avec votre commande, et faites le lien par lui. sent veut dire que le fournisseur l’a, pas qu’il est arrivé. delivered_at est rempli quand le fournisseur signale une remise, bounced_at quand l’adresse a rebondi définitivement, complained_at quand un lecteur l’a signalé comme spam ; status reste sent, et après un rebond failure_reason prend la raison du fournisseur. L’adresse part dans la liste de suppression après un rebond dur ou une plainte : le prochain e-mail vers elle ne partira pas. La même nouvelle arrive aussi par mail.bounced et mail.complaint, avec transactional_mail égal à l’id de l’e-mail.

Ou le relire

Sans adresse de webhook, relisez l’e-mail avec GET /v1/transactional-mails/{id} jusqu’à ce que status ne soit plus pending. Le jeton doit pouvoir Lecture, ce que fait un jeton Lecture et écriture.

curl https://api.lekalao.com/v1/transactional-mails/e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10 \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Accept: application/json"

Espacez les appels. Ils comptent dans la limite du jeton (120 appels par minute par défaut), avec tout ce que fait le jeton :

// Node 18 ou plus. Lancez-le depuis une tâche de fond, jamais pendant que votre client attend.
async function followMail(id) {
  for (const seconds of [1, 2, 4, 8, 15, 30, 60]) {
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));

    const response = await fetch(`https://api.lekalao.com/v1/transactional-mails/${id}`, {
      headers: {
        Authorization: `Bearer ${process.env.LEKALAO_TOKEN}`,
        Accept: 'application/json',
      },
    });
    const { data } = await response.json();

    if (data.status !== 'pending') return data; // "sent" ou "failed"
  }

  return null; // Encore en attente après deux minutes : il est peut-être retenté. Regardez plus tard.
}

Quand l’appel lui-même échoue

Un délai dépassé ou un 5xx vous laisse sans savoir si Lekalao a l’e-mail. Renvoyez le même appel avec la même Idempotency-Key :

si Lekalao avait répondu la première fois, vous recevez cette première réponse, avec Idempotent-Replay: true, et aucun second e-mail ne part. C’est la réponse telle qu’elle était, pending compris : lisez l’e-mail pour savoir où il en est. Un 422 ou un 429 est gardé aussi : la même clé donne le même refus ;
un 502 n’est pas retenu : la même clé envoie de nouveau.

Une clé est gardée 24 heures. Voir Idempotence.

Suivre et renvoyer

Appel
`GET /transactional-mails?template=confirmation-commande&status=failed&to=ada@example.com`	Le journal, filtré.
`GET /transactional-mails/{id}`	Un e-mail, avec son statut, ses ouvertures et ses clics.
`GET /transactional-mails?sandbox=true`	Seulement les e-mails envoyés avec une clé de test ; `false`, seulement les vrais.
`POST /transactional-mails/{id}/resend`	Le renvoie, comme un nouvel e-mail, avec les mêmes réponses qu’un envoi. `409` `mail_not_kept` si le modèle ne conservait pas le contenu.

Un renvoi reprend les mêmes destinataires, variables, langue, objet et adresse d’expéditeur (from_email), et le même fournisseur. Il ne reprend pas les pièces jointes, qui ne sont jamais gardées, ni un from_name ou un reply_to donnés au premier appel : ceux du modèle, ou de l’équipe, sont utilisés. Un e-mail de test renvoyé reste un e-mail de test.

Sans rien envoyer

Une clé de test n’envoie rien : l’e-mail est vérifié, rendu et journalisé, marqué sent avec "sandbox": true, et compté dans aucun quota. Écrit à delivered@sink.lekalao.dev, bounced@sink.lekalao.dev et leurs voisines, il reçoit la réponse du fournisseur et ses webhooks, pour essayer vos gestionnaires de bout en bout.

Autres chemins

Une application Laravel peut garder Mail::to()->send() : voir Transport Laravel.
Un logiciel qui ne sait parler que SMTP : voir Relais SMTP.

L'API

Recettes

Intégrations

E-mails transactionnels

Avec un modèle

Sans modèle

Les champs

En plusieurs langues

La réponse

Ensuite, dans la file

Le suivre par les webhooks

Ou le relire

Quand l’appel lui-même échoue

Suivre et renvoyer

Sans rien envoyer

Autres chemins

​Avec un modèle

​Sans modèle

​Les champs

​En plusieurs langues

​La réponse

​Ensuite, dans la file

​Le suivre par les webhooks

​Ou le relire

​Quand l’appel lui-même échoue

​Suivre et renvoyer

​Sans rien envoyer

​Autres chemins

Avec un modèle

Sans modèle

Les champs

En plusieurs langues

La réponse

Ensuite, dans la file

Le suivre par les webhooks

Ou le relire

Quand l’appel lui-même échoue

Suivre et renvoyer

Sans rien envoyer

Autres chemins