Todos los endpoints
Discovery
GETWhere the key stands/api/v1/meLists
GETList the lists/api/v1/listsGETGet one list/api/v1/lists/{listId}POSTCreate a list/api/v1/listsContacts
GETList contacts/api/v1/contactsGETGet a contact/api/v1/contacts/{contactId}POSTAdd or update one contact/api/v1/lists/{listId}/contactsPOSTImport contacts in bulk/api/v1/lists/{listId}/contacts/bulkPATCHUpdate a contact/api/v1/contacts/{contactId}POSTUnsubscribe a contact/api/v1/contacts/{contactId}/unsubscribePOSTResubscribe a contact/api/v1/contacts/{contactId}/resubscribePOSTOpt a contact out of a topic/api/v1/contacts/{contactId}/topics/{topicId}/opt-outPOSTResubscribe a contact to a topic/api/v1/contacts/{contactId}/topics/{topicId}/resubscribeTags
GETList tags/api/v1/tagsPOSTCreate a tag/api/v1/tagsPOSTTag a contact/api/v1/contacts/{contactId}/tagsDELETEUntag a contact/api/v1/contacts/{contactId}/tags/{tagId}Topics
GETList topics/api/v1/topicsPOSTCreate a topic/api/v1/topicsGETGet a topic/api/v1/topics/{topicId}PATCHRename a topic/api/v1/topics/{topicId}DELETEDelete a topic/api/v1/topics/{topicId}Templates
GETList templates/api/v1/templatesGETGet a template/api/v1/templates/{templateId}POSTCreate a template/api/v1/templatesPATCHUpdate a template/api/v1/templates/{templateId}DELETEDelete a template/api/v1/templates/{templateId}POSTTest a template/api/v1/templates/{templateId}/test-sendGETBrowse the gallery/api/v1/template-galleryGETGet a gallery design/api/v1/template-gallery/{galleryTemplateId}POSTRender without sending/api/v1/renderCampaigns
POSTCreate a campaign/api/v1/campaignsGETList campaigns/api/v1/campaignsGETGet a campaign/api/v1/campaigns/{campaignId}PATCHEdit a draft campaign/api/v1/campaigns/{campaignId}POSTSend a campaign/api/v1/campaigns/{campaignId}/sendPOSTTest a campaign/api/v1/campaigns/{campaignId}/test-sendGETRead campaign stats/api/v1/campaigns/{campaignId}/statsPOSTSchedule a campaign/api/v1/campaigns/{campaignId}/scheduleDELETEUnschedule a campaign/api/v1/campaigns/{campaignId}/scheduleSequences
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}Series
GETList series/api/v1/seriesPOSTCreate a series/api/v1/seriesGETGet a series/api/v1/series/{seriesId}PATCHUpdate a series/api/v1/series/{seriesId}DELETEDelete a series/api/v1/series/{seriesId}GETUpcoming steps/api/v1/series/upcomingSign-up pages
GETList sign-up pages/api/v1/signup-pagesPOSTCreate a sign-up page/api/v1/signup-pagesGETGet a sign-up page/api/v1/signup-pages/{id}PATCHUpdate a sign-up page/api/v1/signup-pages/{id}DELETEDelete a sign-up page/api/v1/signup-pages/{id}GETBrowse the theme catalogue/api/v1/signup-page-templatesRecipient links
GETOpen tracking/api/o/{token}GETClick tracking/api/t/{token}POSTOne-click unsubscribe/api/unsubscribe/{token}Settings
GETRead every setting/api/v1/settingsPATCHUpdate sending preferences/api/v1/settings/sendingGETRead the address book/api/v1/settings/identitiesPOSTAdd a sender address/api/v1/settings/identitiesPATCHEdit or promote an address/api/v1/settings/identities/{identityId}DELETERemove an address/api/v1/settings/identities/{identityId}PATCHUpdate sign-up settings/api/v1/settings/optinPOSTTest the confirmation email/api/v1/settings/optin/test-sendAutenticació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 unadmin 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.| Pregunta | Lo decide | Respuesta cuando falla |
|---|---|---|
| ¿El llamante sigue siendo miembro, y con qué rol? | El propietario de la clave y su rol | 401 / 403 |
| ¿El recurso pertenece a la organización de la clave? | La organización de la clave | 404 |
Quién puede hacer qué
| Operación | Rol mínimo en la organización |
|---|---|
Leer cualquier cosa, y POST /api/v1/render | member |
| Crear, actualizar, eliminar, etiquetar, enviar | admin |
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
| Caso | Cuerpo |
|---|---|
| Éxito | {"success": true, "data": …} |
| Lista paginada | {"success": true, "data": [...], "pagination": {"total", "page", "limit", "totalPages"}} |
| Error | {"error": "…"} |
| Error de validación | {"error": "…", "details": [ … Zod issues … ]} |
| Estado | Cuándo |
|---|---|
200 | Lectura o mutación realizada |
201 | Recurso creado |
202 | Envío aceptado, en curso en segundo plano: todavía no ha terminado nada |
400 | Parámetros o cuerpo no válidos: details enumera los campos que fallan |
401 | Clave ausente o no válida, o una clave cuyo propietario salió de la organización |
403 | El llamante es un miembro legítimo, pero su rol es insuficiente |
404 | Recurso desconocido, o un recurso de otra organización |
409 | Conflicto de estado: un nombre de etiqueta ya usado, una campaña ya enviada |
429 | Límite de frecuencia de la clave superado |
500 | Error 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 responde429 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 ellistId 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.