Automations ​

Full reference for the Automations resource in the bluefox.email API. See the API overview for authentication, the response envelope, and pagination.

List automations ​

GET /v1/projectId/{projectId}/automations

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
limitqueryintegerMax items per page. Capped at 30.
skipqueryintegerNumber of items to skip, for pagination.
sortquerystringField to sort by.
orderquerystring
filter[<field>]querystringExact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields.

Responses ​

StatusDescription
200OK
403Missing or invalid API key

Response body ​

FieldTypeRequiredDescription
itemsarray
countintegerTotal matching items across all pages, not just this page.
nextstringFull URL (path + query string) of the next page, or null if this is the last page.

Create a automation ​

POST /v1/projectId/{projectId}/automations

Either provide trigger directly, or basedOn to duplicate an existing automation. The automation always starts in "draft" status - use POST .../automations/{id}/activate once its trigger and sequence are ready.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.

Request body ​

FieldTypeRequiredDescription
namestringyes
triggerobjectRequired on create unless basedOn is given. Shape depends on type - see the Automations guide.
exitCriteriaobject
basedOnstringDuplicate an existing automation (by _id) as the starting point - copies its sequence, trigger, and exit criteria. The new automation is always created in "draft" status regardless of the source's status.
subscriberListIdstringWith basedOn, overrides the duplicated trigger's subscriberListId - lets you clone an automation onto a different list.

Responses ​

StatusDescription
201Created
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Get a single automation ​

GET /v1/projectId/{projectId}/automations/{id}

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Responses ​

StatusDescription
200OK
403Missing or invalid API key
404Automations not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Delete a automation ​

DELETE /v1/projectId/{projectId}/automations/{id}

This also deletes the automation's email content and running-contact history, and cannot be undone.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes
confirmquerystringMust be exactly "true" to actually delete. Omit it to get back the automation's current full state with confirmationRequired: true instead, with nothing deleted. A query param rather than a body field, since DELETE requests can't reliably carry a body through every proxy/gateway in between. Always fetch and show the caller (or end user) that state before confirming.

Responses ​

StatusDescription
200OK - check result.confirmationRequired before assuming the automation was actually deleted.
403Missing or invalid API key
404Automations not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Rename an automation ​

PATCH /v1/projectId/{projectId}/automations/{id}

Only the name can be changed here. trigger, exitCriteria, sequence, and status all have their own dedicated endpoints (node sub-resource, lifecycle actions) so validation and draft-staging always apply.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
namestringyes

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Set an automation's trigger ​

PATCH /v1/projectId/{projectId}/automations/{automationId}/trigger

While the automation is "draft", writes the live trigger directly. Once active/paused, stages it as draftTrigger instead - it only takes effect after POST .../merge-draft. Not validated at set-time (shape/business-rule validation happens at activate/merge-draft).

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Set an automation's exit criteria ​

PATCH /v1/projectId/{projectId}/automations/{automationId}/exit-criteria

Same draft/live routing as the trigger endpoint above. Pass { active: false } to clear it.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Add a sequence node to an automation ​

POST /v1/projectId/{projectId}/automations/{automationId}/node

While the automation is "draft", inserts directly into the live sequence. While "active" or "paused", the node is inserted into (a copy of) the sequence staged as draftSequence instead, leaving the running automation untouched until POST .../merge-draft.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes

Request body ​

FieldTypeRequiredDescription
typestring (delay | send-email | filter-audience | branch | condition | set-value | notify | complete | manage-tags | webhook)yes"condition" is special: it does not add a top-level node. Instead, set prevNodeId to an EXISTING branch node's own _id, and it appends one more arm to that branch's branches[] (branches start with two). Its condition fields go under a nested "condition" object in the body, e.g. { "type": "condition", "prevNodeId": "<branchNodeId>", "condition": { "property": "...", "operator": "...", "value": "..." } } - not flat on the request body like filter-audience.
prevNodeIdstringCreate only. Insert immediately after this node (a sibling _id anywhere in the tree, including inside a branch). Omit to insert as the very first node.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Update a sequence node ​

PUT /v1/projectId/{projectId}/automations/{automationId}/node/{id}

Same draft/live routing as adding a node - see POST .../node.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyesThe node's _id.

Request body ​

FieldTypeRequiredDescription
typestring (delay | send-email | filter-audience | branch | condition | set-value | notify | complete | manage-tags | webhook)yes"condition" is special: it does not add a top-level node. Instead, set prevNodeId to an EXISTING branch node's own _id, and it appends one more arm to that branch's branches[] (branches start with two). Its condition fields go under a nested "condition" object in the body, e.g. { "type": "condition", "prevNodeId": "<branchNodeId>", "condition": { "property": "...", "operator": "...", "value": "..." } } - not flat on the request body like filter-audience.
prevNodeIdstringCreate only. Insert immediately after this node (a sibling _id anywhere in the tree, including inside a branch). Omit to insert as the very first node.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Node not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Delete a sequence node ​

DELETE /v1/projectId/{projectId}/automations/{automationId}/node/{id}

A send-email/notify node whose email content already exists is only marked deleted on the staged draft (so a merge can still remove it) rather than being spliced out immediately, when the automation is active/paused. Same draft/live routing as adding a node otherwise.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyesThe node's _id.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Node not found

Response body ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

List the email content documents belonging to an automation ​

GET /v1/projectId/{projectId}/automations/{automationId}/email

One item per send-email/notify node that has been given content. Pass filter[nodeId]=<node _id> to instead get only the emails that run at or before that node in the sequence (useful for showing "what has this contact already received by this point").

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
limitqueryintegerMax items per page. Capped at 30.
skipqueryintegerNumber of items to skip, for pagination.
sortquerystringField to sort by.
orderquerystring
filter[&lt;field&gt;]querystringExact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields.

Responses ​

StatusDescription
200OK
403Missing or invalid API key

Response body ​

FieldTypeRequiredDescription
itemsarray
countintegerTotal matching items across all pages, not just this page.
nextstringFull URL (path + query string) of the next page, or null if this is the last page.

Get a single send-email/notify node's email content ​

GET /v1/projectId/{projectId}/automations/{automationId}/email/{id}

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyes

Responses ​

StatusDescription
200OK
403Missing or invalid API key
404Email not found

Response body ​

FieldTypeRequiredDescription
_idstring
subjectstring
previewTextstring
typestring (chamaileon | html | text)
documentanyChamaileon JSON if type is "chamaileon", otherwise an HTML/text string.
senderIdentitystring
replyTostring
trackOpensbooleanDefaults to true. When false, no open-tracking pixel is added to this email, so opens are not recorded (open stats and open-based segments/conditions get no data from it).
trackClicksbooleanDefaults to true. When false, links in this email are sent as-is instead of through the click tracker, so clicks are not recorded (click stats and click-based segments/conditions get no data from it).
feedsarray of object

Update a send-email/notify node's email content ​

PATCH /v1/projectId/{projectId}/automations/{automationId}/email/{id}

Merges the given fields into the existing content. Same draft/live routing as node edits - while the automation is active/paused this is staged and has no effect until POST .../merge-draft.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyes

Request body ​

FieldTypeRequiredDescription
subjectstring
previewTextstring
typestring (chamaileon | html | text)Set to "chamaileon" to switch an html/text email back to a visual editor JSON document.
documentanyHTML/text string when type is "html"/"text" (Handlebars, same merge tags as campaign emails). Otherwise: A Chamaileon visual-editor JSON document (type "chamaileon"): an object with a top-level "body". To change an existing design, GET the email/template, edit its document and send it back. To write one: {"body":{"type":"body","style":{"backgroundColor":"#f4f4f4"},"children":[fullwidth elements]}}. - A fullwidth element is {"type":"fullwidth","style":{"contentBackgroundColor":"#ffffff","contentPaddingTop":"20px",...},"children":[elements]} (600px wide). - Elements inside it: {"type":"text","attrs":{"text":"<h1>..</h1><p>..</p>"},"style":{"paragraphFontFamily":"Verdana, Geneva, sans-serif","paragraphColor":"#333333","paragraphFontSize":"16px","linkColor":"#0094c5","h1FontFamily":"Georgia, serif","h1Color":"#111111"}} (also h2/h3 FontFamily, Color, FontSize - set link colors here, an inline color on <a> is overridden), {"type":"button","attrs":{"text":"<p>Shop</p>","href":"https://.."},"style":{"backgroundColor":"#0094c5"}}, {"type":"image","attrs":{"src":"https://..","altText":"..","link":""},"style":{"width":"560px","maxWidth":"560px"}}, {"type":"divider"}, {"type":"social","attrs":{"elements":[{"type":"Facebook","link":"https://..","src":"img/Facebook/fb-3-colorful.png"}],"color":"colorful","iconSet":3}} (src is img/<network>/<prefix>-<iconSet>-<color>.png; iconSet 1-5; color colorful, black, grey or white; networks and prefixes: Blogger BL, Facebook fb, Instagram ig, Linkedin li, Medium ME, Pinterest PT, Snapchat SN, SoundCloud SC, Spotify SP, Telegram TG, TikTok tt, Tumblr TU, Twitter tw, Vimeo VI, Vkontakte VK, WeChat WC, YouTube YT), {"type":"box","style":{"backgroundColor":"..","paddingTop":"16px","borderRadius":"8px"},"children":[elements]}, columns {"type":"multicolumn","children":[{"type":"column","style":{"width":"280px"},"children":[elements]}, ...]} (widths add up to the space available), {"type":"typed-text","attrs":{"text":"Plain text"},"style":{"subType":"heading1","fontSize":"32px","color":"#111111","fontFamily":"Georgia, serif","align":"center","bold":true}} (subType paragraph, heading1-3 or list; takes plain text and its own style, while text takes HTML), {"type":"code","attrs":{"title":"Custom HTML","content":"<div style="font-size:16px">..</div>"}} (raw HTML, it must set its own font-size), {"type":"dynamic-image","attrs":{"src":"{{this.image.url}}","altText":".."},"style":{"width":"150px","height":"150px"}} (image URL from a merge tag), {"type":"video","attrs":{"videoId":"..","videoProvider":"youtube","link":"https://..","previewBaseUrl":"https://video.chamaileon.io/thumbnail/original/","thumbnailBaseUrl":"https://video.chamaileon.io/thumbnail/generated/"}} (thumbnail generated from the videoId; not in the app editor's toolbox). - Personalization: {"type":"loop","attrs":{"expression":"news.item limit=5 skip=0"},"children":[elements]} repeats its children per feed item (use {{this.title}} inside; add the feed in the feeds field), and {"type":"conditional","children":[{"type":"branch","attrs":{"type":"if","expression":"(EQ contact.plan "pro")"},"children":[elements]},{"type":"branch","attrs":{"type":"else"},"children":[elements]}]} (branch type if, else-if or else). block-level-loop and block-level-conditional work the same but sit directly in body and wrap whole fullwidth elements. - To give conditional branches different backgrounds, put a box with the background in each branch: the generator can apply the first branch's fullwidth colors to all branches. - Nesting: body holds only fullwidth and block-level-*; fullwidth, box, column, loop and branch hold elements; multicolumn holds only column; conditional holds only branch. - Colors, fonts and images can use a design system variable, e.g. "color":{"reference":"name","default":"#111111"} (see GET /v1/projectId/{projectId}/design-systems). - Every element needs a unique "eid" and style values are CSS strings with px units. The MCP server fills in any missing eid and the editor's default style/attrs keys for you; this API stores the document exactly as sent, so send complete elements (e.g. copy them from an existing document). - Merge tags like {{contact.name}} and {{unsubscribeLink}} work in text and links. Quote strings in them with single quotes, e.g. {{DEFAULT contact.url 'https://..'}}: double quotes break the generated src and href attributes.
senderIdentitystring
replyTostring
trackOpensbooleanDefaults to true. When false, no open-tracking pixel is added to this email, so opens are not recorded (open stats and open-based segments/conditions get no data from it).
trackClicksbooleanDefaults to true. When false, links in this email are sent as-is instead of through the click tracker, so clicks are not recorded (click stats and click-based segments/conditions get no data from it).
feedsarray of object

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Email not found

Response body ​

FieldTypeRequiredDescription
_idstring
subjectstring
previewTextstring
typestring (chamaileon | html | text)
documentanyChamaileon JSON if type is "chamaileon", otherwise an HTML/text string.
senderIdentitystring
replyTostring
trackOpensbooleanDefaults to true. When false, no open-tracking pixel is added to this email, so opens are not recorded (open stats and open-based segments/conditions get no data from it).
trackClicksbooleanDefaults to true. When false, links in this email are sent as-is instead of through the click tracker, so clicks are not recorded (click stats and click-based segments/conditions get no data from it).
feedsarray of object

Activate a draft automation ​

POST /v1/projectId/{projectId}/automations/{id}/activate

Validates the trigger and the full sequence (every node's required fields, branch conditions, and any send-email/notify node's referenced email content) before doing anything. If validation fails, nothing is changed and the response has hasErrors: true with each problem node's error array populated - fix and call again. On success the automation becomes "active" and starts running for matching contacts. Requires { "confirm": true } in the body - omit it (or send false) to get back the automation's current full state with confirmationRequired: true instead, with nothing applied. Always fetch and show the caller (or end user) that state before sending confirm: true.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
confirmbooleanMust be true to actually apply this action.

Responses ​

StatusDescription
200OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied.
403Missing or invalid API key
404Automation not found

Response body ​

The response is one of these shapes, depending on the request:

Automation ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Option 2 ​

FieldTypeRequiredDescription
hasErrorsboolean

Merge staged draft changes into a live automation ​

POST /v1/projectId/{projectId}/automations/{id}/merge-draft

Only meaningful when status is "active" or "paused" and draftSequence/draftTrigger/draftExitCriteria are present (i.e. node/trigger/exit-criteria edits were made after the automation went live). Re-validates the same way as activate and is a no-op (hasErrors: true, nothing persisted) on failure. On success, the staged draft becomes the live sequence/trigger/exitCriteria and any contact currently mid-automation is transitioned onto the new sequence from its current position. Requires { "confirm": true } in the body - omit it (or send false) to get back the automation's current full state with confirmationRequired: true instead, with nothing applied. Always fetch and show the caller (or end user) that state before sending confirm: true.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
confirmbooleanMust be true to actually apply this action.

Responses ​

StatusDescription
200OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied.
403Missing or invalid API key
404Automation not found

Response body ​

The response is one of these shapes, depending on the request:

Automation ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Option 2 ​

FieldTypeRequiredDescription
hasErrorsboolean

Discard staged draft changes ​

POST /v1/projectId/{projectId}/automations/{id}/discard-draft

Drops draftSequence/draftTrigger/draftExitCriteria without touching the live, running automation - use when staged edits turned out to be wrong. Not validated (there is nothing to validate away). Requires { "confirm": true } in the body - omit it (or send false) to get back the automation's current full state with confirmationRequired: true instead, with nothing applied. Always fetch and show the caller (or end user) that state before sending confirm: true.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
confirmbooleanMust be true to actually apply this action.

Responses ​

StatusDescription
200OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied.
403Missing or invalid API key
404Automation not found

Response body ​

The response is one of these shapes, depending on the request:

Automation ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Option 2 ​

FieldTypeRequiredDescription
hasErrorsboolean

Pause a live automation ​

POST /v1/projectId/{projectId}/automations/{id}/pause

Stops the automation from processing further steps for any contact, and stops new contacts from entering it, without discarding its configuration - resume to continue exactly where it left off. Requires { "confirm": true } in the body - omit it (or send false) to get back the automation's current full state with confirmationRequired: true instead, with nothing applied. Always fetch and show the caller (or end user) that state before sending confirm: true.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
confirmbooleanMust be true to actually apply this action.

Responses ​

StatusDescription
200OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied.
403Missing or invalid API key
404Automation not found

Response body ​

The response is one of these shapes, depending on the request:

Automation ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Option 2 ​

FieldTypeRequiredDescription
hasErrorsboolean

Resume a paused automation ​

POST /v1/projectId/{projectId}/automations/{id}/resume

Re-validates the same way as activate (a paused automation's configuration may have been edited while paused) and is a no-op on failure. Requires { "confirm": true } in the body - omit it (or send false) to get back the automation's current full state with confirmationRequired: true instead, with nothing applied. Always fetch and show the caller (or end user) that state before sending confirm: true.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyes

Request body ​

FieldTypeRequiredDescription
confirmbooleanMust be true to actually apply this action.

Responses ​

StatusDescription
200OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied.
403Missing or invalid API key
404Automation not found

Response body ​

The response is one of these shapes, depending on the request:

Automation ​

FieldTypeRequiredDescription
_idstring
namestring
statusstring (draft | active | paused)
triggerobjectDiscriminated by trigger.type (contact-added | contact-updated | enter-segment | leave-segment | time-based) - shape varies by type, see the Automations guide. Every type except time-based also supports runOnce (boolean, default true): when true, a contact who has ever run this automation before is skipped even if the trigger matches again; set false to let them re-enter each time it matches.
exitCriteriaobjectA condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields.
sequencearrayThe live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly.
draftSequencearrayPresent only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them.
draftTriggerobjectStaged trigger edit, present only while active with unmerged changes.
draftExitCriteriaobjectStaged exit-criteria edit, present only while active with unmerged changes.
usedSegmentsarray of string
lastTriggeredAtstring
createdAtstring
updatedAtstring

Option 2 ​

FieldTypeRequiredDescription
hasErrorsboolean

Count currently running/waiting contacts per node ​

GET /v1/projectId/{projectId}/automations/{id}/running-nodes

One entry per node _id currently occupied by at least one contact, e.g. { "<nodeId>": 3 }. Only counts contacts with status "running" or "paused" (waiting at a delay node until its pauseUntil time; not completed/errored). Contacts enrolled but not yet at any node are counted under the key "undefined" - list them with currentNodeId "trigger". Use GET .../running-nodes/{currentNodeId} to list the actual contacts at one node.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyesThe automation's _id.

Responses ​

StatusDescription
200OK
403Missing or invalid API key
404Automation not found

List the contacts currently at one node ​

GET /v1/projectId/{projectId}/automations/{automationId}/running-nodes/{currentNodeId}

Only contacts with status "running" or "paused" ("paused" means waiting at a delay node - pauseUntil says when it continues). Pass "trigger" as currentNodeId (instead of a real node _id) to list contacts who have been enrolled but haven't reached the first node yet.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
currentNodeIdpathstringyesA node _id from the automation's sequence, or the literal string "trigger".
limitqueryintegerMax items per page. Capped at 30.
skipqueryintegerNumber of items to skip, for pagination.

Responses ​

StatusDescription
200OK
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
itemsarray of object
items[]._idstring
items[].statusstring (running | paused)"paused" means waiting at a delay node, not stuck.
items[].pauseUntilstringWhen a paused contact continues to the next node (UTC). Only set while paused.
items[].currentIndexinteger
items[].contactIdobjectPopulated contact document, not just an id.
countintegerTotal matching items across all pages, not just this page.
nextstringFull URL (path + query string) of the next page, or null if this is the last page.

Get stats for an automation ​

GET /v1/projectId/{projectId}/automations/{id}/stats

How many contacts have gone through it (active/completed/errored) plus opens/clicks/sends/bounces/complaints for each of its emails and summed across them. The optional from/to range only applies to the email stats.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
idpathstringyesThe automation's _id.
fromquerystringOnly count events at or after this date/time.
toquerystringOnly count events at or before this date/time. If both from and to are given, the range between them cannot exceed 366 days.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404Automation not found

Response body ​

FieldTypeRequiredDescription
contactsobject
contacts.totalintegerEvery run ever started, including completed/errored ones.
contacts.activeintegerCurrently running or paused (waiting at a timer). See GET .../running-nodes for which step they are at.
contacts.completedinteger
contacts.errorinteger
totalsany
emailsarray

Get stats for one automation email ​

GET /v1/projectId/{projectId}/automations/{automationId}/email/{id}/stats

Same counts as the other email stats endpoints, for the email sent by one send-email/notify node. Pass interval + metric for an hourly/daily/weekly/monthly breakdown instead of totals. For who received/opened/clicked it, see GET .../email/{id}/recipients.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyesThe automation email _id (the node's emailId).
fromquerystringOnly count events at or after this date/time.
toquerystringOnly count events at or before this date/time. If both from and to are given, the range between them cannot exceed 366 days.
intervalquerystringReturns an EmailStatsTimeline (per-period breakdown, same as the app's stats chart) instead of totals. Requires metric. With interval, from/to are rounded to whole UTC days and default to the last 7 days (hourly) or the last month (others). Max range: hourly 7 days, daily 60 days, weekly/monthly 12 months (405 when exceeded).
metricquerystringWith interval: what to count per period. subscribe/unsubscribe/resubscribe/pause-subscription/unpause-subscription count subscription changes caused by this email.
timeZonequerystringWith interval: IANA time zone the periods are labelled in. Defaults to UTC.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404AutomationEmail not found
405The operation is blocked by a business rule (e.g. the resource is still in use)

Response body ​

The response is one of these shapes, depending on the request:

EmailStats ​

FieldTypeRequiredDescription
opensintegerTotal open events (a single recipient opening twice counts twice).
clicksintegerTotal click events.
uniqueOpensintegerNumber of distinct dispatched emails with at least one open.
uniqueClicksintegerNumber of distinct dispatched emails with at least one click.
sentinteger
failedinteger
bounceinteger
complaintinteger

EmailStatsTimeline ​

FieldTypeRequiredDescription
intervalstring (hourly | daily | weekly | monthly)
metricstring
timeZonestringThe time zone the periods are labelled in.
fromstringStart of the range actually used (start of the UTC day).
tostringEnd of the range actually used (end of the UTC day).
bucketsarray of objectOnly periods with activity are listed - missing periods had 0. When nothing happened at all, a single period with count 0 is returned.
buckets[].periodstring"YYYY-MM-DD HH:00" (hourly), "YYYY-MM-DD" (daily), "YYYY-MM-DD to YYYY-MM-DD" (weekly) or "YYYY-MM" (monthly).
buckets[].countintegerNot returned for the *PerUniqueOpens metrics.
buckets[].ratenumberCount metrics: the count as a percentage of all sends (null when nothing was sent). *PerUniqueOpens metrics: the percentage itself. Not returned for subscription metrics.

List recipients of one automation email ​

GET /v1/projectId/{projectId}/automations/{automationId}/email/{id}/recipients

One row per actual recipient - who received it, how many times they opened/clicked, and whether they bounced/complained/unsubscribed/paused/subscribed/resubscribed as a result of this specific send. Supports the usual filter[<field>] exact-match filtering (e.g. filter[unsubscribed]=true, filter[status]=failed), plus two convenience filters not tied to a literal field: filter[opened]=true/false and filter[clicked]=true/false.

Parameters ​

NameInTypeRequiredDescription
projectIdpathstringyesThe project _id, found in the app under Project Settings.
automationIdpathstringyes
idpathstringyesThe automation email _id (the node's emailId).
limitqueryintegerMax items per page. Capped at 30.
skipqueryintegerNumber of items to skip, for pagination.
sortquerystringField to sort by.
orderquerystring
filter[&lt;field&gt;]querystringExact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields.

Responses ​

StatusDescription
200OK
400Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
403Missing or invalid API key
404AutomationEmail not found

Response body ​

FieldTypeRequiredDescription
itemsarray
countintegerTotal matching items across all pages, not just this page.
nextstringFull URL (path + query string) of the next page, or null if this is the last page.