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.
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
dataestá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 }}.
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 para conocer el editor y los datos de prueba que usa la vista previa.
- Las claves que envías en
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 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.
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.
Envía el correo desde tu backend
Llama a
POST /api/transactional.sendcon 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 unemailvá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
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 }Una llamada correcta devuelve
200con{"message_id": "…", "success": true}. Un error devuelve un cuerpo JSON con un campoerror, por ejemplo400si falta un campo o el identificador API no existe, y500cuando 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.
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.
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 recoge todos los campos de la petición, incluido
email_optionspara reply-to, CC, BCC y archivos adjuntos. - Crea una secuencia de bienvenida para los correos que siguen a un registro.
- Webhooks para recibir en tu aplicación los eventos de entrega y de rebote.
