Tous les 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-sendAuthentification
Chaque requête/api/v1 porte une clé d'API dans l'en-tête x-api-key. Une clé se crée depuis l'application et appartient à une seule organisation : cette organisation est tout le périmètre de la clé.
bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
"https://www.agentsmail.io/api/v1/tags"La clé agit au nom de la personne qui l'a créée
Une clé n'est pas une seconde identité dotée de ses propres pouvoirs. Elle porte les droits du membre qui l'a créée, dans l'organisation pour laquelle elle a été créée. Une clé créée par unadmin peut écrire ; une clé créée par un member peut lire. L'API n'accorde rien que la même personne ne pourrait pas faire dans l'interface.
Une clé cesse de fonctionner quand son propriétaire quitte l'organisation. Aucun accès orphelin ne survit à un départ : la clé répond
401 dès cet instant, exactement comme si elle avait été révoquée. Révoquer la clé d'une personne partie relève donc du ménage, pas d'un correctif de sécurité.| Question | Tranchée par | Réponse en cas d'échec |
|---|---|---|
| L'appelant est-il toujours membre, et avec quel rôle ? | Le propriétaire de la clé et son rôle | 401 / 403 |
| La ressource appartient-elle à l'organisation de la clé ? | L'organisation de la clé | 404 |
Qui peut faire quoi
| Opération | Rôle minimal dans l'organisation |
|---|---|
Tout lire, et POST /api/v1/render | member |
| Créer, modifier, supprimer, taguer, envoyer | admin |
POST /api/v1/render est l'exception parmi les verbes d'écriture parce qu'il n'écrit rien : il fait le rendu et le renvoie, sans aucun effet de bord.
Enveloppe des réponses
| Cas | Corps |
|---|---|
| Succès | {"success": true, "data": …} |
| Liste paginée | {"success": true, "data": [...], "pagination": {"total", "page", "limit", "totalPages"}} |
| Erreur | {"error": "…"} |
| Erreur de validation | {"error": "…", "details": [ … Zod issues … ]} |
| Statut | Quand |
|---|---|
200 | Lecture ou modification effectuée |
201 | Ressource créée |
202 | Envoi accepté, en cours en arrière-plan — rien n'est encore terminé |
400 | Paramètres ou corps invalides — details liste les champs en cause |
401 | Clé absente ou invalide, ou clé dont le propriétaire a quitté l'organisation |
403 | L'appelant est un membre légitime, mais son rôle est trop bas |
404 | Ressource inconnue, ou ressource d'une autre organisation |
409 | Conflit d'état — un nom de tag déjà pris, une campagne déjà envoyée |
429 | Limite de débit de la clé dépassée |
500 | Erreur serveur inattendue |
Une ressource d'une autre organisation répond
404, jamais 403. Un 403 confirmerait que l'identifiant existe. Même réponse pour un identifiant inconnu et pour un identifiant que vous n'avez pas le droit de lire — impossible de les distinguer, et c'est voulu. Le 403 est réservé à l'autre question : vous êtes dans la bonne organisation, mais votre rôle est trop bas.Limite de débit
La limite est portée par la clé, pas par l'adresse IP. Une clé qui dépasse sa limite répond429 sur tous les endpoints. Patientez puis réessayez : rien n'a été fait.
Par où commencer
Commencez par Découverte : deux appels transforment une clé nue en contexte — l'organisation qu'elle ouvre, et lelistId que demande chaque endpoint d'audience. Lisez ensuite l'audience — une campagne sans liste à qui l'envoyer ne va nulle part — puis composez avec les modèles et le rendu. Le chemin complet, d'une organisation vide à une newsletter envoyée, est parcouru de bout en bout en bas de Campagnes.