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

# Inviare email di reimpostazione password dalla tua app

> Crea una notifica transazionale per la reimpostazione della password e inviala dal tuo backend con una sola chiamata API.

Quando un utente chiede di reimpostare la password, la tua app chiama l'API di Notifuse. Notifuse gli invia un'email con il link di reimpostazione generato dalla tua app.

## Prima di iniziare

- Un workspace con un provider email impostato per le **Email transazionali** in Impostazioni › **Integrazioni**. Senza provider, la pagina **Transazionale** avvisa che le notifiche non possono essere inviate.
- Un backend che crea il link di reimpostazione (token, scadenza, pagina che lo verifica). Notifuse si limita a consegnare il link.
- L'ID del tuo workspace. È l'ID che hai scelto creando il workspace e compare nell'URL della console dopo `/console/workspace/`.
- L'indirizzo della tua istanza Notifuse, lo stesso da cui apri la console. Gli esempi usano `https://YOUR_NOTIFUSE_HOST`.

### 1. Crea il template email

Apri **Template**, fai clic su **Nuovo modello** e scegli il modello **Reimpostazione password** nella **Galleria**. Contiene già un pulsante e una copia del link in testo semplice, entrambi rivolti a `{{ reset_url }}`.

Puoi anche partire da un template vuoto. In questo caso imposta la sua **Categoria** su **Transazionale**, perché una notifica elenca solo i template di quella categoria.

Il template può usare due tipi di variabili:

- Le chiavi che invii in `data` stanno al livello principale. Scrivi `{{ reset_url }}`, non `{{ data.reset_url }}`.
- Il contatto si trova sotto `contact`, per esempio `{{ contact.first_name }}` o `{{ contact.email }}`.

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

<a href="{{ reset_url }}">Choose a new password</a>
```

Imposta **Oggetto** e **Mittente** nelle impostazioni del template, poi salva. Consulta [Template](https://www.notifuse.com/it/docs/features/templates.md) per l'editor e per i dati di test usati dall'anteprima.

### 2. Crea la notifica transazionale

Apri **Transazionale** e fai clic su **Nuova notifica**. Compila:

- **Nome**: il nome che vedrai nella console, per esempio "Password Reset Email".
- **Identificatore API**: il valore che invia il tuo codice, per esempio `password_reset`. Solo lettere minuscole, numeri e underscore, al massimo 32 caratteri. Non si può modificare dopo la creazione della notifica.
- **Template email**: il template del passaggio 1.

Fai clic su **Crea notifica**.

![Una notifica transazionale: il nome, l'identificatore API fisso password_reset e il template email](https://www.notifuse.com/docs/assets/screenshots/transactional_notification_edit.png)

La pagina della notifica ha un pannello **Chiamata API** con una richiesta pronta in cURL, TypeScript e Python. **Tutti i linguaggi** ne mostra altre.

### 3. Crea una API Key

Vai in Impostazioni › **Team e API Key** e fai clic su **Crea chiave API**. Assegnale un **Nome API Key**, per esempio "Backend password reset".

In **Permessi**, la scrittura su **Transazionale** basta per inviare. Una chiave senza altri permessi può inviare email ma non può leggere né modificare i tuoi contatti. Se la console indica che i permessi personalizzati richiedono una licenza Notifuse Studio, la chiave può avere solo l'accesso completo, e per questa guida funziona allo stesso modo.

Fai clic su **Crea chiave API** e copia subito il token: viene mostrato una sola volta e non si può recuperare. Conservalo tra i segreti del backend, mai nel codice eseguito dal browser.

### 4. Invia l'email dal tuo backend

Chiama `POST /api/transactional.send` passando il token come bearer token. Il body deve contenere:

- `workspace_id`: l'ID del tuo workspace.
- `notification.id`: l'identificatore API, `password_reset`.
- `notification.channels`: `["email"]`. Serve almeno un canale.
- `notification.contact`: il destinatario, con almeno un campo `email` valido.
- `notification.data`: le variabili del template, qui `reset_url`.
- `notification.external_id` (facoltativo): un tuo ID per questo invio, che serve a evitare i duplicati. Vedi la sezione successiva.

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

Una chiamata riuscita restituisce `200` con `{"message_id": "…", "success": true}`. Un errore restituisce un body JSON con un campo `error`, per esempio `400` per un campo mancante o un identificatore API sconosciuto, e `500` quando l'invio fallisce presso il provider.

## Evitare email duplicate con external_id

Se nel workspace esiste già un messaggio con lo stesso `external_id`, Notifuse non invia nulla e restituisce il `message_id` del primo messaggio. Così il tuo codice può ripetere una chiamata andata in timeout senza che l'utente riceva due email.

Usa un `external_id` per ogni richiesta di reimpostazione, per esempio l'ID utente più l'ID o la data di creazione del token. Se più tardi l'utente chiede un nuovo link, la nuova richiesta ha bisogno di un nuovo `external_id`. Altrimenti la chiamata riesce ma non parte nessuna email.

## Campi del contatto e chiave di solo invio

Notifuse crea il contatto quando l'indirizzo email non è ancora nel workspace. Con una chiave che ha solo la scrittura su **Transazionale**:

- Un nuovo contatto viene salvato con il solo indirizzo email. Gli altri campi che invii, come `first_name`, vengono scartati, quindi `{{ contact.first_name }}` resta vuoto in quella prima email.
- Un contatto esistente non viene mai modificato e il template usa i campi già salvati.

Se l'email deve salutare l'utente per nome, aggiungi alla chiave la scrittura su **Contatti**, oppure invia il nome in `data` e scrivi `{{ first_name }}` nel template. Consulta [API transazionale](https://www.notifuse.com/it/docs/features/transactional-api.md#permissions).

## Verificare che funzioni

Avvia dalla tua app una reimpostazione per il tuo indirizzo, oppure esegui l'esempio cURL con quell'indirizzo.

Apri **Log**, resta nella scheda **Messaggi** e cerca il tuo indirizzo email o l'`external_id` che hai inviato. Il messaggio deve avere l'origine **Transazionale**. Fai clic per vedere i suoi eventi (inviato, consegnato, aperto) e, sotto **Dati**, il `reset_url` con cui è stato inviato. Consulta [Log](https://www.notifuse.com/it/docs/features/logs.md).

![Un messaggio aperto in Log, con i suoi eventi di consegna e i dati con cui è stato inviato](https://www.notifuse.com/docs/assets/screenshots/logs_message_detail.png)

Invia la stessa richiesta una seconda volta: la risposta restituisce lo stesso `message_id` e in **Log** non compare una seconda email.

## Prossimi passi

- [API transazionale](https://www.notifuse.com/it/docs/features/transactional-api.md) elenca tutti i campi della richiesta, compreso `email_options` per reply-to, CC, BCC e allegati.
- [Crea una sequenza di benvenuto](https://www.notifuse.com/it/docs/guides/welcome-sequence.md) per le email che seguono una registrazione.
- [Webhook](https://www.notifuse.com/it/docs/features/webhooks.md) per ricevere nella tua app gli eventi di consegna e di bounce.
