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
contactde 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 souscontact.
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).
Enrichissement des données du modèle
Quand vous envoyez un email transactionnel, Notifuse :
- Crée ou met à jour le contact, puis le recherche par adresse email dans votre espace de travail
- Place les clés de
dataau premier niveau des variables du modèle, et le profil enregistré du contact souscontact - Rend le modèle avec les informations complètes du contact
- 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_idpour ne pas envoyer deux fois la même notification : les notifications qui ont le mêmeexternal_idne 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 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 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
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 :
{
"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 :
{
"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
{
"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
{
"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:..."> :
{
"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 :
<img src="cid:checkInQr" alt="Your check-in QR code" />
Remarques :
content_idne peut contenir que des lettres, des chiffres et les caractères._-@(255 caractères max.), et n’est accepté que sidispositionvaut"inline".- Quand
content_idest 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_iddevient aussi le nom de fichier de la partie livrée : préférez uncontent_idavec 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 :
{
"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.
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
contactsont ignorés, et un contact existant n’est jamais modifié. - Sans la lecture Contacts, un envoi qui définit
ccoubccest refusé. Sur le bridge SMTP,ccetbccviennent des en-têtesCc:etBcc: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 :
<!-- 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.
Exemple complet
Requête API :
{
"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 :
{
"first_name": "Sarah",
"last_name": "Johnson",
"email": "sarah@example.com",
"phone": "+1234567890"
}
Disponible dans le modèle :
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
{
"external_id": "order-12345-confirmation"
}
Réinitialisations de mot de passe
{
"external_id": "pwd-reset-user123-20240101"
}
Emails de bienvenue
{
"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.
