Appearance
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
limit | query | integer | Max items per page. Capped at 30. | |
skip | query | integer | Number of items to skip, for pagination. | |
sort | query | string | Field to sort by. | |
order | query | string | ||
filter[<field>] | query | string | Exact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | array | ||
count | integer | Total matching items across all pages, not just this page. | |
next | string | Full 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
trigger | object | Required on create unless basedOn is given. Shape depends on type - see the Automations guide. | |
exitCriteria | object | ||
basedOn | string | Duplicate 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. | |
subscriberListId | string | With basedOn, overrides the duplicated trigger's subscriberListId - lets you clone an automation onto a different list. |
Responses
| Status | Description |
|---|---|
| 201 | Created |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Get a single automation
GET /v1/projectId/{projectId}/automations/{id}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
| 404 | Automations not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes | |
confirm | query | string | Must 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
| Status | Description |
|---|---|
| 200 | OK - check result.confirmationRequired before assuming the automation was actually deleted. |
| 403 | Missing or invalid API key |
| 404 | Automations not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | string (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. |
prevNodeId | string | Create 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
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Update a sequence node
PUT /v1/projectId/{projectId}/automations/{automationId}/node/{id}
Same draft/live routing as adding a node - see POST .../node.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes | The node's _id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | string (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. |
prevNodeId | string | Create 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
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Node not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes | The node's _id. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Node not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
limit | query | integer | Max items per page. Capped at 30. | |
skip | query | integer | Number of items to skip, for pagination. | |
sort | query | string | Field to sort by. | |
order | query | string | ||
filter[<field>] | query | string | Exact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | array | ||
count | integer | Total matching items across all pages, not just this page. | |
next | string | Full 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
| 404 | Email not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
subject | string | ||
previewText | string | ||
type | string (chamaileon | html | text) | ||
document | any | Chamaileon JSON if type is "chamaileon", otherwise an HTML/text string. | |
senderIdentity | string | ||
replyTo | string | ||
trackOpens | boolean | Defaults 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). | |
trackClicks | boolean | Defaults 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). | |
feeds | array 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
subject | string | ||
previewText | string | ||
type | string (chamaileon | html | text) | Set to "chamaileon" to switch an html/text email back to a visual editor JSON document. | |
document | any | HTML/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. | |
senderIdentity | string | ||
replyTo | string | ||
trackOpens | boolean | Defaults 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). | |
trackClicks | boolean | Defaults 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). | |
feeds | array of object |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Email not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
subject | string | ||
previewText | string | ||
type | string (chamaileon | html | text) | ||
document | any | Chamaileon JSON if type is "chamaileon", otherwise an HTML/text string. | |
senderIdentity | string | ||
replyTo | string | ||
trackOpens | boolean | Defaults 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). | |
trackClicks | boolean | Defaults 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). | |
feeds | array 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | Must be true to actually apply this action. |
Responses
| Status | Description |
|---|---|
| 200 | OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
The response is one of these shapes, depending on the request:
Automation
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Option 2
| Field | Type | Required | Description |
|---|---|---|---|
hasErrors | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | Must be true to actually apply this action. |
Responses
| Status | Description |
|---|---|
| 200 | OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
The response is one of these shapes, depending on the request:
Automation
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Option 2
| Field | Type | Required | Description |
|---|---|---|---|
hasErrors | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | Must be true to actually apply this action. |
Responses
| Status | Description |
|---|---|
| 200 | OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
The response is one of these shapes, depending on the request:
Automation
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Option 2
| Field | Type | Required | Description |
|---|---|---|---|
hasErrors | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | Must be true to actually apply this action. |
Responses
| Status | Description |
|---|---|
| 200 | OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
The response is one of these shapes, depending on the request:
Automation
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Option 2
| Field | Type | Required | Description |
|---|---|---|---|
hasErrors | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | Must be true to actually apply this action. |
Responses
| Status | Description |
|---|---|
| 200 | OK - check result.hasErrors/result.confirmationRequired before assuming the action actually applied. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
The response is one of these shapes, depending on the request:
Automation
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | ||
name | string | ||
status | string (draft | active | paused) | ||
trigger | object | Discriminated 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. | |
exitCriteria | object | A condition that removes a contact from this automation mid-flow when true. Has an "active" boolean plus condition fields. | |
sequence | array | The live, running sequence. Use the node sub-resource endpoints to add/update/delete nodes rather than replacing this array directly. | |
draftSequence | array | Present only while this automation is active and has unmerged staged edits. POST .../merge-draft to apply, or .../discard-draft to drop them. | |
draftTrigger | object | Staged trigger edit, present only while active with unmerged changes. | |
draftExitCriteria | object | Staged exit-criteria edit, present only while active with unmerged changes. | |
usedSegments | array of string | ||
lastTriggeredAt | string | ||
createdAt | string | ||
updatedAt | string |
Option 2
| Field | Type | Required | Description |
|---|---|---|---|
hasErrors | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes | The automation's _id. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
| 404 | Automation 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
currentNodeId | path | string | yes | A node _id from the automation's sequence, or the literal string "trigger". |
limit | query | integer | Max items per page. Capped at 30. | |
skip | query | integer | Number of items to skip, for pagination. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object | ||
items[]._id | string | ||
items[].status | string (running | paused) | "paused" means waiting at a delay node, not stuck. | |
items[].pauseUntil | string | When a paused contact continues to the next node (UTC). Only set while paused. | |
items[].currentIndex | integer | ||
items[].contactId | object | Populated contact document, not just an id. | |
count | integer | Total matching items across all pages, not just this page. | |
next | string | Full 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
id | path | string | yes | The automation's _id. |
from | query | string | Only count events at or after this date/time. | |
to | query | string | Only count events at or before this date/time. If both from and to are given, the range between them cannot exceed 366 days. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | Automation not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
contacts | object | ||
contacts.total | integer | Every run ever started, including completed/errored ones. | |
contacts.active | integer | Currently running or paused (waiting at a timer). See GET .../running-nodes for which step they are at. | |
contacts.completed | integer | ||
contacts.error | integer | ||
totals | any | ||
emails | array |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes | The automation email _id (the node's emailId). |
from | query | string | Only count events at or after this date/time. | |
to | query | string | Only count events at or before this date/time. If both from and to are given, the range between them cannot exceed 366 days. | |
interval | query | string | Returns 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). | |
metric | query | string | With interval: what to count per period. subscribe/unsubscribe/resubscribe/pause-subscription/unpause-subscription count subscription changes caused by this email. | |
timeZone | query | string | With interval: IANA time zone the periods are labelled in. Defaults to UTC. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | AutomationEmail not found |
| 405 | The 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
| Field | Type | Required | Description |
|---|---|---|---|
opens | integer | Total open events (a single recipient opening twice counts twice). | |
clicks | integer | Total click events. | |
uniqueOpens | integer | Number of distinct dispatched emails with at least one open. | |
uniqueClicks | integer | Number of distinct dispatched emails with at least one click. | |
sent | integer | ||
failed | integer | ||
bounce | integer | ||
complaint | integer |
EmailStatsTimeline
| Field | Type | Required | Description |
|---|---|---|---|
interval | string (hourly | daily | weekly | monthly) | ||
metric | string | ||
timeZone | string | The time zone the periods are labelled in. | |
from | string | Start of the range actually used (start of the UTC day). | |
to | string | End of the range actually used (end of the UTC day). | |
buckets | array of object | Only periods with activity are listed - missing periods had 0. When nothing happened at all, a single period with count 0 is returned. | |
buckets[].period | string | "YYYY-MM-DD HH:00" (hourly), "YYYY-MM-DD" (daily), "YYYY-MM-DD to YYYY-MM-DD" (weekly) or "YYYY-MM" (monthly). | |
buckets[].count | integer | Not returned for the *PerUniqueOpens metrics. | |
buckets[].rate | number | Count 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | The project _id, found in the app under Project Settings. |
automationId | path | string | yes | |
id | path | string | yes | The automation email _id (the node's emailId). |
limit | query | integer | Max items per page. Capped at 30. | |
skip | query | integer | Number of items to skip, for pagination. | |
sort | query | string | Field to sort by. | |
order | query | string | ||
filter[<field>] | query | string | Exact-match filter on a top-level field, e.g. filter[name]=Welcome. Repeatable for multiple fields. |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 400 | Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit. |
| 403 | Missing or invalid API key |
| 404 | AutomationEmail not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | array | ||
count | integer | Total matching items across all pages, not just this page. | |
next | string | Full URL (path + query string) of the next page, or null if this is the last page. |