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

# API transaccional

> Envía correos disparados por eventos desde tu aplicación. A diferencia de los envíos masivos, los correos transaccionales van a un solo contacto cada vez, en tiempo real, y Notifuse crea o actualiza el contacto al enviar. Úsalos para las notificaciones que disparan tus usuarios y para los flujos automatizados.

![Lista de notificaciones transaccionales en la consola](https://www.notifuse.com/docs/assets/screenshots/transactional_api.png)

## Casos de uso habituales

```
- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations
```

## Funciones principales

### Gestión automática de contactos

- El objeto `contact` de la solicitud crea el contacto o actualiza sus campos antes del envío, así su información se mantiene al día.
- Los datos de la plantilla (`data`) no se guardan en el contacto. Sus claves pasan a ser variables de primer nivel de la plantilla, y el perfil guardado del contacto está disponible en `contact`.

Para actualizar el contacto de esta forma hace falta el permiso de escritura de Contactos. Sin él, un envío solo crea el contacto que falta a partir de su dirección de correo y nunca modifica uno existente (consulta [Permisos](#permissions)).

### Enriquecimiento de los datos de la plantilla

Cuando envías un correo transaccional, Notifuse:

1. Crea o actualiza el contacto y luego lo busca por su dirección de correo en tu espacio de trabajo
2. Pone las claves de `data` en el primer nivel de las variables de la plantilla, y el perfil guardado del contacto en `contact`
3. Genera la plantilla con toda la información del contacto
4. Envía el correo personalizado

**Ejemplo**: si tu API envía `"data": {"order_id": "12345"}` y el perfil del contacto contiene `{"first_name": "John", "last_name": "Doe"}`, la plantilla puede usar `{{ order_id }}` y `{{ contact.first_name }}`.

### Deduplicación con ID externo

- Define `external_id` para no enviar dos veces la misma notificación: las notificaciones con el mismo `external_id` solo se envían una vez.
- Usa tus propios identificadores únicos (ID de pedido, ID de evento, etc.).

**Ejemplo**: con `external_id: "order-12345"`, la confirmación de pedido se entrega una sola vez, aunque tu sistema la envíe varias veces.

### Opciones de entrega del correo

Cada envío puede definir:

- **Nombre del remitente**: sustituye el nombre visible del remitente predeterminado
- **Asunto**: sustituye el asunto de la plantilla (admite Liquid)
- **Responder a**: define direcciones de respuesta personalizadas
- **CC**: añade destinatarios en copia
- **CCO**: añade destinatarios en copia oculta
- **Adjuntos**: adjunta archivos a los correos (PDF, imágenes, documentos, etc.)

### Seguimiento

Las aperturas y los clics siguen la configuración del espacio de trabajo y el [consentimiento de seguimiento](https://www.notifuse.com/es/docs/features/email-tracking.md) del contacto. Un `contact` en la solicitud puede llevar `tracking_opens_consent` y `tracking_clicks_consent`, que se registran con el origen `api` salvo que envíes `tracking_consent_source`. Cada notificación también puede desactivar el seguimiento:

- **Sin seguimiento de aperturas ni clics, conservar UTM** (`tracking_mode: "no_tracking"`)
- **Deshabilitado para esta notificación** (`tracking_mode: "disabled"`): los enlaces nunca se reescriben y no llevan ni seguimiento ni parámetros UTM. Úsalo para enlaces que deben quedarse como están, como los enlaces de inicio de sesión

## Supervisión en la consola

La página **Transaccional** muestra tus notificaciones con sus estadísticas de los últimos 7, 30 o 60 días, hoy incluido:

- **Totales**: correos enviados, tasa de entrega con su variación respecto al periodo anterior, tasas de apertura y de clics de los correos con seguimiento, fallos y rebotes.
- **Una fila por notificación**: su plantilla, los correos enviados, las tasas de entrega, apertura y clics, los fallos, la tasa de rebote y la fecha de su último envío correcto. Se resaltan una tasa de entrega por debajo del 97 % y una tasa de rebote a partir del 2 %. Puedes buscar por nombre o por ID.
- **Acciones de fila**: enviar una prueba, mostrar el comando de la API y, desde el menú, editar, ver la vista previa de la plantilla, copiar el ID, abrir sus mensajes en los [registros](https://www.notifuse.com/es/docs/features/logs.md) o eliminarla.

Haz clic en una fila para abrir la vista de detalle de la notificación, que tiene su propio enlace para compartir. Muestra las mismas estadísticas para esa notificación, enlazadas con los mensajes correspondientes de los registros, además de los envíos por día, los últimos envíos (actualizados cada 30 segundos), una vista previa de la plantilla, su configuración de seguimiento y de UTM, el remitente predeterminado y la llamada a la API en cURL, TypeScript y Python. **K** y **J** pasan a la notificación anterior o a la siguiente.

Con un proveedor SMTP, las tasas de entrega y de rebote no están disponibles, porque SMTP no envía eventos de entrega. Las estadísticas requieren el permiso de lectura del historial de mensajes.

## Endpoint de la API

Envía un correo transaccional con una solicitud POST:

### Solicitud

```bash
curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'
```

### Parámetros

| Parámetro                    | Tipo   | Obligatorio | Descripción                                             |
| ---------------------------- | ------ | ----------- | ------------------------------------------------------- |
| `workspace_id`               | string | Sí          | Identificador de tu espacio de trabajo                  |
| `notification.id`            | string | Sí          | Identificador de la plantilla del correo                |
| `notification.external_id`   | string | No          | Identificador único para la deduplicación               |
| `notification.channels`      | array  | Sí          | Debe incluir "email"                                    |
| `notification.contact`       | object | Sí          | Objeto de contacto con al menos un campo email          |
| `notification.data`          | object | No          | Variables de la plantilla para el contenido del correo  |
| `notification.metadata`      | object | No          | Datos de seguimiento (no disponibles en las plantillas) |
| `notification.email_options` | object | No          | Configuración del envío del correo                      |

### Opciones del correo

| Parámetro     | Tipo   | Descripción                                                                                                                                                                        |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_id`   | string | Envía desde este remitente de la integración de correo transaccional en lugar del de la plantilla. Un ID desconocido se rechaza con un 400 antes de crear o actualizar el contacto |
| `from_name`   | string | Sustituye el nombre visible del remitente predeterminado                                                                                                                           |
| `subject`     | string | Sustituye el asunto de la plantilla (admite Liquid, 255 como máximo)                                                                                                               |
| `reply_to`    | string | Define una dirección de respuesta personalizada, en lugar de la de la plantilla                                                                                                    |
| `cc`          | array  | Lista de destinatarios en copia                                                                                                                                                    |
| `bcc`         | array  | Lista de destinatarios en copia oculta                                                                                                                                             |
| `attachments` | array  | Archivos adjuntos (20 archivos como máximo, 3 MB por archivo, 10 MB en total)                                                                                                      |

## Data frente a metadata

### Variables de la plantilla (`data`)

El objeto `data` contiene las variables que pueden usar tus plantillas de correo:

```json
{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}
```

En las plantillas se usan así: `{{ order_id }}`, `{{ total }}`, `{{ discount_code }}`

### Datos de seguimiento (`metadata`)

El objeto `metadata` guarda información para analítica y seguimiento, y **no está disponible** en las plantillas:

```json
{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}
```

Usa metadata para el seguimiento interno, la analítica y los informes.

## Archivos adjuntos

Adjunta facturas, recibos, entradas u otros documentos a tus correos transaccionales. Los adjuntos se deduplican automáticamente en el almacenamiento.

### Límites de los adjuntos

- **Número máximo de archivos**: 20 adjuntos por correo
- **Tamaño de archivo**: 3 MB por archivo
- **Tamaño total**: 10 MB por correo
- **Formatos admitidos**: todos los tipos de archivo (PDF, PNG, JPEG, DOCX, etc.)

### Parámetros de los adjuntos

| Parámetro      | Tipo   | Obligatorio | Descripción                                                                                                                                                                                                  |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filename`     | string | Sí          | Nombre del archivo (255 caracteres como máximo)                                                                                                                                                              |
| `content`      | string | Sí          | Contenido del archivo codificado en Base64                                                                                                                                                                   |
| `content_type` | string | No          | Tipo MIME (por ejemplo, "application/pdf"); se detecta automáticamente si no se indica                                                                                                                       |
| `disposition`  | string | No          | "attachment" (por defecto) o "inline"                                                                                                                                                                        |
| `content_id`   | string | No          | Content-ID de los adjuntos en línea, al que se hace referencia desde el cuerpo HTML como `<img src="cid:...">`. Solo se permite cuando `disposition` es "inline". Si se omite, se usa el nombre del archivo. |

### Ejemplo con una factura en PDF

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}
```

### Ejemplo con varios adjuntos

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}
```

### Imágenes en línea (Content-ID)

Inserta imágenes propias de cada destinatario, como códigos QR o gráficos personalizados, en el cuerpo del correo en lugar de alojarlas en una URL. Pon `disposition` a `"inline"` y dale al adjunto un `content_id`, y luego haz referencia a él desde el HTML de tu plantilla como `<img src="cid:...">`:

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}
```

Y en la plantilla del correo:

```html
<img src="cid:checkInQr" alt="Your check-in QR code" />
```

Notas:

- `content_id` solo puede contener letras, cifras y los caracteres `.` `_` `-` `@` (255 caracteres como máximo), y solo se acepta cuando `disposition` es `"inline"`.
- Si se omite `content_id`, se usa el nombre del archivo como Content-ID, así que `<img src="cid:check-in-qr.png">` también funciona.
- Las imágenes en línea se entregan dentro de una parte MIME `multipart/related` junto al cuerpo HTML, así los clientes de correo las muestran en el cuerpo y no como adjuntos descargables.
- Como la imagen viaja dentro del cuerpo del mensaje, los proxies de enlaces y los servicios de caché de imágenes nunca la descargan ni la registran, lo que conviene para secretos propios de cada destinatario, como los códigos QR.
- En Mailgun, el `content_id` también pasa a ser el nombre de archivo de la parte entregada, así que conviene un `content_id` con extensión de archivo (por ejemplo, `checkInQr.png`) cuando envías a través de Mailgun.

### Casos de uso habituales

- **Confirmaciones de pedido**: adjunta facturas y recibos
- **Confirmaciones de reserva**: adjunta entradas e itinerarios
- **Documentos legales**: adjunta contratos y acuerdos
- **Informes**: adjunta informes de analítica y resúmenes
- **Certificados**: adjunta certificados de finalización e insignias
- **Entradas para eventos**: inserta códigos QR propios de cada destinatario como imágenes en línea

## Puente SMTP

Notifuse incluye un servidor puente SMTP, así puedes enviar correos transaccionales desde clientes SMTP estándar en lugar de llamar a la API HTTP. Es útil para:

- **Sistemas heredados**: integrar aplicaciones existentes que solo admiten SMTP
- **Bibliotecas de correo**: usar las bibliotecas de correo estándar de cualquier lenguaje de programación
- **Integración con frameworks**: trabajar con frameworks que ya traen soporte SMTP
- **Migración gradual**: dejar un proveedor de correo existente sin cambiar el código de la aplicación

### Cómo funciona

El servidor puente SMTP acepta correos en el puerto 587 (STARTTLS) o 465 (TLS implícito). El cuerpo del correo debe contener un payload JSON con el formato de la API transaccional, y te autenticas con las credenciales de API de tu espacio de trabajo.

### Enviar correos por SMTP

#### Autenticación

- **Nombre de usuario**: el email de API de tu espacio de trabajo (el email asociado a tu clave API)
- **Contraseña**: la clave API de tu espacio de trabajo
- **Seguridad**: STARTTLS (puerto 587) o TLS implícito / SMTPS (puerto 465), según tu ajuste `SMTP_BRIDGE_TLS`
- **Servidor**: el host del puente SMTP que hayas configurado (por ejemplo, `smtp.yourdomain.com`)

#### Formato del correo

El cuerpo del correo debe ser un payload JSON con el formato de la API transaccional:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}
```

## Permisos

El permiso de escritura de **Transaccional** basta por sí solo para enviar, tanto por la API como por el puente SMTP. Por eso resulta práctica una clave API que solo envía: dale a una clave la escritura de Transaccional y nada más, y podrá enviar correos sin leer ni editar un solo contacto. Consulta [Administradores y claves API](https://www.notifuse.com/es/docs/features/admins-api-keys.md).

Una clave con un alcance tan limitado tiene dos restricciones, en el puente SMTP igual que en la API:

- **Sin escritura en Contactos**, un envío sigue creando el contacto del destinatario cuando todavía no existe, pero solo guarda su dirección de correo. Los demás campos del objeto `contact` se descartan, y un contacto existente nunca se modifica.
- **Sin lectura en Contactos**, se rechaza un envío que define `cc` o `bcc`. En el puente SMTP, `cc` y `bcc` salen de las cabeceras `Cc:` y `Bcc:` del mensaje, así que una credencial que solo envía y que las define se rechaza al entregar el mensaje.

Añade a la clave la lectura y la escritura de Contactos si debe enriquecer los perfiles de los contactos al enviar o copiar a otros destinatarios. Con las dos, la clave se comporta como antes.

La escritura de Transaccional cubre todas las vías que envían correo real con las credenciales de tu proveedor: `/api/transactional.send`, `/api/transactional.testTemplate` y el puente SMTP. Probar un proveedor de correo (`/api/email.testProvider`) está reservado al propietario del espacio de trabajo, así que una clave API no puede llamarlo. Un correo de prueba también necesita la lectura de Plantillas, y la lectura de Listas cuando se envía para una lista de correo (`list_id`).

El permiso **Leído** de Transaccional solo cubre las definiciones de las notificaciones (listarlas y abrir una). No permite enviar a una clave.

## Integración con las plantillas

### Estructura de datos en las plantillas

Tus plantillas pueden usar tanto los datos de la API como el perfil del contacto:

```liquid
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.
```

### Bloques condicionales

Los bloques de una plantilla visual pueden enviarse solo cuando se cumple una condición sobre estos datos, por ejemplo una sección que solo se muestra cuando `order.total` es mayor que 100. Consulta [Bloques condicionales](https://www.notifuse.com/es/docs/features/templates.md#conditional-blocks).

### Ejemplo completo

**Solicitud a la API**:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}
```

**Perfil de contacto existente**:

```json
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
```

**Disponible en la plantilla**:

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

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.
```

## Referencia de la API

## Ejemplos de deduplicación

### Confirmaciones de pedido

```json
{
  "external_id": "order-12345-confirmation"
}
```

### Restablecimiento de contraseña

```json
{
  "external_id": "pwd-reset-user123-20240101"
}
```

### Correos de bienvenida

```json
{
  "external_id": "welcome-user123"
}
```

Unos patrones de `external_id` coherentes evitan las notificaciones duplicadas, aunque tu aplicación envíe varias solicitudes.

Para la documentación completa de la API y los demás parámetros, consulta la [referencia de la API](https://www.notifuse.com/docs/api-reference/send-a-transactional-notification.md).
