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

# Envía correos de restablecimiento de contraseña desde tu aplicación

> Crea una notificación transaccional para restablecer contraseñas y envíala desde tu backend con una sola llamada a la API.

Cuando un usuario pide restablecer su contraseña, tu aplicación llama a la API de Notifuse, y Notifuse le envía un correo con el enlace de restablecimiento que generó tu aplicación.

## Antes de empezar

- Un espacio de trabajo con un proveedor de correo asignado a **Correos transaccionales** en Configuración › **Integraciones**. Si no lo tiene, la página **Transaccional** avisa de que las notificaciones no se pueden enviar.
- Un backend que cree el enlace de restablecimiento (el token, su caducidad y la página que lo comprueba). Notifuse solo entrega el enlace.
- El ID de tu espacio de trabajo. Es el ID que elegiste al crear el espacio de trabajo, y aparece en la URL de la consola después de `/console/workspace/`.
- La dirección de tu instancia de Notifuse, la misma en la que abres la consola. Los ejemplos usan `https://YOUR_NOTIFUSE_HOST`.

### 1. Crea la plantilla de correo

Abre **Plantillas**, haz clic en **Nueva plantilla** y elige el modelo **Restablecimiento de contraseña** en la **Galería**. Ya incluye un botón y una copia del enlace en texto plano, los dos apuntando a `{{ reset_url }}`.

También puedes partir de una plantilla en blanco. Establece su **Categoría** en **Transaccional**, porque una notificación solo muestra las plantillas de esa categoría.

La plantilla puede usar dos tipos de variables:

- Las claves que envías en `data` están en el nivel superior. Escribe `{{ reset_url }}`, no `{{ data.reset_url }}`.
- El contacto está en `contact`, por ejemplo `{{ contact.first_name }}` o `{{ contact.email }}`.

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

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

Define el **Asunto** y el **Remitente** en los ajustes de la plantilla y guarda. Consulta [Plantillas](https://www.notifuse.com/es/docs/features/templates.md) para conocer el editor y los datos de prueba que usa la vista previa.

### 2. Crea la notificación transaccional

Abre **Transaccional** y haz clic en **Nueva notificación**. Rellena:

- **Nombre**: lo que verás en la consola, por ejemplo "Correo de restablecimiento de contraseña".
- **Identificador API**: lo que envía tu código, por ejemplo `password_reset`. Solo letras minúsculas, números y guiones bajos, 32 caracteres como máximo. No se puede cambiar una vez creada la notificación.
- **Plantilla de correo**: la plantilla del paso 1.

Haz clic en **Crear notificación**.

![Una notificación transaccional: su nombre, el identificador API fijo password_reset y su plantilla de correo](https://www.notifuse.com/docs/assets/screenshots/transactional_notification_edit.png)

La página de la notificación tiene un panel **Llamada a la API** con una petición lista para usar en cURL, TypeScript y Python, y **Todos los lenguajes** muestra más.

### 3. Crea una clave API

Ve a Configuración › **Equipo y claves API** y haz clic en **Crear clave API**. Dale un **Nombre de clave API**, como "Restablecimiento de contraseña del backend".

En **Permisos**, basta con el permiso de escritura en **Transaccional** para enviar. Una clave que solo tiene ese permiso puede enviar correos, pero no puede leer ni modificar tus contactos. Si la consola indica que los permisos personalizados requieren una licencia de Notifuse Studio, la clave solo puede tener acceso completo, y para esta guía funciona igual.

Haz clic en **Crear clave API** y copia el token en ese momento: se muestra una sola vez y no se puede recuperar después. Guárdalo en los secretos de tu backend, nunca en el código del navegador.

### 4. Envía el correo desde tu backend

Llama a `POST /api/transactional.send` con el token como token Bearer. El cuerpo necesita:

- `workspace_id`: el ID de tu espacio de trabajo.
- `notification.id`: el identificador API, `password_reset`.
- `notification.channels`: `["email"]`. Se necesita al menos un canal.
- `notification.contact`: el destinatario, con al menos un `email` válido.
- `notification.data`: las variables de la plantilla, aquí `reset_url`.
- `notification.external_id` (opcional): tu propio ID para este envío, que sirve para evitar duplicados. Consulta la sección siguiente.

**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 llamada correcta devuelve `200` con `{"message_id": "…", "success": true}`. Un error devuelve un cuerpo JSON con un campo `error`, por ejemplo `400` si falta un campo o el identificador API no existe, y `500` cuando el envío falla en el proveedor.

## Evita correos duplicados con external_id

Si en el espacio de trabajo ya existe un mensaje con el mismo `external_id`, Notifuse no envía nada y devuelve el `message_id` del primer mensaje. Así tu código puede repetir una llamada que agotó el tiempo de espera sin que el usuario reciba dos correos.

Usa un `external_id` por cada solicitud de restablecimiento, por ejemplo el ID del usuario más el ID o la hora de creación del token. Si el usuario pide un enlace nuevo más tarde, la nueva solicitud necesita un `external_id` nuevo; si no, la llamada se completa sin error y no sale ningún correo.

## Campos del contacto y clave solo de envío

Notifuse crea el contacto cuando la dirección de correo todavía no está en el espacio de trabajo. Con una clave que solo tiene el permiso de escritura en **Transaccional**:

- Un contacto nuevo se guarda solo con la dirección de correo. Los demás campos que envías, como `first_name`, se descartan, así que `{{ contact.first_name }}` queda vacío en ese primer correo.
- Un contacto existente nunca se modifica, y la plantilla usa los campos que ya están guardados.

Si el correo tiene que saludar al usuario por su nombre, añade a la clave el permiso de escritura en **Contactos**, o envía el nombre en `data` y escribe `{{ first_name }}` en la plantilla. Consulta [API transaccional](https://www.notifuse.com/es/docs/features/transactional-api.md#permissions).

## Comprueba que funciona

Lanza un restablecimiento para tu propia dirección desde tu aplicación, o ejecuta el ejemplo de cURL con ella.

Abre **Registros**, quédate en la pestaña **Mensajes** y busca tu dirección de correo o el `external_id` que enviaste. El mensaje debería mostrar el origen **Transaccional**. Haz clic en él para ver sus eventos (enviado, entregado, abierto) y, en **Datos**, el `reset_url` con el que se envió. Consulta [Registros](https://www.notifuse.com/es/docs/features/logs.md).

![Un mensaje abierto en Registros, con sus eventos de entrega y los datos con los que se envió](https://www.notifuse.com/docs/assets/screenshots/logs_message_detail.png)

Envía la misma petición por segunda vez: la respuesta devuelve el mismo `message_id` y no aparece un segundo correo en **Registros**.

## Siguientes pasos

- [API transaccional](https://www.notifuse.com/es/docs/features/transactional-api.md) recoge todos los campos de la petición, incluido `email_options` para reply-to, CC, BCC y archivos adjuntos.
- [Crea una secuencia de bienvenida](https://www.notifuse.com/es/docs/guides/welcome-sequence.md) para los correos que siguen a un registro.
- [Webhooks](https://www.notifuse.com/es/docs/features/webhooks.md) para recibir en tu aplicación los eventos de entrega y de rebote.
