Ajouter une étape

POST /api/v1/sequences/{sequenceId}/versions/{versionId}/nodes Ajoute un nœud à un brouillon. Répond 201. Sans afterNodeId, le nœud est ajouté à la fin du parcours ; avec, le nœud est glissé juste après ce nœud et les liaisons sont recousues autour de lui.

Un nœud ne porte qu'une sorte de colonne, celle de son type. Un wait avec un templateId, ou un send_email avec waitHours, répond 400 — la colonne resterait en base sans rien signifier, lue ni par le moteur ni par l'écran. Une mauvaise colonne n'est jamais ignorée en silence : vous en êtes averti.

Créer une étape n'écrit pas son contenu. Un nœud send_email naît avec le contenu par défaut et un objet vide — les seules choses que lit POST sont le type, un templateId, un preheader et les champs de la famille du nœud (waitHours, tagId, webhookUrl). L'objet, le contenu et le sendTimeMinutes d'une étape de série s'écrivent en modifiant l'étape renvoyée.

Un modèle est une copie, pas un lien. Un POST avec un templateId copie son objet et son HTML sur le nœud ; modifier le modèle ensuite ne change rien ici. Sans templateId, le nœud naît vide — sa création est permise, mais il est refusé à la publication tant que vous ne l'avez pas rempli avec PATCH. Même chose pour un nœud d'action sans tag et un webhook sans URL : créez maintenant, complétez avant de publier.

L'URL d'un webhook est vérifiée à l'écriture, pas au déclenchement. Une URL non https, ou qui pointe vers un réseau privé, répond 400 à l'écriture. L'appel lui-même a lieu au plus une fois : il n'est jamais retenté, si bien qu'une destination qui cesse de répondre échoue en silence et pour toujours.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Refusé — `403`

Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Corps de la requête

Champ	Type	Obligatoire	Description
`type`	string	oui	`send_email`, `wait`, `add_tag`, `remove_tag`, `end_sequence`, `webhook`
`templateId`	string	non	`send_email` uniquement — copie l'objet et le HTML du modèle sur le nœud
`preheader`	string	non	`send_email` uniquement — jusqu'à 200 caractères, le texte d'aperçu affiché après l'objet. Un modèle n'en porte pas, c'est donc le seul moyen de le définir à la création
`waitHours`	number	oui	Nombre d'heures entières d'attente
`tagId`	string	non	Le tag que le nœud ajoute ou retire
`webhookUrl`	string	non	L'URL à appeler
`afterNodeId`	string	non	Insérer juste après ce nœud de la même version

Exemple

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"type":"send_email","templateId":"'$TEMPLATE_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes"

Réponse

201 Created — la ressource créée.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
404 Not Found — aucune ressource de ce type, ou elle appartient à une autre organisation. L'API ne confirme jamais l'existence d'un id à un appelant qui n'y a pas droit.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data.id`	string	Identifiant unique de l'étape
`data.versionId`	string	La version brouillon à laquelle elle appartient
`data.type`	string	`send_email`, `wait`, `add_tag`, `remove_tag`, `end_sequence`, `webhook`
`data.subject`	string \| null	Sur une étape `send_email`
`data.preheader`	string	Texte d'aperçu de l'étape ; chaîne vide sur une étape qui n'envoie rien
`data.content`	string \| null	Idem
`data.templateId`	string \| null	Le modèle dont l'étape a été copiée
`data.waitHours`	number \| null	Délai d'une étape `wait`
`data.tagId`	string \| null	Tag d'une étape `add_tag` / `remove_tag`
`data.webhookUrl`	string \| null	URL appelée par une étape `webhook`
`data.createdAt`	string	Date de création ISO
`data.updatedAt`	string	Date ISO de la dernière modification

Exemple de réponse

json

{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "versionId": "c41a7e55",
    "type": "send_email",
    "subject": "August news",
    "preheader": "Three new things this month",
    "content": "<html>…</html>",
    "templateId": "5a44b901",
    "waitHours": 24,
    "tagId": "7c2ef4b1",
    "webhookUrl": "https://example.com/hooks/agentsmail",
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}