Aller au contenu

Emails produit

Envoyer les emails de réinitialisation de mot de passe depuis votre application

Créez une notification transactionnelle pour la réinitialisation du mot de passe et envoyez-la depuis votre backend en un seul appel API.

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.
  1. 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 data se 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.

  2. 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
    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.

  3. 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.

  4. Envoyer l'email depuis votre backend

    Appelez POST /api/transactional.send avec 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 un email valide.
    • notification.data : les variables du modèle, ici reset_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 200 avec {"message_id": "…", "success": true}. Une erreur renvoie un corps JSON avec un champ error, par exemple 400 pour un champ manquant ou un identifiant API inconnu, et 500 quand 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.

Un message ouvert dans les Logs, avec ses événements de remise et les données envoyées
Un message ouvert dans les Logs, avec ses événements de remise et les données envoyées

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_options pour 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.