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

# 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 }}`.

```liquid
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](https://www.notifuse.com/fr/docs/features/templates.md) 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](https://www.notifuse.com/docs/assets/screenshots/transactional_notification_edit.png)

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**

```bash
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**

```javascript
// 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**

```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
<?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**

```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](https://www.notifuse.com/fr/docs/features/transactional-api.md#permissions).

## 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](https://www.notifuse.com/fr/docs/features/logs.md).

![Un message ouvert dans les Logs, avec ses événements de remise et les données envoyées](https://www.notifuse.com/docs/assets/screenshots/logs_message_detail.png)

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](https://www.notifuse.com/fr/docs/features/transactional-api.md) 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](https://www.notifuse.com/fr/docs/guides/welcome-sequence.md) pour les emails qui suivent une inscription.
- [Webhooks](https://www.notifuse.com/fr/docs/features/webhooks.md) pour recevoir dans votre application les événements de remise et de rebond.
