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

# API transactionnelle

> Envoyez depuis votre application des emails déclenchés par des événements. Contrairement aux newsletters, les emails transactionnels partent vers un seul contact à la fois, en temps réel, et Notifuse crée ou met à jour le contact au moment de l'envoi. Utilisez-les pour les notifications que vos utilisateurs déclenchent et pour les workflows automatisés.

![La liste des notifications transactionnelles dans la console](https://www.notifuse.com/docs/assets/screenshots/transactional_api.png)

## Cas d'usage courants

```
- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations
```

## Fonctionnalités principales

### Gestion automatique des contacts

- L'objet `contact` de la requête crée le contact ou met à jour ses champs avant l'envoi, ce qui garde ses informations à jour.
- Les données du modèle (`data`) ne sont pas enregistrées sur le contact. Leurs clés deviennent des variables de premier niveau du modèle, et le profil enregistré du contact est disponible sous `contact`.

Cette mise à jour du contact demande la permission d'écriture Contacts. Sans elle, un envoi se contente de créer un contact manquant à partir de son adresse email et ne modifie jamais un contact existant (voir [Permissions](#permissions)).

### Enrichissement des données du modèle

Quand vous envoyez un email transactionnel, Notifuse :

1. Crée ou met à jour le contact, puis le recherche par adresse email dans votre espace de travail
2. Place les clés de `data` au premier niveau des variables du modèle, et le profil enregistré du contact sous `contact`
3. Rend le modèle avec les informations complètes du contact
4. Envoie l'email personnalisé

**Exemple** : si votre requête API envoie `"data": {"order_id": "12345"}` et que le profil du contact contient `{"first_name": "John", "last_name": "Doe"}`, le modèle peut utiliser `{{ order_id }}` et `{{ contact.first_name }}`.

### Dédoublonnage avec l'ID externe

- Définissez `external_id` pour ne pas envoyer deux fois la même notification : les notifications qui ont le même `external_id` ne partent qu'une fois.
- Utilisez vos propres identifiants uniques (ID de commande, ID d'événement, etc.).

**Exemple** : avec `external_id: "order-12345"`, la confirmation de commande n'est remise qu'une fois, même si votre système l'envoie plusieurs fois.

### Options d'envoi

Chaque envoi peut définir :

- **Nom de l'expéditeur** : remplace le nom d'affichage de l'expéditeur par défaut
- **Sujet** : remplace le sujet du modèle (accepte Liquid)
- **Répondre à** : définit des adresses de réponse personnalisées
- **CC** : ajoute des destinataires en copie
- **CCI** : ajoute des destinataires en copie cachée
- **Pièces jointes** : joint des fichiers aux emails (PDF, images, documents, etc.)

### Suivi

Le suivi des ouvertures et des clics dépend des réglages de l'espace de travail et du [consentement au tracking](https://www.notifuse.com/fr/docs/features/email-tracking.md) du contact. Un `contact` dans la requête peut porter `tracking_opens_consent` et `tracking_clicks_consent`, enregistrés avec la source `api`, sauf si vous envoyez `tracking_consent_source`. Chaque notification peut aussi désactiver le suivi :

- **Pas de tracking des ouvertures et des clics, UTM conservés** (`tracking_mode: "no_tracking"`)
- **Désactivé pour cette notification** (`tracking_mode: "disabled"`) : les liens ne sont jamais réécrits et ne portent ni suivi ni paramètres UTM. Utilisez ce mode pour les liens qui doivent rester tels quels, comme les liens de connexion

## Surveiller les envois dans la console

La page **Transactionnel** liste vos notifications avec leurs statistiques sur les 7, 30 ou 60 derniers jours, aujourd'hui compris :

- **Totaux** : emails envoyés, taux de remise avec son évolution depuis la période précédente, taux d'ouverture et de clic sur les emails suivis, échecs et rebonds.
- **Une ligne par notification** : son modèle, les emails envoyés, les taux de remise, d'ouverture et de clic, les échecs, le taux de rebond, et la date de son dernier envoi réussi. Un taux de remise sous 97 % et un taux de rebond à partir de 2 % sont mis en évidence. Vous pouvez chercher par nom ou par ID.
- **Actions de ligne** : envoyer un test, afficher la commande API, et depuis le menu, modifier la notification, prévisualiser le modèle, copier l'ID, ouvrir ses messages dans les [logs](https://www.notifuse.com/fr/docs/features/logs.md) ou la supprimer.

Cliquez sur une ligne pour ouvrir la vue détaillée de la notification, qui a son propre lien à partager. Elle affiche les mêmes statistiques pour cette notification, reliées aux messages correspondants dans les logs, ainsi que les envois par jour, les derniers envois (actualisés toutes les 30 secondes), un aperçu du modèle, ses réglages de suivi et d'UTM, l'expéditeur par défaut, et l'appel API en cURL, TypeScript et Python. **K** et **J** passent à la notification précédente ou suivante.

Avec un fournisseur SMTP, les taux de remise et de rebond ne sont pas disponibles, car SMTP n'envoie pas d'événements de remise. Les statistiques demandent la permission de lecture Historique des messages.

## Endpoint de l'API

Envoyez un email transactionnel avec une requête POST :

### Requête

```bash
curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'
```

### Paramètres

| Paramètre                    | Type   | Obligatoire | Description                                         |
| ---------------------------- | ------ | ----------- | --------------------------------------------------- |
| `workspace_id`               | string | Oui         | Identifiant de votre espace de travail              |
| `notification.id`            | string | Oui         | Identifiant du modèle de l'email                    |
| `notification.external_id`   | string | Non         | Identifiant unique pour le dédoublonnage            |
| `notification.channels`      | array  | Oui         | Doit inclure "email"                                |
| `notification.contact`       | object | Oui         | Objet contact avec au moins un champ email          |
| `notification.data`          | object | Non         | Variables du modèle pour le contenu de l'email      |
| `notification.metadata`      | object | Non         | Données de suivi (non disponibles dans les modèles) |
| `notification.email_options` | object | Non         | Configuration de l'acheminement de l'email          |

### Options d'email

| Paramètre     | Type   | Description                                                                                                                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_id`   | string | Envoie depuis cet expéditeur de l'intégration d'emails transactionnels au lieu de celui du modèle. Un ID inconnu est refusé avec une erreur 400 avant que le contact soit créé ou mis à jour |
| `from_name`   | string | Remplace le nom d'affichage de l'expéditeur par défaut                                                                                                                                       |
| `subject`     | string | Remplace le sujet du modèle (accepte Liquid, 255 caractères max.)                                                                                                                            |
| `reply_to`    | string | Définit une adresse de réponse personnalisée, à la place de celle du modèle                                                                                                                  |
| `cc`          | array  | Liste des destinataires en copie                                                                                                                                                             |
| `bcc`         | array  | Liste des destinataires en copie cachée                                                                                                                                                      |
| `attachments` | array  | Fichiers joints (20 fichiers max., 3 Mo par fichier, 10 Mo au total)                                                                                                                         |

## Données et métadonnées

### Variables du modèle (`data`)

L'objet `data` contient les variables que vos modèles d'email peuvent utiliser :

```json
{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}
```

Elles s'utilisent dans les modèles ainsi : `{{ order_id }}`, `{{ total }}`, `{{ discount_code }}`

### Données de suivi (`metadata`)

L'objet `metadata` stocke des informations destinées à l'analyse et au suivi, et n'est **pas disponible** dans les modèles :

```json
{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}
```

Utilisez les métadonnées pour le suivi interne, l'analyse et le reporting.

## Pièces jointes

Joignez des factures, des reçus, des billets ou d'autres documents à vos emails transactionnels. Les pièces jointes sont dédoublonnées automatiquement dans le stockage.

### Limites des pièces jointes

- **Nombre maximal de fichiers** : 20 pièces jointes par email
- **Taille d'un fichier** : 3 Mo par fichier
- **Taille totale** : 10 Mo par email
- **Formats acceptés** : tous les types de fichiers (PDF, PNG, JPEG, DOCX, etc.)

### Paramètres des pièces jointes

| Paramètre      | Type   | Obligatoire | Description                                                                                                                                                                          |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filename`     | string | Oui         | Nom du fichier (255 caractères max.)                                                                                                                                                 |
| `content`      | string | Oui         | Contenu du fichier encodé en Base64                                                                                                                                                  |
| `content_type` | string | Non         | Type MIME (par ex. "application/pdf"), détecté automatiquement s'il n'est pas fourni                                                                                                 |
| `disposition`  | string | Non         | "attachment" (par défaut) ou "inline"                                                                                                                                                |
| `content_id`   | string | Non         | Content-ID d'une pièce jointe inline, référencé depuis le corps HTML par `<img src="cid:...">`. Autorisé seulement quand `disposition` vaut "inline". Par défaut, le nom du fichier. |

### Exemple avec une facture PDF

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}
```

### Exemple avec plusieurs pièces jointes

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}
```

### Images inline (Content-ID)

Intégrez dans le corps de l'email des images propres à chaque destinataire, comme des QR codes ou des visuels personnalisés, au lieu de les héberger à une URL. Donnez à `disposition` la valeur `"inline"` et un `content_id` à la pièce jointe, puis faites-y référence dans le HTML de votre modèle avec `<img src="cid:...">` :

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}
```

Et dans le modèle d'email :

```html
<img src="cid:checkInQr" alt="Your check-in QR code" />
```

Remarques :

- `content_id` ne peut contenir que des lettres, des chiffres et les caractères `.` `_` `-` `@` (255 caractères max.), et n'est accepté que si `disposition` vaut `"inline"`.
- Quand `content_id` est omis, le nom du fichier sert de Content-ID : `<img src="cid:check-in-qr.png">` fonctionne donc aussi.
- Les images inline sont livrées dans une partie MIME `multipart/related`, à côté du corps HTML : les clients mail les affichent dans le corps et non comme des pièces jointes à télécharger.
- Comme l'image voyage dans le corps du message, les proxys de liens et les services de mise en cache d'images ne la récupèrent ni ne la journalisent jamais, ce qui convient aux secrets propres à chaque destinataire comme les QR codes.
- Sur Mailgun, le `content_id` devient aussi le nom de fichier de la partie livrée : préférez un `content_id` avec une extension de fichier (par ex. `checkInQr.png`) quand vous envoyez par Mailgun.

### Cas d'usage courants

- **Confirmations de commande** : joindre les factures et les reçus
- **Confirmations de réservation** : joindre les billets et les itinéraires
- **Documents juridiques** : joindre les contrats et les accords
- **Rapports** : joindre des rapports d'analyse et des synthèses
- **Certificats** : joindre des certificats de réussite et des badges
- **Billets d'événement** : intégrer en images inline des QR codes propres à chaque destinataire

## Bridge SMTP

Notifuse intègre un serveur bridge SMTP : vous pouvez envoyer des emails transactionnels depuis des clients SMTP standard au lieu d'appeler l'API HTTP. Il sert pour :

- **Systèmes hérités** : intégrer des applications existantes qui ne gèrent que SMTP
- **Bibliothèques d'email** : utiliser les bibliothèques d'email standard de n'importe quel langage de programmation
- **Intégration aux frameworks** : travailler avec des frameworks qui gèrent SMTP nativement
- **Migration progressive** : quitter vos fournisseurs d'email actuels sans modifier le code de l'application

### Fonctionnement

Le serveur bridge SMTP accepte les emails sur le port 587 (STARTTLS) ou 465 (TLS implicite). Le corps de l'email doit contenir un payload JSON au format de l'API transactionnelle, et vous vous authentifiez avec les identifiants API de votre espace de travail.

### Envoyer des emails par SMTP

#### Authentification

- **Nom d'utilisateur** : l'email API de votre espace de travail (l'email associé à votre clé API)
- **Mot de passe** : la clé API de votre espace de travail
- **Sécurité** : STARTTLS (port 587) ou TLS implicite / SMTPS (port 465), selon votre réglage `SMTP_BRIDGE_TLS`
- **Serveur** : l'hôte du bridge SMTP que vous avez configuré (par ex. `smtp.yourdomain.com`)

#### Format de l'email

Le corps de l'email doit être un payload JSON au format de l'API transactionnelle :

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}
```

## Permissions

La permission d'écriture **Transactionnel** suffit à elle seule pour envoyer, par l'API comme par le bridge SMTP. Une clé API en envoi seul est donc pratique : donnez à une clé l'écriture Transactionnel et rien d'autre, et elle peut envoyer des emails sans lire ni modifier un seul contact. Voir [Admins et clés API](https://www.notifuse.com/fr/docs/features/admins-api-keys.md).

Deux limites s'appliquent à une clé aussi restreinte, sur le bridge SMTP comme sur l'API :

- **Sans l'écriture Contacts**, un envoi crée toujours le contact du destinataire s'il n'existe pas encore, mais seule son adresse email est enregistrée. Tous les autres champs de l'objet `contact` sont ignorés, et un contact existant n'est jamais modifié.
- **Sans la lecture Contacts**, un envoi qui définit `cc` ou `bcc` est refusé. Sur le bridge SMTP, `cc` et `bcc` viennent des en-têtes `Cc:` et `Bcc:` du message : un identifiant en envoi seul qui les définit est rejeté au moment où le message est remis au serveur.

Ajoutez la lecture et l'écriture Contacts à la clé si elle doit enrichir les profils des contacts pendant l'envoi ou mettre d'autres destinataires en copie. Avec les deux, la clé se comporte comme avant.

L'écriture Transactionnel couvre tous les chemins qui envoient de vrais emails avec les identifiants de votre fournisseur : `/api/transactional.send`, `/api/transactional.testTemplate` et le bridge SMTP. Tester un fournisseur d'email (`/api/email.testProvider`) est réservé au propriétaire de l'espace de travail : une clé API ne peut donc pas le faire. Un email de test demande aussi la lecture Modèles d'email, et la lecture Listes quand il est envoyé pour une liste de diffusion (`list_id`).

La **lecture** Transactionnel ne couvre que les définitions des notifications (les lister et en ouvrir une). Elle ne permet pas à une clé d'envoyer.

## Intégration aux modèles

### Structure des données dans les modèles

Vos modèles peuvent utiliser à la fois les données de l'API et le profil du contact :

```liquid
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.
```

### Blocs conditionnels

Les blocs d'un modèle visuel peuvent n'être envoyés que lorsqu'une condition sur ces données est vérifiée, par exemple une section affichée seulement quand `order.total` est supérieur à 100. Voir [Blocs conditionnels](https://www.notifuse.com/fr/docs/features/templates.md#conditional-blocks).

### Exemple complet

**Requête API** :

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}
```

**Profil du contact existant** :

```json
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
```

**Disponible dans le modèle** :

```liquid
Hi {{ contact.first_name }}!

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.
```

## Référence de l'API

## Exemples de dédoublonnage

### Confirmations de commande

```json
{
  "external_id": "order-12345-confirmation"
}
```

### Réinitialisations de mot de passe

```json
{
  "external_id": "pwd-reset-user123-20240101"
}
```

### Emails de bienvenue

```json
{
  "external_id": "welcome-user123"
}
```

Des valeurs `external_id` construites toujours sur le même modèle évitent les notifications en double, même si votre application envoie plusieurs requêtes.

Pour la documentation complète de l'API et les autres paramètres, voir la [référence de l'API](https://www.notifuse.com/docs/api-reference/send-a-transactional-notification.md).
