Publicar una versión

POST /api/v1/sequences/{sequenceId}/versions/{versionId}/publish Congela el borrador, le pone fecha y apunta la secuencia hacia él. Es el único momento en que se comprueba el grafo, y el único momento en que tiene consecuencias.

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.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 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.

Ejemplo

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/publish"

Respuesta

  • 200 OK: la llamada tuvo éxito.
  • 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

CampoTipoDescripción
successbooleanIndica si la operación tuvo éxito
data.idstringIdentificador único de la versión
data.sequenceIdstringLa secuencia a la que pertenece
data.versionnumberSu número de orden, empezando por 1
data.statusstringdraft o published
data.publishedAtstringnull
data.triggerTypestringlist_joined o tag_added
data.triggerTargetIdstringLa lista o etiqueta que inscribe contactos
data.createdAtstringFecha ISO de creación
data.updatedAtstringFecha ISO del último cambio

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "sequenceId": "9b3f2d10",
    "version": 1,
    "status": "subscribed",
    "publishedAt": "2026-08-23T10:22:05.000Z",
    "triggerType": "list_joined",
    "triggerTargetId": "0b7c51e8",
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}

Receta para agentes

Construye el grafo con libertad y luego lee el rechazo: la validación ocurre al publicar, no en cada edición. Un 400 aquí es el grafo siendo rechazado, no un bug.
js
const publish = await fetch(
  `${base}/sequences/${sequenceId}/versions/${versionId}/publish`,
  {method: 'POST', headers}
)

if (publish.status === 400) {
  const {error, details} = await publish.json()
  // `details` nombra los pasos con defectos: corrige el borrador y vuelve a publicar
  return repairDraft(details ?? error)
}

// Nada se ejecuta hasta que la propia secuencia está activa
await fetch(`${base}/sequences/${sequenceId}`, {
  method: 'PATCH',
  headers: {...headers, 'content-type': 'application/json'},
  body: JSON.stringify({status: 'active'}),
})

Relacionado