Pensalo así: una campaña de email marketing es como un volante que imprimís y repartís a toda una lista. Un envío transaccional es como una carta personal que se escribe y se envía en el momento exacto en que pasa algo —alguien compró, se registró o pidió recuperar su contraseña—.
En esta guía conectamos tu sistema con arrobaMail para enviar esos correos automáticos. Es un tutorial técnico (vas a ver código), pero está explicado para que cualquiera entienda qué hace cada paso. Si manejás un poco de HTTP, en una tarde lo tenés andando.
Antes de empezar
- Una cuenta de arrobaMail con un remitente verificado (SPF/DKIM) y una lista.
- Acceso al backend de tu sistema (o tu desarrollador), para hacer llamadas HTTP.
- Tu usuario y contraseña de arrobaMail para obtener el token de la API.
Los 7 pasos
- 1
Qué es un envío transaccional
Un email individual y automático que responde a un evento puntual, no a una lista.
- 2
Las tres formas de enviarlos
API directa, automatización con evento o webhooks: cambia quién arma el email y quién lo dispara.
- 3
Forma 1 — API directa
Tu sistema arma el HTML y se lo manda a arrobaMail para entregar.
- 4
Forma 2 — Automatización con evento
El email vive en arrobaMail; tu sistema solo registra el evento que lo dispara.
- 5
Forma 3 — Webhooks
Al revés: arrobaMail le avisa a tu sistema cuando un flujo llega a un nodo Webhook.
- 6
Errores frecuentes y cómo resolverlos
Los tropiezos típicos: el evento que no se guardó, el 404, el token vencido.
- 7
Referencia y a dónde seguir
El resumen de endpoints y los lugares para profundizar.
1. Qué es un envío transaccional
Un transaccional es un email individual y automático que responde a un evento puntual. No se manda a una lista: tiene un destinatario específico y un momento exacto. Los del día a día:
- Confirmación de compra — "Tu orden #12345 fue confirmada. Llega el martes."
- Código de verificación (OTP) — "Tu código es 482931. Expira en 5 minutos."
- Factura electrónica — "Adjuntamos tu factura por $15.200."
- Recordatorio — "Tu turno es mañana a las 10:00."
Una aclaración clave: arrobaMail no reemplaza tu sistema. Tu sistema sigue siendo el que detecta el evento. arrobaMail es el servicio especializado de entrega: recibe la instrucción y manda el correo con autenticación SPF/DKIM, control de rebotes y optimización por proveedor (Gmail, Outlook, Yahoo). Vos te ocupás del "cuándo"; arrobaMail, del "que llegue".
2. Las tres formas de enviarlos
arrobaMail ofrece tres mecanismos. Lo que cambia entre ellos es quién arma el email y en qué dirección va la conversación:
API directa
arma y manda el email
Tu sistema arma el HTML del email y se lo manda a arrobaMail para que lo entregue.
- Arma el email:
- Tu sistema
- Cuándo conviene:
- El contenido se genera en tu backend: facturas, reportes con datos variables.
Automatización con evento
registra un evento
El email ya está armado en arrobaMail; tu sistema solo dispara el evento y arrobaMail lo envía.
- Arma el email:
- arrobaMail
- Cuándo conviene:
- El email ya está diseñado (con el editor o con IA). Tu sistema solo dice «mandalo».
Webhooks
POST a tu servidor
Al revés: arrobaMail le avisa a tu sistema con un POST cuando el flujo pasa por el nodo Webhook.
- Arma el email:
- —
- Cuándo conviene:
- Necesitás que arrobaMail notifique a tu backend cuando se ejecuta un flujo.
En resumen: si el contenido se genera en tu backend (una factura con datos variables), API directa. Si el email ya está diseñado dentro de arrobaMail y tu sistema solo dispara, automatización con evento. Y si necesitás que arrobaMail le avise a tu sistema cuando pasa algo, webhooks. Veamos las tres.
3. Forma 1 — API directa
Tu código arma el email completo (HTML, asunto, remitente) y se lo manda a arrobaMail. No hay automatización: tu sistema decide todo.
Paso 1 — Obtené el token JWT. Es un pase temporal que autoriza tus llamadas.
POST https://envios.arrobamail.com/v3/api/auth/getToken
Content-Type: application/json
{ "username": "tu_usuario", "pass": "tu_contraseña", "rememberMe": false, "locale": "es" }
Recibís { "token": "eyJhbGci...", "expires": ... }. Guardalo: va en el header Authorization: Bearer {token} de todas las llamadas siguientes.
Paso 2 — Probá con un envío de prueba (no consume cuota): mandá una copia a tu casilla para ver que se ve bien.
POST /campaigns/test
Authorization: Bearer {token}
{ "email": "vos@mail.com", "subject": "Confirmación #12345",
"html": "<html>...</html>", "fromname": "Tu Empresa", "frommail": "info@tudominio.com" }
Paso 3 — Enviá el email real. Encola la entrega inmediata.
POST /campaigns
Authorization: Bearer {token}
{ "campname": "Confirmacion_12345", "asunto": "Tu orden fue confirmada",
"html": "<html>...</html>", "fromname": "Tu Empresa", "frommail": "info@tudominio.com",
"listid": ["TU_LIST_ID"], "preheader": "Gracias por tu compra.",
"tracklinks": 1, "trackreads": 1 }
Recibís un encid (el identificador de la campaña). Guardalo.
Paso 4 — Consultá el resultado con ese encid:
GET /campaigns/{encid}/stats/subscriber-actions
Te dice si el email fue entregado, abierto, si hubo clics y si rebotó.
Cuándo usarla: el contenido se genera en tu backend con datos variables —facturas, reportes, comprobantes—. Tu código tiene el control total del HTML.
4. Forma 2 — Automatización con evento
Acá el email ya vive armado dentro de arrobaMail. Tu sistema solo dice "mandáselo a esta persona ahora". arrobaMail busca la automatización, reemplaza las variables y envía. Tiene dos partes.
Parte A — Configurar en la plataforma (una sola vez)
- Creá la automatización: Automatización › Nueva Automatización.
- Elegí el trigger «Evento personalizado» (es el que responde a llamadas externas).
- Escribí el nombre exacto del evento —por ejemplo,
confirmacion_curso—. Es sensible a mayúsculas:Confirmacion_Cursono es lo mismo. Verificá que el nombre aparezca impreso dentro del nodo azul. - GUARDÁ. (Sí, en mayúsculas: es el paso que más se olvida y el que causa la mayoría de los problemas.)
- Agregá la acción «Enviar email» debajo del trigger y elegí el contenido (editor, IA o plantilla).
- Definí la política de reingreso (qué pasa si el mismo contacto dispara el evento varias veces): Nunca (bienvenida), Siempre (facturas, recordatorios), Después de completar o Con período de espera.
- Activá el flujo.
Parte B — Llamar desde tu sistema (en cada evento)
Obtené el token (igual que en la Forma 1) y después registrá el evento. Es un GET con los datos en la URL:
GET /events/record?eventName=confirmacion_curso&email=alumno@dominio.com&listid=TU_LIST_ID&pf_curso=Marketing&pf_fecha=20/06/2026
Authorization: Bearer {token}
Qué es cada cosa:
- eventName — el nombre exacto del trigger del paso 3 (idéntico, mayúsculas incluidas).
- email — el destinatario; debe existir como suscriptor Activo en la lista (si está Pendiente por double opt-in, no dispara).
- listid — el ID de la lista (un string cifrado, no un número).
- pf_* — variables dinámicas para el email sin guardarlas en el contacto. En la plantilla se usan como
{{{pf_curso}}}.
Si responde { "status": "success", ... }, el motor ya está procesando el evento.
Cuándo usarla: el email ya está diseñado en arrobaMail (con el editor o con IA) y tu sistema solo necesita dispararlo. Menos código de tu lado.
5. Forma 3 — Webhooks
Las dos formas anteriores: tu sistema le habla a arrobaMail. Esta es al revés: cuando un suscriptor pasa por un nodo Webhook dentro de una automatización, arrobaMail hace un POST a una URL tuya con los datos del contacto. Sirve para que arrobaMail dispare lógica en tu backend (habilitar un acceso, emitir una factura).
- Creá la automatización con trigger «Evento personalizado» (igual que la Forma 2), pero en vez de «Enviar email», agregá un nodo de acción Webhook.
- Configurá la URL de tu servidor (debe ser HTTPS).
- Programá el receptor: tu servidor escucha el
POST, lee el JSON y respondeHTTP 200.
<?php // webhook-handler.php
$payload = json_decode(file_get_contents("php://input"), true);
if (isset($payload["email"])) {
$email = $payload["email"];
// Tu lógica acá: habilitar acceso, emitir factura, etc.
}
http_response_code(200);
echo json_encode(["status" => "ok"]);
Tip: la estructura del payload puede variar. En las primeras pruebas, logueá el body completo para ver exactamente qué campos llegan antes de programar tu lógica.
6. Errores frecuentes y cómo resolverlos
- El evento se registra pero el email no llega. Casi siempre: el nombre del evento no se guardó en el nodo. El flujo figura "Activo" pero el trigger está vacío. → Editá el flujo, reescribí el nombre, verificá que aparezca dentro del nodo azul y GUARDÁ.
- HTTP 404 — subscriber_not_found. El
emailno existe como suscriptor activo en esalistid. → Dalo de alta antes de llamar al evento (y que no esté Pendiente). - HTTP 401 — token inválido o expirado. → Volvé a pedir el token y revisá que el header diga exactamente
Authorization: Bearer {token}(con el espacio después de Bearer). - El email llega varias veces. → Hay flujos duplicados con el mismo evento, o la política de reingreso está en "Siempre" y tu código llama de más. Pausá los duplicados y revisá tu código.
7. Referencia y a dónde seguir
Los endpoints que usaste, de un vistazo:
| Endpoint | Para qué |
|---|---|
POST /auth/getToken |
Obtener el token de autenticación. |
POST /campaigns/test |
Enviar un email de prueba (API directa). |
POST /campaigns |
Enviar el email real (API directa). |
GET /events/record |
Registrar un evento y disparar la automatización. |
GET /campaigns/:encid/stats/subscriber-actions |
Ver si un email fue entregado o abierto. |
Para el detalle completo de cada endpoint —parámetros, respuestas y ejemplos en curl, Node, PHP y Python— está la referencia de la API. Para el panorama de todas las formas de integrar (incluida la IA por MCP), conectar arrobaMail con tus sistemas y la página de API.
Próximos pasos
- Mirá el panorama de integración completo en conectar arrobaMail con tus sistemas.
- Profundizá cada endpoint en la referencia de la API.
- Si querés operar tu cuenta con un asistente de IA, mirá MCP.