Dispará automatizaciones desde tu sistema: alta por API y evento personalizado

Cuando el alta de contactos la hace tu propio sistema —tu web, tu backoffice, tu tienda— el disparador «Suscripción» puede no verla nunca, porque espera un opt-in que tu backend no produce. La solución determinística es el evento personalizado: tu sistema le avisa a arrobaMail "esto pasó" con una llamada HTTP, y el flujo arranca. En la práctica es un disparador tipo webhook: cualquier sistema, con una sola invocación, puede iniciar una automatización.

Un ejemplo para ubicarnos. En tu e-commerce se concreta una compra. Tomás esa operación y, por la API, das de alta al cliente en una lista con su nombre, su email y el rubro del producto. Enseguida registrás un evento que dispara la automatización: sale un primer correo de agradecimiento con productos relacionados y, una semana después, un segundo correo con novedades del mismo rubro. Eso es lo que vas a montar acá.

1. Por qué un evento personalizado y no «Suscripción»

El disparador «Suscripción» se activa con el opt-in de un formulario: la persona se suscribe, confirma, y recién ahí arranca el flujo. Es el camino correcto cuando el alta entra por un formulario público, y lo explicamos paso a paso en automatizá tu bienvenida desde un formulario.

Pero si tu alta saltea ese paso —porque la hacés por API, desde un backoffice, o con un formulario propio que confirma en silencio— el evento de suscripción "visible" nunca ocurre, y el flujo se queda esperando algo que no va a pasar. Lo peor es que no hay error en ningún lado: el contacto queda perfecto en la lista, la automatización figura activa, y simplemente no entra nadie.

El evento personalizado no depende de nada de eso. Es una señal explícita que vos disparás cuando querés, con el nombre que vos elegís. Determinístico y bajo tu control.

2. Creá la automatización con el disparador «Evento personalizado»

En el editor de automatización, abrí la categoría Disparadores de la paleta. Ahí está, al final de la lista, Evento personalizado.

Arrastralo al lienzo y abrí su configuración. Tiene dos campos:

• Nombre del evento. Definí uno fijo, sin espacios y en minúsculas, del estilo compra_confirmada, alta_backoffice o trial_vencido. Este nombre es el contrato con tu sistema: tiene que coincidir exactamente con el que dispares, mayúsculas incluidas. El panel te sugiere ejemplos (purchase, signup, lead, view_product, cart_abandoned, trial_started, trial_expired, plan_changed) que sirven muy bien de convención.
• Valor (opcional). Un filtro fino: si lo completás, el flujo solo arranca cuando el evento llega con ese valor. Sirve para tener un mismo evento plan_changed disparando flujos distintos según el plan.

Ese detalle ahorra tiempo y errores: no tenés que construir la URL a mano. La copiás del panel y solo reemplazás los dos marcadores que vienen entre corchetes.

3. El requisito clave: el contacto ya tiene que estar en la lista

Acá está el punto que hace tropezar a todo el mundo la primera vez: el evento dispara, no crea. La automatización necesita que el suscriptor ya exista en la lista para poder enrolarlo.

No es una contradicción ni una limitación rara: es la separación de responsabilidades. Tu sistema es el dueño del dato del contacto (lo da de alta con sus campos), y arrobaMail es el dueño de la conversación (decide qué mensaje sale y cuándo). El evento es apenas el timbre que conecta a los dos.

En el flujo real esto se resuelve solo, porque el alta ocurre naturalmente antes: primero registrás al cliente, después avisás que compró.

4. Registrá el evento desde tu sistema

Cuando ocurre el hecho que te interesa, tu backend llama al endpoint de eventos. Esta es la forma que te entrega el panel:

GET /v3/api/events/record?eventName=compra_confirmada&email=[SUBSCRIBER_EMAIL]&listid=[LIST_ID]

Los parámetros:

• eventName — el nombre exacto que configuraste en el paso 2. Si no coincide carácter por carácter, no dispara.
• email — la dirección del contacto que ya está en la lista. Reemplazá el marcador [SUBSCRIBER_EMAIL].
• listid — el identificador de la lista. Lo tenés en el panel; reemplazá [LIST_ID].
• eventValue (opcional) — solo si configuraste el filtro por valor.
• pf_* (opcionales) — campos temporales que viajan con el evento y podés usar dentro del email sin guardarlos en el contacto: pf_order_id, pf_total, pf_rubro. En la plantilla se escriben como {{{$pf_order_id}}}, con el $ adelante, igual que las variables del suscriptor.

Un ejemplo completo con curl, contra la cuenta de prueba gratuita:

curl -G "https://demo.arrobamail.com/v3/api/events/record" \
  --data-urlencode "eventName=compra_confirmada" \
  --data-urlencode "[email protected]" \
  --data-urlencode "listid=TU_LIST_ID" \
  --data-urlencode "pf_order_id=ORD-123" \
  --data-urlencode "pf_total=99.90"

El dominio es el de tu cuenta. En el ejemplo usamos demo.arrobamail.com, que es donde cualquiera puede probar arrobaMail gratis. Si tu cuenta vive en otro servidor, la URL que copiás del panel ya viene con el tuyo. La base general de la API está documentada en el quickstart de la API v3.

Alternativa para probar rápido. Existe además una vía legacy, POST /eventRecord.php, que sigue vigente y acepta los mismos parámetros en el cuerpo del request. Tiene una ventaja concreta para pruebas y para producción: al ir por POST, el email no viaja en la URL. El endpoint documentado y el que arma el panel es el GET /v3/api/events/record; si te importa mantener las direcciones fuera de los logs, el POST legacy es una opción válida.

5. Respetá el orden: primero el alta, después el evento

Del punto 3 se desprende la regla operativa más importante de este tutorial. La secuencia completa, desde tu backend, es esta:

Si el evento llegara antes que el alta, no encuentra al contacto y no dispara — y otra vez, sin error visible. Como el alta ocurre primero por naturaleza, el orden natural ya es el correcto: asegurate solo de que tu código no las lance en paralelo, porque ahí sí se pueden cruzar.

Con el disparador ya conectado, el flujo del lado de arrobaMail queda así:

Fijate en lo que gana tu equipo: el contenido y los tiempos viven en arrobaMail. Si mañana querés sumar un tercer email, correr la espera de 7 a 10 días o cambiar el texto, lo hacés desde el editor visual, sin tocar una línea de tu sistema ni volver a desplegar nada.

6. Activá y verificá el enrolamiento

Guardá y activá la automatización — igual que en cualquier flujo, en borrador no procesa a nadie.

Para el test, hacelo en tres tiempos y sin adivinar:

1. Confirmá que tu contacto de prueba quedó en la lista (miralo en el panel, no lo asumas).
2. Anotá el conteo de inscriptos actual de la automatización.
3. Registrá el evento para ese email y volvé a mirar el conteo.

Si el número subió, la señal llegó y enganchó. Si no subió, el problema está en uno de tres lugares, siempre en este orden de probabilidad: el nombre del evento no coincide exactamente, el contacto no estaba en la lista, o el listid es de otra lista.

7. Seguridad: llamá desde el backend

Dos recomendaciones para producción, en orden de importancia.

Hacé la llamada desde tu servidor, nunca desde el navegador del visitante. Es lo que más importa. Si el disparo sale del front, cualquiera puede abrir las herramientas de desarrollo, ver la URL completa —con tu listid incluido— y empezar a iniciar flujos para direcciones arbitrarias. No expongas el listid en páginas públicas.

Tené presente que un GET deja rastro. Con GET, el email viaja en la URL y termina en los logs del servidor, en el historial y en las cabeceras Referer. Desde el backend eso es mucho menos grave —no hay navegador ni referer de por medio—, pero si manejás datos sensibles o tenés una política estricta de retención de logs, la vía POST /eventRecord.php del paso 4 mantiene el email fuera de la URL.

En resumen: llamada del lado del servidor y, si tu contexto lo pide, POST. Con eso el disparo queda seguro, privado y bajo tu control.

Los tres disparadores que inician una conversación

Este tutorial cubre el más flexible de los tres, pero conviene tenerlos juntos en la cabeza: elegir bien el disparador es el 80% del trabajo de una automatización.

Disparador	Se activa cuando…	Ideal para	Guía
Suscripción	alguien confirma su alta en una lista	bienvenida desde un formulario de tu web	bienvenida desde formulario
Evento personalizado	tu sistema registra un evento por la API	compras, altas desde tu backend, cualquier acción de tu plataforma	esta guía
Apertura / Click en email	un contacto abre o clickea una campaña	seguimiento por interés, reenvíos, reactivación	automatizar por comportamiento

La referencia completa está en disparadores de automatización.

Errores frecuentes a evitar

• Un nombre de evento que "casi" coincide. Compra_Confirmada no es compra_confirmada. Definí el nombre una vez, en minúsculas, y copialo de un lado al otro.
• Lanzar el alta y el evento en paralelo. Parecen dos llamadas independientes, pero la segunda depende de la primera. Encadenalas.
• Disparar desde el navegador. Cómodo para probar, indefendible en producción.
• Un evento genérico para todo. Si signup dispara cinco flujos distintos, en tres meses nadie sabe cuál hace qué. Un evento por intención, y el campo valor para las variantes.
• Olvidarse de activar el flujo. Vale para todas las automatizaciones y sigue siendo la causa número uno de "no anda".

Próximos pasos

1. Repasá el detalle de cada disparador en disparadores de automatización.
2. Si además querés que arrobaMail le avise a tu sistema cuando pasa algo, el camino inverso son los webhooks de eventos en vivo.
3. Para confirmaciones, códigos y facturas que arma tu backend, mirá las tres formas de enviar emails transaccionales.
4. Y para que el flujo además reaccione a lo que hace cada contacto, seguí con aperturas y clics.