Quand un utilisateur demande à réinitialiser son mot de passe, votre application appelle l’API Notifuse. Notifuse lui envoie alors un email contenant le lien de réinitialisation que votre application a généré.
Avant de commencer
- Un espace de travail dont un fournisseur d’email est défini pour les Emails transactionnels dans Paramètres › Intégrations. Sans lui, la page Transactionnel signale que les notifications ne peuvent pas être envoyées.
- Un backend qui crée le lien de réinitialisation (jeton, date d’expiration, page qui le vérifie). Notifuse se contente de remettre le lien.
- L’ID de votre espace de travail. C’est l’ID choisi à la création de l’espace de travail ; il figure dans l’URL de la console, après
/console/workspace/. - L’adresse de votre instance Notifuse, celle sur laquelle vous ouvrez la console. Les exemples utilisent
https://YOUR_NOTIFUSE_HOST.
Créer le modèle d'email
Ouvrez Modèles d’email, cliquez sur Nouveau modèle et choisissez le modèle Réinitialisation du mot de passe dans la Galerie. Il contient déjà un bouton et une copie du lien en texte brut, qui pointent tous deux vers
{{ reset_url }}.Vous pouvez aussi partir d’un modèle vierge. Réglez alors sa Catégorie sur Transactionnel, car une notification ne propose que les modèles de cette catégorie.
Le modèle peut utiliser deux sortes de variables :
- Les clés envoyées dans
datase trouvent au premier niveau. Écrivez{{ reset_url }}, et non{{ data.reset_url }}. - Le contact se trouve sous
contact, par exemple{{ contact.first_name }}ou{{ contact.email }}.
Hi {{ contact.first_name }}, <a href="{{ reset_url }}">Choose a new password</a>Renseignez le Sujet et l’Expéditeur dans les paramètres du modèle, puis enregistrez. La page Modèles d’email décrit l’éditeur et les données de test qu’utilise l’aperçu.
- Les clés envoyées dans
Créer la notification transactionnelle
Ouvrez Transactionnel et cliquez sur Nouvelle notification. Remplissez :
- Nom : ce que vous verrez dans la console, par exemple « Email de réinitialisation du mot de passe ».
- Identifiant API : ce que votre code envoie, par exemple
password_reset. Uniquement des lettres minuscules, des chiffres et des tirets bas, 32 caractères au plus. Il ne peut plus changer une fois la notification créée. - Modèle d’email : le modèle de l’étape 1.
Cliquez sur Créer la notification.
Une notification transactionnelle : son nom, l'identifiant API fixe password_reset et son modèle d'email La page de la notification comporte un panneau Appel API avec une requête prête à l’emploi en cURL, TypeScript et Python ; Tous les langages en affiche d’autres.
Créer une clé API
Allez dans Paramètres › Équipe et clés API et cliquez sur Créer une clé API. Donnez-lui un Nom de la clé API, par exemple « Backend réinitialisation mot de passe ».
Sous Permissions, l’écriture Transactionnel suffit pour envoyer. Une clé qui n’a que ce droit peut envoyer des emails, mais ne peut ni lire ni modifier vos contacts. Si la console indique que les permissions personnalisées nécessitent une licence Notifuse Studio, la clé ne peut avoir que l’accès complet, et elle fonctionne de la même façon pour ce guide.
Cliquez sur Créer une clé API et copiez le jeton tout de suite : il ne s’affiche qu’une fois et ne peut pas être récupéré ensuite. Rangez-le dans les secrets de votre backend, jamais dans du code exécuté par le navigateur.
Envoyer l'email depuis votre backend
Appelez
POST /api/transactional.sendavec le jeton comme bearer token. Le corps de la requête contient :workspace_id: l’ID de votre espace de travail.notification.id: l’identifiant API,password_reset.notification.channels:["email"]. Au moins un canal est obligatoire.notification.contact: le destinataire, avec au minimum unemailvalide.notification.data: les variables du modèle, icireset_url.notification.external_id(facultatif) : votre propre ID pour cet envoi, qui sert à éviter les doublons. Voir la section suivante.
cURL
curl -X POST "https://YOUR_NOTIFUSE_HOST/api/transactional.send" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workspace_id": "YOUR_WORKSPACE_ID", "notification": { "id": "password_reset", "external_id": "pwd-reset-u123-1700000000", "channels": ["email"], "contact": { "email": "user@example.com", "first_name": "Ada" }, "data": { "reset_url": "https://app.example.com/reset?token=abc123" } } }'Node.js
// Node.js 18 or later (built-in fetch) async function sendPasswordReset(user, resetRequestId, resetUrl) { const response = await fetch('https://YOUR_NOTIFUSE_HOST/api/transactional.send', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NOTIFUSE_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ workspace_id: 'YOUR_WORKSPACE_ID', notification: { id: 'password_reset', external_id: `pwd-reset-${user.id}-${resetRequestId}`, channels: ['email'], contact: { email: user.email, first_name: user.firstName }, data: { reset_url: resetUrl } } }) }) const result = await response.json() if (!response.ok) { throw new Error(`Notifuse error ${response.status}: ${result.error}`) } return result.message_id }Python
import os import requests def send_password_reset(user, reset_request_id, reset_url): response = requests.post( "https://YOUR_NOTIFUSE_HOST/api/transactional.send", headers={"Authorization": f"Bearer {os.environ['NOTIFUSE_API_KEY']}"}, json={ "workspace_id": "YOUR_WORKSPACE_ID", "notification": { "id": "password_reset", "external_id": f"pwd-reset-{user['id']}-{reset_request_id}", "channels": ["email"], "contact": {"email": user["email"], "first_name": user["first_name"]}, "data": {"reset_url": reset_url}, }, }, timeout=10, ) result = response.json() if not response.ok: raise RuntimeError(f"Notifuse error {response.status_code}: {result.get('error')}") return result["message_id"]PHP
<?php function sendPasswordReset(array $user, string $resetRequestId, string $resetUrl): string { $payload = [ 'workspace_id' => 'YOUR_WORKSPACE_ID', 'notification' => [ 'id' => 'password_reset', 'external_id' => "pwd-reset-{$user['id']}-{$resetRequestId}", 'channels' => ['email'], 'contact' => ['email' => $user['email'], 'first_name' => $user['first_name']], 'data' => ['reset_url' => $resetUrl], ], ]; $ch = curl_init('https://YOUR_NOTIFUSE_HOST/api/transactional.send'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('NOTIFUSE_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_TIMEOUT => 10, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $result = json_decode($body, true); if ($status !== 200) { throw new RuntimeException("Notifuse error {$status}: " . ($result['error'] ?? $body)); } return $result['message_id']; }Go
package notify import ( "bytes" "encoding/json" "fmt" "net/http" "os" "time" ) func SendPasswordReset(userID, email, firstName, resetRequestID, resetURL string) (string, error) { payload := map[string]any{ "workspace_id": "YOUR_WORKSPACE_ID", "notification": map[string]any{ "id": "password_reset", "external_id": fmt.Sprintf("pwd-reset-%s-%s", userID, resetRequestID), "channels": []string{"email"}, "contact": map[string]string{"email": email, "first_name": firstName}, "data": map[string]string{"reset_url": resetURL}, }, } body, err := json.Marshal(payload) if err != nil { return "", err } req, err := http.NewRequest(http.MethodPost, "https://YOUR_NOTIFUSE_HOST/api/transactional.send", bytes.NewReader(body)) if err != nil { return "", err } req.Header.Set("Authorization", "Bearer "+os.Getenv("NOTIFUSE_API_KEY")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 10 * time.Second} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() var result struct { MessageID string `json:"message_id"` Error string `json:"error"` } if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return "", err } if resp.StatusCode != http.StatusOK { return "", fmt.Errorf("notifuse error %d: %s", resp.StatusCode, result.Error) } return result.MessageID, nil }Un appel réussi renvoie
200avec{"message_id": "…", "success": true}. Une erreur renvoie un corps JSON avec un champerror, par exemple400pour un champ manquant ou un identifiant API inconnu, et500quand l’envoi échoue chez le fournisseur.
Éviter les emails en double avec external_id
Si un message avec le même external_id existe déjà dans l’espace de travail, Notifuse n’envoie rien et renvoie le message_id du premier message. Votre code peut donc relancer un appel qui a expiré sans que l’utilisateur reçoive deux emails.
Utilisez un external_id par demande de réinitialisation, par exemple l’ID de l’utilisateur suivi de l’ID ou de la date de création du jeton. Si l’utilisateur demande un nouveau lien plus tard, la nouvelle demande doit avoir un nouvel external_id. Sinon l’appel réussit, mais aucun email ne part.
Champs du contact et clé limitée à l’envoi
Notifuse crée le contact quand l’adresse email n’existe pas encore dans l’espace de travail. Avec une clé qui n’a que l’écriture Transactionnel :
- Un nouveau contact est enregistré avec sa seule adresse email. Les autres champs envoyés, comme
first_name, sont ignorés :{{ contact.first_name }}est donc vide dans ce premier email. - Un contact existant n’est jamais modifié, et le modèle utilise les champs déjà enregistrés.
Si l’email doit saluer l’utilisateur par son nom, ajoutez l’écriture Contacts à la clé, ou envoyez le nom dans data et écrivez {{ first_name }} dans le modèle. Voir API transactionnelle.
Vérifier que tout fonctionne
Déclenchez une réinitialisation pour votre propre adresse depuis votre application, ou lancez l’exemple cURL avec cette adresse.
Ouvrez Logs, restez sur l’onglet Messages et cherchez votre adresse email ou l’external_id envoyé. Le message doit avoir l’origine Transactionnel. Cliquez dessus pour voir ses événements (envoyé, délivré, ouvert) et, sous Données, le reset_url avec lequel il est parti. Voir Logs.
Envoyez la même requête une seconde fois : la réponse renvoie le même message_id, et aucun deuxième email n’apparaît dans Logs.
Étapes suivantes
- API transactionnelle liste tous les champs de la requête, dont
email_optionspour l’adresse de réponse (reply-to), CC, BCC et les pièces jointes. - Créez une séquence de bienvenue pour les emails qui suivent une inscription.
- Webhooks pour recevoir dans votre application les événements de remise et de rebond.
