Saltar al contenido

Correos de producto

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

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

  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

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

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.

Un mensaje abierto en Registros, con sus eventos de entrega y los datos con los que se envió
Un mensaje abierto en Registros, con sus eventos de entrega y los datos con los que se envió

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