API

Tout ce que l'application fait sur une audience, un modèle ou une campagne est accessible en HTTP. Un script — ou un agent — travaille sur les mêmes données que l'interface, avec les mêmes règles, sans session de navigateur. Cette page est la carte : l'authentification, la forme de chaque réponse, et chaque endpoint avec la page qui le détaille. Chaque endpoint a sa propre page — un appel, ses paramètres, ses réponses et ce qu'il refuse.

Tous les 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}

Authentification

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 un admin 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é.
Deux règles tranchent chaque appel, et les deux doivent passer :
QuestionTranchée parRé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ôle401 / 403
La ressource appartient-elle à l'organisation de la clé ?L'organisation de la clé404

Qui peut faire quoi

OpérationRôle minimal dans l'organisation
Tout lire, et POST /api/v1/rendermember
Créer, modifier, supprimer, taguer, envoyeradmin
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

CasCorps
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 … ]}
StatutQuand
200Lecture ou modification effectuée
201Ressource créée
202Envoi accepté, en cours en arrière-plan — rien n'est encore terminé
400Paramètres ou corps invalides — details liste les champs en cause
401Clé absente ou invalide, ou clé dont le propriétaire a quitté l'organisation
403L'appelant est un membre légitime, mais son rôle est trop bas
404Ressource inconnue, ou ressource d'une autre organisation
409Conflit d'état — un nom de tag déjà pris, une campagne déjà envoyée
429Limite de débit de la clé dépassée
500Erreur 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épond 429 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 le listId 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.