Secuencias

Una secuencia es un recorrido automatizado. Un contacto entra por un disparador y luego recorre un grafo de pasos a su propio ritmo; el grafo está versionado, así que un recorrido ya en marcha nunca cambia.
POSTCreate a sequence/api/v1/sequencesGETList sequences/api/v1/sequencesGETGet a sequence/api/v1/sequences/{sequenceId}PATCHRename, activate or pause/api/v1/sequences/{sequenceId}DELETEDelete a sequence/api/v1/sequences/{sequenceId}GETWho is walking it/api/v1/sequences/{sequenceId}/enrollmentsGETList versions/api/v1/sequences/{sequenceId}/versionsPOSTOpen a draft version/api/v1/sequences/{sequenceId}/versionsPATCHChange a draft's trigger/api/v1/sequences/{sequenceId}/versions/{versionId}POSTPublish a version/api/v1/sequences/{sequenceId}/versions/{versionId}/publishPOSTRoll back to a version/api/v1/sequences/{sequenceId}/versions/{versionId}/rollbackDELETEDiscard a draft/api/v1/sequences/{sequenceId}/versions/{versionId}POSTAdd a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodesGETList steps/api/v1/sequences/{sequenceId}/versions/{versionId}/nodesPATCHEdit a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}DELETERemove a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}POSTMove a step/api/v1/sequences/{sequenceId}/versions/{versionId}/nodes/{nodeId}/moveGETList wires/api/v1/sequences/{sequenceId}/versions/{versionId}/edgesPOSTWire two steps/api/v1/sequences/{sequenceId}/versions/{versionId}/edgesDELETEUnwire two steps/api/v1/sequences/{sequenceId}/versions/{versionId}/edges/{edgeId}

Los cuatro objetos que manipulas

ObjetoQué es
SecuenciaLa identidad del recorrido: un nombre, un estado (active / paused) y un puntero a la versión que se está ejecutando
VersiónUna instantánea del recorrido, con su disparador. Un draft es editable; una published ya nunca cambia
NodoUn paso de una versión: send_email, wait, add_tag, remove_tag, end_sequence, webhook
ConexiónUn enlace de un nodo al siguiente. Añadir un nodo lo conecta por ti; las conexiones existen para que puedas reconectar
Dos consecuencias atraviesan todo lo que sigue:
  • Nunca editas un recorrido en ejecución. Editar significa abrir una versión en borrador, cambiarla y publicarla. Los contactos que ya recorren la versión antigua terminan en la versión antigua.
  • El disparador vive en la versión, no en la secuencia. Lo defines al crear la secuencia (esa llamada crea la versión 1 con él) y lo cambias como cambias todo lo demás: en un borrador, con PATCH sobre la versión, y luego publicas.

Dónde encaja una serie

Una serie (una secuencia guiada por un calendario en lugar de por un disparador, consulta las tres formas de un envío) no es un objeto aparte aquí. No hay recurso /series: una serie es una secuencia cuya versión lleva triggerType: "fixed_date", y ese campo es lo que te permite reconocerla al leer. Lo que la API puede y no puede hacer con ella:
Serie
Crear unaNo. triggerType: "fixed_date" al crear, o en el disparador de un borrador, se rechaza con 400
Leer unaSí: secuencias, versiones, nodos y conexiones se leen con normalidad
Renombrar, activar, pausar, eliminarSí, como cualquier otra secuencia
Leer quién la recorreNo hay nada que leer: una serie no inscribe a nadie, así que su lista de inscripciones está vacía por diseño
Las series de fecha fija se configuran en la app, donde se eligen la fecha de inicio y la hora de envío de cada paso. Los correos que envía una serie son campañas: cada paso de envío crea una, llamada <series name> · step N, en el momento en que el paso sale. Se leen a través de la API de campañas como cualquier otra campaña, con un límite que conviene conocer: una campaña no lleva en su payload de API la serie de la que procede. Hoy, lo que las une es el nombre.
No hay ningún endpoint para inscribir un contacto directamente. Los contactos entran en una secuencia por su disparador, y solo por él: al entrar en una lista (list_joined) o al recibir una etiqueta (tag_added). Usa la API de audiencia para añadir un contacto a la lista, o para etiquetarlo, y la inscripción llega sola.

Códigos de estado que importan aquí

Todo lo que dice la referencia de la API se aplica. Tres casos aparecen mucho más a menudo aquí:
EstadoCuándo
201Se creó una secuencia, una versión, un nodo o una conexión
400El recorrido rechaza lo que pediste: un grafo no válido al publicar, una escritura en una versión publicada, un límite del plan
404Id desconocido, un id que pertenece a otra organización, o un id que pertenece a otra versión
Lo último merece leerse dos veces: un versionId que no es una versión del sequenceId de la URL responde 404, y lo mismo un nodeId que no está en esa versión. Los ids solo se leen dentro de la ruta que lleva a ellos.

Qué significa una publicación rechazada

Cada defecto responde 400, se nombra a sí mismo y nombra los nodos implicados, todos a la vez, para que corrijas en una sola pasada en lugar de volver a publicar para descubrir el siguiente.
DefectoQué significaCómo corregirlo
vacíaLa versión no tiene ningún nodoAñade al menos un nodo
sin entradaTodos los nodos tienen algo que apunta a ellos: no hay forma de entrarElimina la conexión que cierra el bucle arriba
varias entradasDos nodos no tienen nada que apunte a ellosConecta uno detrás del otro; un recorrido tiene una sola puerta
cicloLas conexiones vuelven sobre sí mismas: un contacto daría vueltas para siempreElimina la conexión que va hacia atrás
huérfanoUn nodo es inalcanzable desde la entradaConéctalo, o elimínalo
rama colganteUna rama no lleva a ninguna parteConecta su final, o quita la rama
rama ambiguaUn nodo tiene dos conexiones de salida sin forma de elegirConserva una sola conexión
conexión fuera del grafoUna conexión apunta a un nodo de otra versiónElimina esa conexión y reconecta dentro de esta versión
envío vacíoUn nodo send_email no tiene asunto o no tiene contenidoHaz PATCH del nodo con un asunto y HTML
acción incompletaUn nodo add_tag / remove_tag no tiene etiquetaHaz PATCH del nodo con un tagId
fin con sucesorUn nodo end_sequence tiene un nodo detrásElimina lo que sigue: nada se ejecuta después del fin
webhook no válidoUn nodo webhook no tiene URL, o tiene una que la política rechazaHaz PATCH del nodo con una URL pública https://
Una versión que no es un borrador también responde 400: una versión publicada es una instantánea, y volver a publicarla en el sitio reescribiría lo que están recorriendo los contactos. Usa la reversión en su lugar.

Conexiones

Añadir un nodo lo conecta por ti. Estos endpoints existen para las formas que no se consiguen añadiendo al final, y para deshacer una.

Escribir en una versión publicada

Todas las escrituras anteriores (añadir, editar, eliminar o mover un nodo, conectar, desconectar, cambiar el disparador) responden 400 si la versión no es un draft. No es un problema de permisos, y reintentar no ayudará: las versiones publicadas son instantáneas que los contactos están ejecutando. La salida es siempre la misma, en tres llamadas: abre un borrador, edítalo, publícalo.

Una secuencia de bienvenida, de principio a fin

1

Crea la secuencia sobre su disparador

bash
SEQUENCE_ID=$(curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name":"Onboarding","triggerType":"list_joined","triggerTargetId":"'$LIST_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences" | jq -r '.data.id')
Está paused, y la versión 1 ya existe como borrador.
2

Encuentra el borrador que vas a editar

bash
VERSION_ID=$(curl -s -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions" \
  | jq -r '.data[] | select(.status=="draft") | .id')
3

Añade los pasos, en orden

bash
curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"type":"send_email","templateId":"'$TEMPLATE_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes"

curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"type":"wait","waitHours":48}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes"

curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"type":"add_tag","tagId":"'$TAG_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes"
Cada uno se añade detrás del anterior y se conecta por ti. Las plantillas vienen de la API de contenido y envío, las etiquetas de la API de audiencia.
4

Vuelve a leer el grafo

bash
curl -s -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes" \
  | jq '.data[] | {id, type, subject, waitHours, tagId}'
Un subject vacío en un send_email es lo que se rechazará al publicar. Corrígelo con PATCH sobre el nodo.
5

Publica

bash
curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/publish"
Un 400 aquí nombra el defecto y los nodos: corrígelos y vuelve a publicar. Este bucle no cuesta nada: todavía no se ha inscrito a nadie.
6

Activa

bash
curl -s -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"status":"active"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID"
A partir de aquí, cada contacto que entra en la lista recorre el recorrido. Publicar sin activar no inscribe a nadie; activar sin publicar responde 400.
7

Cambia algo más adelante

bash
NEW_VERSION_ID=$(curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions" | jq -r '.data.id')
Edita ese borrador, publícalo, y la secuencia cambia a él. Los contactos que ya recorren la versión anterior terminan en ella: nunca cambian de recorrido a mitad de camino.