Automations

An automation enrolls a contact when a trigger matches, waits through any delay steps, and sends email.

Overview

An automation is created as a draft. Activate Automation starts enrollment. Pause Automation stops new enrollment and leaves contacts who are already in it where they are.

steps is a chain of delay and send-email steps. The chain may end in one branch step, whose arms check whether the contact is in a segment. See Step Object and Structure.

Endpoints

Method	Endpoint	Description
GET	/automations	List automations
POST	/automations	Create an automation
GET	/automations/{uuid}	Get an automation
PATCH	/automations/{uuid}	Update an automation
DELETE	/automations/{uuid}	Delete an automation
POST	/automations/{uuid}/duplicate	Duplicate an automation
POST	/automations/{uuid}/activate	Activate an automation
POST	/automations/{uuid}/pause	Pause an automation

Automation Object

Get Automation, Create Automation, Update Automation, Duplicate Automation, Activate Automation, and Pause Automation return this object:

Field	Type	Description
uuid	string	Unique identifier for the automation
name	string	Automation name
status	string	draft, active, or paused. See Statuses.
structure	string	linear or branched. See Structure.
trigger	object|null	What enrolls a contact. null when the automation has no trigger. See Trigger Object.
reentry_policy	string	once or multiple_times. Set on create. once — a contact who has already entered is not enrolled again. multiple_times — a contact can enter again each time the trigger matches.
timezone_mode	string|null	Whose clock a delay uses: contact (the contact's timezone), tenant (the workspace timezone), or fixed (the timezone in timezone_uuid). null when it has not been set. Set on create. contact and tenant both require a workspace timezone before activation — see Activate Automation.
timezone_uuid	string|null	Timezone UUID from List Timezones. Set only when timezone_mode is fixed. Otherwise null.
language	string|null	Two-letter language code, stored lowercase. null when unset. Set on create.
steps	array|null	The chain, in send order. [] when the automation has no steps. null when the steps cannot be represented here. See Step Object and Structure.
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

List Automations omits reentry_policy, timezone_mode, timezone_uuid, language, and steps.

reentry_policy, timezone_mode, timezone_uuid, and language are set on Create Automation. Sending them on Update Automation returns 422 VALIDATION_ERROR.

Trigger Object

Exactly one target applies to type. The other UUIDs are null.

Field	Type	Description
type	string	contact_added_to_list, contact_entered_segment, product_purchased, contact_added_to_waitlist, or contact_updated
list_uuid	string|null	List the contact is added to. Set for contact_added_to_list. null for every other type, and null when that list no longer exists.
segment_uuid	string|null	Segment the contact enters. Set for contact_entered_segment. null for every other type, and null when that segment no longer exists.
product_uuid	string|null	Product whose purchase enrolls the contact. Set for product_purchased. null for every other type.
variant_uuid	string|null	Variant of product_uuid whose purchase enrolls the contact. null when not set, and for every other type.
waitlist_uuid	string|null	Waitlist the contact joins. Set for contact_added_to_waitlist. null for every other type.
conditions	array|null	Conditions when type is contact_updated. null for every other type. See Condition Object.

list_uuid and segment_uuid must be a list or segment on your account. product_uuid, variant_uuid, and waitlist_uuid are the UUIDs of a product, variant, and waitlist in your store. For contact_updated, every UUID is null.

Condition Object

A condition on a contact_updated trigger. The contact enrolls when the named field changes and the condition matches the new value.

A write takes exactly one condition — see the rules below the table. A read can return conditions with no items or with several, and a returned condition can have field_kind, field_key, or operator set to null, for an automation whose trigger was saved in the dashboard.

Field	Type	Description
field_kind	string|null	property or custom_field.
field_key	string|null	email, first_name, or last_name when field_kind is property. null on a custom field.
custom_field_uuid	string|null	Custom field this condition watches. Set when field_kind is custom_field. null on a property, and null when that field no longer exists.
operator	string|null	How the new value is compared.
value	string|number|boolean|null	Comparison value. null for changed, is_empty, and is_not_empty.

Send conditions with exactly one item when type is contact_updated, and omit the list, segment, product, variant, and waitlist UUIDs. Those UUIDs on contact_updated, or conditions on any other type, return 422 VALIDATION_ERROR. Send field_key for a property and omit custom_field_uuid. Send custom_field_uuid for a custom field and omit field_key. A custom_field_uuid that is not a custom field on your account returns 422 VALIDATION_ERROR on trigger.conditions.0.custom_field_uuid. An empty conditions array, or more than one condition, returns 422 VALIDATION_ERROR.

operator is one of the operators listed for what the condition watches:

Watches	Operators
A contact property, or a text custom field	changed, equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty
A number, date, or datetime custom field	changed, equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal
A boolean custom field	changed, equals
A select custom field	changed, equals, not_equals
A list custom field	changed, contains, not_contains, is_empty, is_not_empty
An exists custom field	changed

value is required for every operator except changed, is_empty, and is_not_empty, and is null for those three. A property, text, list, or select value is a string. A select value is one of that field's options. A number is a number. A boolean is true or false. A date is YYYY-MM-DD. A datetime is an ISO 8601 datetime string. A list value is one item, not an array.

On a number custom field, these values return 422 VALIDATION_ERROR on trigger.conditions.0.value:

Value	Message
Not numeric	Value must be numeric.
Numeric but not finite, such as 1e999	Value must be a finite number.
Fractional, on a field that accepts only whole numbers	Value must be an integer.
A whole number outside the supported integer range, on a field that accepts only whole numbers	Value is outside the supported integer range.

Step Object

A step is a timer, a send_email, or a branch. Fields that do not apply to type are null. Every step includes branches: null on a timer and on a send_email, including steps inside an arm.

On create and update, a field that does not apply to the step's type may be sent as null; it is ignored. Any other value for that field returns 422 VALIDATION_ERROR. On update, a step returned by Get Automation can be sent back as returned. A body that reports content_overwrite_required still needs overwrite — see Email body.

Field	Type	Description
uuid	string	Step UUID. Send it back on update to keep this step. A kept send_email step takes every email field from the request — see Update Automation.
type	string	timer, send_email, or branch
delay_value	integer|null	How long a timer waits. An integer of at least 1, and at most 3650 days, 87600 hours, or 5256000 minutes. null on a send_email or branch step.
delay_unit	string|null	minutes, hours, or days. null on a send_email or branch step.
name	string|null	Email name. Omitting it on a send_email step uses the subject. null on a timer or branch step.
subject	string|null	Email subject. null on a timer or branch step.
preheader	string|null	Preview text shown after the subject. null when unset, or on a timer or branch step.
from_name	string|null	Sender display name. null when unset, or on a timer or branch step.
reply_to	string|null	Reply-to address. null when unset, or on a timer or branch step.
from_identity	string|null	UUID of the sender identity. null on a timer or branch step. A sender that is not yet enabled can be saved on a draft; activation then returns email_sender_not_sendable.
from_email	string|null	Address of from_identity. null on a timer or branch step.
content	string|null	Email body as Markdown. null on a timer or branch step, or when the body is empty. See Email body.
content_editable_via_api	boolean|null	true when the body is empty or Markdown can represent it. false when the body has layout Markdown cannot keep. null on a timer or branch step.
content_overwrite_required	boolean|null	true when replacing this body discards styling or layout unless overwrite is true. null on a timer or branch step.
branches	array|null	Arms of a branch step, in the order they are checked. null on a timer or send_email step. See Branch Object.

The chain is in send order and holds 1 to 50 steps. It must include at least one send_email, in the top-level steps or inside an arm. A branch, when present, is the last step and has 2 to 10 arms. Each arm holds 1 to 50 steps and ends the run.

These requests return 422 VALIDATION_ERROR:

• steps, branches, or an arm's steps that is not a JSON array
• A chain, branches, or an arm's steps with fewer or more items than the limits above
• A send_email step whose subject, content, or from_identity is missing, empty, or only whitespace, such as The steps.1.subject field is required.
• A delay_value above the maximum for its delay_unit, such as The steps.0.delay_value field must not be greater than 3650.
• A branch that is not the last step
• A condition_type other than audience_matches or audience_not_matches
• An arm segment_uuid that is not a segment on your account
• A branch inside an arm
• A chain with no send_email step

Branch Object

Arms are checked in array order. The first arm whose condition matches runs, and the others are skipped. A contact who matches no arm ends the run after the branch.

Each arm has its own segment_uuid. Arms may use the same segment or different segments. An arm has no uuid.

Field	Type	Description
condition_type	string	audience_matches — the contact is in segment_uuid. audience_not_matches — the contact is not in segment_uuid.
segment_uuid	string|null	Segment this arm checks. Must be a segment on your account when you send it. null when that segment no longer exists — the automation still returns, with the rest of the tree.
name	string|null	Arm label, up to 255 characters. null when unset.
steps	array	Delay and send-email steps for this arm, in send order. Same fields as a top-level timer or send_email.

Statuses

Status	Meaning
draft	Saved. Not enrolling contacts.
active	Enrolling contacts that match the trigger.
paused	Not enrolling. Contacts already in progress stay where they are and continue when the automation is activated again, except contacts canceled by an edit — see Update Automation.

Structure

structure is on every automation, including each item from List Automations.

Value	Meaning
linear	A chain of timer and send_email steps. steps is that chain. Every step has branches set to null.
branched	The automation contains a branch. When the chain ends in an audience branch, steps is that chain and the last step is branch. When the steps cannot be represented here, steps is null.

steps [] is an automation with no steps. Which automations can be updated is under Editing.

Editing

Update Automation applies to a draft or paused automation whose steps is a chain, or a chain that ends in an audience branch, including []. An active automation returns 409 AUTOMATION_NOT_EDITABLE. An automation whose steps is null returns 409 AUTOMATION_NOT_LINEAR, including a request that only changes the name. Replacing the steps of a paused automation can cancel contacts waiting in a delay step — see Update Automation.

Delete Automation applies in any status. Activate Automation sets status to active. Pause Automation applies only while status is active.

Email body

content on a send_email step is Markdown, the same subset as a campaign body. Markdown that converts to an invalid document returns 422 VALIDATION_ERROR on that step's content, including steps.N.branches.M.steps.K.content. So does Markdown that is too long once formatted, even within the 65000-character limit, with The content is too long once formatted.

content_editable_via_api is false when the body uses layout Markdown cannot keep, and the returned content is then a lossy approximation. content_overwrite_required is true when the body carries formatting Markdown cannot keep. Replacing that body on update requires overwrite set to true, which discards the formatting. The check includes send-email steps inside an arm. Omitting steps leaves every email body as stored.

Both flags are null on a timer or branch step.