Séquences

Une séquence est un parcours automatisé. Un contact y entre sur un déclencheur, puis parcourt un graphe d'étapes à son propre rythme — et le graphe est versionné, si bien qu'un parcours déjà engagé ne change jamais.
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}

Les quatre objets que vous manipulez

ObjetCe que c'est
SéquenceL'identité du parcours : un nom, un statut (active / paused) et un pointeur vers la version en cours d'exécution
VersionUn instantané du parcours, avec son déclencheur. Un draft est modifiable ; une version published ne change plus jamais
NœudUne étape d'une version : send_email, wait, add_tag, remove_tag, end_sequence, webhook
LiaisonUn lien d'un nœud vers le suivant. Ajouter un nœud le relie pour vous ; les liaisons existent pour que vous puissiez recâbler
Deux conséquences traversent tout ce qui suit :
  • Vous ne modifiez jamais un parcours en cours d'exécution. Modifier signifie ouvrir une version brouillon, la changer, puis la publier. Les contacts qui parcourent déjà l'ancienne version la terminent sur l'ancienne version.
  • Le déclencheur vit sur la version, pas sur la séquence. Vous le définissez à la création de la séquence — cet appel crée la version 1 avec lui — et vous le changez comme tout le reste : sur un brouillon, avec un PATCH sur la version, puis en publiant.

La place d'une série

Une série — une séquence pilotée par un calendrier plutôt que par un déclencheur, voir les trois formes d'un envoi — n'est pas un objet distinct ici. Il n'existe pas de ressource /series : une série est une séquence dont la version porte triggerType: "fixed_date", et c'est à ce champ que vous la reconnaissez en lecture. Ce que l'API peut faire, ou non, avec une série :
Série
En créer uneNon. triggerType: "fixed_date" à la création, ou sur le déclencheur d'un brouillon, est refusé avec 400
La lireOui — séquences, versions, nœuds et liaisons se lisent normalement
Renommer, activer, mettre en pause, supprimerOui, comme toute autre séquence
Lire qui la parcourtRien à lire : une série n'inscrit personne, sa liste d'inscriptions est donc vide par construction
Les séries à date fixe se configurent dans l'application, où l'on choisit la date de début et l'heure d'envoi de chaque étape. Les e-mails qu'envoie une série sont des campagnes : chaque étape d'envoi en crée une, nommée <series name> · step N, au moment où l'étape part. Elles se lisent via l'API Campagnes comme n'importe quelle autre campagne — avec une limite à connaître : une campagne ne porte pas la série dont elle provient dans sa charge utile d'API. C'est le nom qui les relie aujourd'hui.
Il n'existe aucun endpoint pour inscrire un contact directement. Les contacts entrent dans une séquence par son déclencheur, et uniquement par lui : l'entrée dans une liste (list_joined) ou la réception d'un tag (tag_added). Utilisez l'API Audience pour ajouter un contact à la liste, ou pour lui attribuer un tag, et l'inscription suit.

Les codes de statut qui comptent ici

Tout ce qui figure dans la référence de l'API s'applique. Trois cas reviennent bien plus souvent ici :
StatutQuand
201Une séquence, une version, un nœud ou une liaison a été créé
400Le parcours refuse ce que vous demandez — un graphe invalide à la publication, une écriture sur une version publiée, une limite de l'offre
404Id inconnu, id appartenant à une autre organisation, ou id appartenant à une autre version
Ce dernier cas mérite d'être lu deux fois : un versionId qui n'est pas une version du sequenceId présent dans l'URL répond 404, tout comme un nodeId absent de cette version. Les ids ne sont jamais lus qu'à l'intérieur du chemin qui y mène.

Ce que signifie une publication refusée

Chaque défaut répond 400, se nomme lui-même, et nomme les nœuds concernés — tous à la fois, pour que vous corrigiez en une seule passe au lieu de republier pour découvrir le suivant.
DéfautCe que cela signifieComment le corriger
emptyLa version n'a aucun nœudAjoutez au moins un nœud
no entryChaque nœud a quelque chose qui pointe vers lui — il n'y a aucune entréeSupprimez la liaison qui ferme la boucle en haut
multiple entriesDeux nœuds n'ont rien qui pointe vers euxReliez l'un derrière l'autre ; un parcours n'a qu'une porte
cycleLes liaisons reviennent sur elles-mêmes — un contact tournerait en boucle indéfinimentSupprimez la liaison qui revient en arrière
orphanUn nœud est inaccessible depuis l'entréeReliez-le, ou supprimez-le
dangling branchUne branche ne mène nulle partReliez son extrémité, ou abandonnez la branche
ambiguous branchUn nœud a deux liaisons sortantes sans moyen de choisirGardez une seule liaison
edge out of graphUne liaison pointe vers un nœud d'une autre versionSupprimez cette liaison et recâblez à l'intérieur de cette version
empty sendUn nœud send_email n'a pas d'objet ou pas de contenuFaites un PATCH du nœud avec un objet et du HTML
incomplete actionUn nœud add_tag / remove_tag n'a pas de tagFaites un PATCH du nœud avec un tagId
end with successorUn nœud end_sequence est suivi d'un autre nœudSupprimez ce qui suit : rien ne s'exécute après la fin
invalid webhookUn nœud webhook n'a pas d'URL, ou une URL que la politique refuseFaites un PATCH du nœud avec une URL publique https://
Une version qui n'est pas un brouillon répond aussi 400 : une version publiée est un instantané, la republier sur place réécrirait ce que les contacts sont en train de parcourir. Utilisez plutôt le retour arrière.

Liaisons

Ajouter un nœud le relie pour vous. Ces endpoints existent pour les formes qu'un ajout en fin ne peut pas produire — et pour en défaire une.

Écrire sur une version publiée

Chaque écriture ci-dessus — ajouter, modifier, supprimer ou déplacer un nœud, relier, délier, changer le déclencheur — répond 400 si la version n'est pas un draft. Ce n'est pas un problème de permission, et réessayer n'y changera rien : les versions publiées sont des instantanés que les contacts exécutent. Le chemin est toujours le même, en trois appels : ouvrir un brouillon, le modifier, le publier.

Une séquence d'accueil, de bout en bout

1

Créer la séquence sur son déclencheur

bash
SEQUENCE_ID=$(curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name":"Onboarding","triggerType":"list_joined","triggerTargetId":"'$LIST_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences" | jq -r '.data.id')
Elle est paused, et la version 1 existe déjà en brouillon.
2

Trouver le brouillon à modifier

bash
VERSION_ID=$(curl -s -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions" \
  | jq -r '.data[] | select(.status=="draft") | .id')
3

Ajouter les étapes, dans l'ordre

bash
curl -s -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"

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

curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"type":"add_tag","tagId":"'$TAG_ID'"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes"
Chacune est ajoutée derrière la précédente, et reliée pour vous. Les modèles viennent de l'API Contenu et envoi, les tags de l'API Audience.
4

Relire le graphe

bash
curl -s -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/nodes" \
  | jq '.data[] | {id, type, subject, waitHours, tagId}'
Un subject vide sur un send_email, c'est ce qui sera refusé à la publication. Corrigez-le avec un PATCH sur le nœud.
5

Publier

bash
curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions/$VERSION_ID/publish"
Un 400 à cette étape nomme le défaut et les nœuds : corrigez-les et publiez à nouveau. Cette boucle ne coûte rien — personne n'a encore été inscrit.
6

Activer

bash
curl -s -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"status":"active"}' \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID"
Dès lors, chaque contact qui entre dans la liste parcourt le parcours. Publier sans activer n'inscrit personne ; activer sans publier répond 400.
7

Changer quelque chose plus tard

bash
NEW_VERSION_ID=$(curl -s -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/sequences/$SEQUENCE_ID/versions" | jq -r '.data.id')
Modifiez ce brouillon, publiez-le, et la séquence bascule dessus. Les contacts qui parcourent déjà la version précédente la terminent — ils ne changent jamais de parcours en cours de route.