Cómo funcionan las automatizaciones

Una definition tiene un trigger, el paso entry y una lista de steps. Cada paso tiene una key única en la automatización: una letra minúscula seguida de 2 a 23 letras minúsculas o dígitos. Un paso nombra al que le sigue en next, y un branch nombra dos, yes y no. null termina ese camino. Los pasos forman un árbol, así que a ningún paso se llega desde dos sitios y nada vuelve atrás. Una automatización admite hasta 50 pasos, con bifurcaciones de 5 niveles como máximo.

• —audience_joined: se añade un contacto a audienceId. Los contactos añadidos por una importación se quedan fuera salvo que includeImported sea true.
• —form_submitted: una persona se suscribe con el formulario formId. Con doble opt-in, entra cuando confirma.
• —event: tu código envía un evento llamado eventName. Hasta 5 filters sobre sus propiedades limitan quién entra.
• —date: llega un día para cada miembro de audienceId. field es birthday o joined, el aniversario del día en que se unió a esa audiencia. offsetDays lo desplaza hasta un año: negativo para días antes, positivo para días después.
• —manual: nadie entra por sí solo. Añades personas desde la app o con el endpoint de inscripción.

Un valor de props o de update_field viene de uno de tres sitios: { "source": "static", "value": "…" }, { "source": "contact", "field": "firstName" } para email, name, firstName, lastName o attributes.<key>, y { "source": "event", "path": "orderId" } para una propiedad del evento que inició el recorrido.

Guardar cambia la definition del borrador. Nada se ejecuta hasta que POST /automations/{id}/publish congela el borrador como una versión numerada, que published muestra a partir de entonces. Quienes ya están dentro terminan con la versión con la que entraron, y quienes entran después reciben la nueva. hasUnpublishedChanges indica que el borrador ha seguido cambiando.

• —draft: nunca publicada. No entra nadie.
• —live: publicada y en marcha.
• —paused: no entra nadie y todos los que están dentro se quedan donde están. pausedReason dice por qué: manual, o un problema que encontró el motor, como sender_refused o template_unavailable.
• —archived: retirada para siempre. Todos los que están dentro salen, y el historial se conserva.

settings van aparte y se aplican en cuanto se guardan: la timezone, un sendWindow fuera del cual los correos esperan, reentryDays antes de que la misma persona pueda volver a entrar (null significa una sola vez), exitOnLeave para sacar a quienes dejan la audiencia del desencadenante, y listAudienceId, la audiencia en la que se registra una baja.

problems lista lo que falla en el borrador, cada cosa con un code, el path del campo, el stepKey y si es blocking. Un borrador con un problema que bloquea no se puede publicar.

Cada persona que entra recibe una inscripción. Es active mientras avanza por los pasos, completed cuando llega al final de un camino y exited cuando sale antes, con un exitReason: exit_step, unsubscribed, suppressed, left_audience, removed, archived o failed.

• —Los pasos se ejecutan unos 15 segundos después de que les toque. Una persona nunca recibe dos correos de una misma automatización en la misma pasada.
• —Los correos de una automatización son correo de marketing, así que todos llevan un enlace de baja. Quien se da de baja sale de las automatizaciones que escriben a esa lista, y aquel cuya dirección rebotó o se quejó sale en su siguiente paso.
• —Un correo cuya dirección no puede recibir correo se omite, y la persona sigue al siguiente paso.
• —Cuando un envío se rechaza para todos, como con un remitente que perdió su dominio o una plantilla que dejó de estar publicada, la automatización se pausa y pausedReason dice por qué.

POST /events registra que un contacto hizo algo: order.placed, trial.started, plan.upgraded. Un evento inicia cada automatización activa cuyo desencadenante lo nombra, hace avanzar a quien lo esté esperando y responde a la pregunta event de una bifurcación. Los eventos se conservan 90 días.

• —Leer requiere automations:read y cambiar requiere automations:write. Publicar, reanudar y enviar una prueba también requieren emails:send, porque hacen que la automatización envíe correo.
• —Enviar un evento requiere contacts:write, y leer los eventos de un contacto requiere contacts:read.
• —Una clave de API y el propietario ven todas las automatizaciones del espacio de trabajo. Una app que conectó un miembro ve las que creó ese miembro.
• —Eliminar una automatización pide a una app OAuth un código de verificación. Una clave de API nunca lo necesita.
• —Un plan permite 1 automatización activa en Free, 10 en Starter, 50 en Business y cualquier número en Enterprise. Un espacio de trabajo admite 100 automatizaciones por defecto.

Los webhooks automation.entered, automation.exited y automation.paused avisan a tus sistemas de quién entró, quién salió y cuándo se detuvo una automatización. Archivar una automatización termina a todos los que están en ella sin un evento automation.exited por cada persona.

Todo lo de aquí está también en el SDK como openemail.automations y openemail.events, y en la CLI como openemail automations y openemail events. El servidor MCP tiene herramientas de automatizaciones, así que un agente puede crear una, publicarla y ver quién está dentro.