Añadir un paso

POST /api/v1/sequences/{sequenceId}/versions/{versionId}/nodes Añade un nodo a un borrador. Responde 201. Sin afterNodeId, el nodo se añade al final del recorrido; con él, el nodo se inserta justo después de ese nodo y las conexiones se recosen a su alrededor.

Un nodo lleva un solo tipo de columna, la de su tipo. Un wait con un templateId, o un send_email con waitHours, responde 400: la columna quedaría en la base de datos sin significar nada, sin que la leyera ni el motor ni la pantalla. Enviar la columna equivocada nunca se descarta en silencio: se te avisa.

Crear un paso no escribe su contenido. Un nodo send_email nace con el contenido por defecto y un asunto vacío: lo único que lee POST es el type, un templateId, un preheader y los campos de la familia propia del nodo (waitHours, tagId, webhookUrl). El asunto, el contenido y el sendTimeMinutes de un paso de serie se escriben editando el paso que se devuelve.

Una plantilla es una copia, no un vínculo. POST con un templateId copia su asunto y su HTML en el nodo; editar la plantilla después no cambia nada aquí. Sin templateId, el nodo nace vacío: se puede crear, pero se rechaza al publicar hasta que lo rellenes con PATCH. Lo mismo para un nodo de acción sin etiqueta y un webhook sin URL: créalos ahora, complétalos antes de publicar.

La URL de un webhook se comprueba cuando la escribes, no cuando se dispara. Una URL que no es https, o que apunta a una red privada, responde 400 al escribirla. La llamada en sí ocurre como máximo una vez: nunca se reintenta, así que un destino que deja de responder falla en silencio y para siempre.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Rechazado — `403`

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol en AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`type`	string	sí	`send_email`, `wait`, `add_tag`, `remove_tag`, `end_sequence`, `webhook`
`templateId`	string	no	Solo `send_email`: copia el asunto y el HTML de la plantilla en el nodo
`preheader`	string	no	Solo `send_email`: hasta 200 caracteres, el texto de vista previa que se muestra tras el asunto. Una plantilla no lleva ninguno, así que es la única forma de definirlo al crear
`waitHours`	number	sí	Horas completas de espera
`tagId`	string	no	La etiqueta que el nodo pone o quita
`webhookUrl`	string	no	La URL a la que llamar
`afterNodeId`	string	no	Insertar justo después de este nodo de la misma versión

Ejemplo

bash

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

Respuesta

201 Created: el recurso creado.
401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
404 Not Found: no existe ese recurso, o pertenece a otra organización. La API nunca confirma que un id existe a quien no tiene derecho sobre él.
429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.id`	string	Identificador único del paso
`data.versionId`	string	La versión en borrador a la que pertenece
`data.type`	string	`send_email`, `wait`, `add_tag`, `remove_tag`, `end_sequence`, `webhook`
`data.subject`	string \| null	En un paso `send_email`
`data.preheader`	string	Texto de vista previa del paso; cadena vacía en un paso que no envía nada
`data.content`	string \| null	Igual
`data.templateId`	string \| null	La plantilla de la que se copió el paso
`data.waitHours`	number \| null	Retraso de un paso `wait`
`data.tagId`	string \| null	Etiqueta de un paso `add_tag` / `remove_tag`
`data.webhookUrl`	string \| null	URL llamada por un paso `webhook`
`data.createdAt`	string	Fecha ISO de creación
`data.updatedAt`	string	Fecha ISO del último cambio

Ejemplo de respuesta

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "versionId": "c41a7e55",
    "type": "send_email",
    "subject": "August news",
    "preheader": "Three new things this month",
    "content": "<html>…</html>",
    "templateId": "5a44b901",
    "waitHours": 24,
    "tagId": "7c2ef4b1",
    "webhookUrl": "https://example.com/hooks/agentsmail",
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}