> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lekalao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-mails transactionnels

> Confirmations de commande, factures, réinitialisations de mot de passe : un appel par e-mail.

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](/fr/transactional/overview).

## 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](/fr/transactional/templates)), puis :

```bash theme={null}
curl -X POST https://lekalao.example.com/api/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 :

```html theme={null}
<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](/fr/content/personalization).

## Sans modèle

Envoyez le HTML tel quel :

```bash theme={null}
curl -X POST https://lekalao.example.com/api/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.fr",
    "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. 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 configuré, pour forcer le chemin.          |
| `attachments`                         | 10 au plus : `name`, `content` en base64, `mime` facultatif.            |

## En plusieurs langues

Un modèle peut avoir une version par langue ([Langues](/fr/content/languages)). `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

`201` quand le fournisseur a accepté l'e-mail :

```json theme={null}
{
    "data": {
        "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10",
        "template": "confirmation-commande",
        "subject": "Commande 2026-00481 confirmée",
        "from": "bonjour@maboulangerie.fr",
        "to": ["ada@example.com"],
        "cc": [],
        "bcc": [],
        "status": "sent",
        "failure_reason": null,
        "opens": 0,
        "clicks": 0,
        "sent_at": "2026-09-17T10:14:03+00:00",
        "created_at": "2026-09-17T10:14:02+00:00"
    }
}
```

`502` quand le fournisseur a refusé : l'e-mail est journalisé avec `status: failed` et le motif dans `failure_reason`. Il est aussi `failed` quand le quota mensuel de la formule est épuisé.

`422` si l'expéditeur n'est pas autorisé, si ni `template` ni `html` n'est donné, ou s'il n'y a aucun destinataire.

<Note>
  L'envoi est synchrone : la réponse arrive quand le fournisseur a répondu.
  Appelez l'API depuis une tâche de fond de votre application, pas pendant la
  requête de votre client.
</Note>

## 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 ouvertures et clics.                                                                   |
| `POST /transactional-mails/{id}/resend`                                                    | Le renvoie à l'identique ; un nouvel e-mail est créé. `409` si le modèle ne conservait pas le contenu. |

Les rebonds et plaintes arrivent par les webhooks `mail.bounced` et `mail.complaint`.

## Autres chemins

* Une application **Laravel** peut garder `Mail::to()->send()` : voir [Transport Laravel](/fr/developers/laravel-transport).
* Un logiciel qui ne sait parler que **SMTP** : voir [Relais SMTP](/fr/developers/smtp-relay).