API

Todo lo que la app hace con una audiencia, una plantilla o una campaña es accesible por HTTP. Un script —o un agente— trabaja sobre los mismos datos que la interfaz, con las mismas reglas, sin sesión de navegador. Esta página es el mapa: la autenticación, la forma de cada respuesta y cada endpoint con la página que lo detalla. Cada endpoint tiene su propia página: una llamada, sus parámetros, sus respuestas y lo que rechaza.

Todos los endpoints

Sequences
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}

Autenticación

Cada solicitud a /api/v1 lleva una clave de API en el encabezado x-api-key. Una clave se crea desde la app y pertenece a una organización: esa organización es todo el alcance de la clave.
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/tags"

La clave actúa como la persona que la creó

Una clave no es una segunda identidad con poderes propios. Lleva los derechos del miembro que la creó, en la organización para la que se creó. Una clave creada por un admin puede escribir; una clave creada por un member puede leer. La API no concede nada que esa misma persona no pueda hacer en la interfaz.
Una clave deja de funcionar cuando su propietario sale de la organización. Ningún acceso huérfano sobrevive a una salida: la clave responde 401 desde ese momento, exactamente como si se hubiera revocado. Revocar la clave de alguien que se fue es, por tanto, una limpieza, no una corrección de seguridad.
Dos reglas deciden cada llamada, y ambas deben cumplirse:
PreguntaLo decideRespuesta cuando falla
¿El llamante sigue siendo miembro, y con qué rol?El propietario de la clave y su rol401 / 403
¿El recurso pertenece a la organización de la clave?La organización de la clave404

Quién puede hacer qué

OperaciónRol mínimo en la organización
Leer cualquier cosa, y POST /api/v1/rendermember
Crear, actualizar, eliminar, etiquetar, enviaradmin
POST /api/v1/render es la excepción entre los verbos de escritura porque no escribe nada: renderiza y devuelve, sin efectos secundarios.

Envoltorio de respuesta

CasoCuerpo
Éxito{"success": true, "data": …}
Lista paginada{"success": true, "data": [...], "pagination": {"total", "page", "limit", "totalPages"}}
Error{"error": "…"}
Error de validación{"error": "…", "details": [ … Zod issues … ]}
EstadoCuándo
200Lectura o mutación realizada
201Recurso creado
202Envío aceptado, en curso en segundo plano: todavía no ha terminado nada
400Parámetros o cuerpo no válidos: details enumera los campos que fallan
401Clave ausente o no válida, o una clave cuyo propietario salió de la organización
403El llamante es un miembro legítimo, pero su rol es insuficiente
404Recurso desconocido, o un recurso de otra organización
409Conflicto de estado: un nombre de etiqueta ya usado, una campaña ya enviada
429Límite de frecuencia de la clave superado
500Error inesperado del servidor
Un recurso de otra organización responde 404, nunca 403. Un 403 confirmaría que el id existe. La misma respuesta para un id desconocido y para un id que no tienes permiso para leer: no puedes distinguirlos, y esa es la idea. El 403 se reserva para la otra pregunta: estás en la organización correcta, pero tu rol es insuficiente.

Límite de frecuencia

El límite lo lleva la clave, no la IP. Una clave que supera su límite responde 429 en todos los endpoints. Espera y vuelve a intentarlo: no se hizo nada.

Por dónde empezar

Empieza por Descubrimiento: dos llamadas convierten una clave sin más en un contexto: la organización que abre y el listId que piden todos los endpoints de audiencia. Después lee la audiencia —una campaña sin lista a la que enviarse no llega a ninguna parte— y compón con plantillas y renderizado. El recorrido completo, desde una organización vacía hasta una newsletter enviada, se detalla de principio a fin al final de Campañas.