Saltar al contenido

Funciones

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

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

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

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ámetroTipoObligatorioDescripción
workspace_idstringSíIdentificador de tu espacio de trabajo
notification.idstringSíIdentificador de la plantilla del correo
notification.external_idstringNoIdentificador único para la deduplicación
notification.channelsarraySíDebe incluir “email”
notification.contactobjectSíObjeto de contacto con al menos un campo email
notification.dataobjectNoVariables de la plantilla para el contenido del correo
notification.metadataobjectNoDatos de seguimiento (no disponibles en las plantillas)
notification.email_optionsobjectNoConfiguración del envío del correo

Opciones del correo

ParámetroTipoDescripción
sender_idstringEnví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_namestringSustituye el nombre visible del remitente predeterminado
subjectstringSustituye el asunto de la plantilla (admite Liquid, 255 como máximo)
reply_tostringDefine una dirección de respuesta personalizada, en lugar de la de la plantilla
ccarrayLista de destinatarios en copia
bccarrayLista de destinatarios en copia oculta
attachmentsarrayArchivos 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:

{
  "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:

{
  "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ámetroTipoObligatorioDescripción
filenamestringSíNombre del archivo (255 caracteres como máximo)
contentstringSíContenido del archivo codificado en Base64
content_typestringNoTipo MIME (por ejemplo, “application/pdf”); se detecta automáticamente si no se indica
dispositionstringNo“attachment” (por defecto) o “inline”
content_idstringNoContent-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

{
  "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

{
  "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:...">:

{
  "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:

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

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

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:

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

Ejemplo completo

Solicitud a la API:

{
  "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:

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

Disponible en la plantilla:

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

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

Restablecimiento de contraseña

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

Correos de bienvenida

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