Appearance
Automations
These tools list, read, create, change and delete email automations: flows that start when a subscriber gets a tag or enters a segment (the trigger) and then send one or more emails, each after its own delay.
For a step-by-step flow, use the Create an automation workflow.
Good to know
- Created switched off. A new automation, and every email in it, is switched off. Nothing is sent until you switch them on, in Rule or by explicitly asking the assistant.
- Delays count from the trigger, not from the previous email. A delay is set in minutes, hours or days.
- Custom delays (based on a date in the subscriber's data) can be read, but not created or changed with these tools.
- No copy. Rule offers no way to copy an automation through its API. To reuse content, copy its templates with
copy-email-template. - Deleting is permanent and needs your explicit confirmation. See
delete-automation. - Email only. SMS automations can appear in the list, but cannot be created or changed here.
- Every tool also takes the optional
account_id(see Accounts). It is left out of the tables below.
list-automations
Lists automations with their id, name, whether they are active, sendout type, trigger and dates.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Only automations whose name contains this text. |
active | boolean | No | true for active only, false for inactive only. Leave out for both. |
page | number | No | Page number, starting at 1. |
per_page | number | No | Automations per page, up to 100. Defaults to 100. |
- In an account with many automations, search by name with
queryrather than paging through all of them: Rule can skip an automation at a page boundary. - To see what an automation sent on a particular day, use
export-dispatchers.
Try asking: "List my active automations."
get-automation
Shows one automation in full: its settings and every email in it, with its subject, sender, delay, whether it is switched on, and its content.
| Parameter | Type | Required | Description |
|---|---|---|---|
automation_id | number | Yes | The automation's id. |
- A delay is shown in seconds (
type: "delay"), or astype: "custom"for a delay set up with conditions in Rule. - Emails made in Rule's older email editor show no content.
- An automation with no emails yet has an empty list. That is normal.
Try asking: "Show me the emails in my Welcome automation and when each one is sent."
create-automation
Creates an automation together with its emails, in one step.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Automation name. |
sendout_type | marketing or transactional | No | Defaults to marketing. |
trigger | object | No | { type: "tag" or "segment", id }: what starts the automation. Without a trigger, it cannot be switched on. |
finish_tags | array | No | Tags to add when a subscriber finishes the automation, as { id }, or { id, detach: true } to remove the tag instead. |
active | boolean | No | Switch the automation on once everything is created. Defaults to false. |
messages | array | No | The emails, in sending order. See below. |
Each email in messages:
| Field | Type | Required | Description |
|---|---|---|---|
template | object | Yes | The content. See below. |
delay | object | No | { amount, unit } with unit of minutes, hours or days, counted from the trigger. Leave out to send immediately. |
subject | string | No | Subject line. |
pre_header | string | No | Preview text. |
sender | object | No | { name, email, phone_number }. |
active | boolean | No | Switch this email on. Defaults to false. |
utm_campaign, utm_term | string | No | Tracking values added to links. |
The content of each email (template) can be:
| Mode | You give | What happens |
|---|---|---|
inline | content (the email as RCML), optional name and brand_style_id | A new template is created and styled with the brand style (the account's default if none is given). |
copy | template_id | An existing template is copied. The original is not changed. |
attach | template_id | An existing template that was made for this email is used as it is. |
- The trigger and finish tags must already exist; otherwise nothing is created.
- The tool does not check for an unsubscribe link. Marketing emails need one.
- If a step fails half-way, nothing is undone: the answer shows what was created and which step failed. Do not run
create-automationagain, as that creates a second automation. Add the missing emails withupdate-automationinstead.
Try asking: "Create a welcome automation triggered by the 'New subscriber' tag, with one email right away and one three days later."
update-automation
Changes an automation and its emails. Only what you mention is changed.
| Parameter | Type | Required | Description |
|---|---|---|---|
automation_id | number | Yes | The automation's id. |
name | string | No | New name. |
sendout_type | marketing or transactional | No | New sendout type. |
trigger | object | No | A new trigger, { type: "tag" or "segment", id }. A trigger can be replaced, not removed. |
finish_tags | array | No | Replaces all finish tags; [] removes them. |
active | boolean | No | Switch the automation on or off. Switching on needs a trigger. See the warning below. |
message_updates | array | No | Changes to existing emails: each with message_id and any of subject, pre_header, sender, delay, active, utm_campaign, utm_term. |
add_messages | array | No | New emails, in the same shape as messages in create-automation. They are added switched off. |
- An automation without a trigger can only be renamed or changed if you also give it a trigger in the same request. Its emails can be changed either way.
- An email with a custom delay keeps it: its delay and on/off state cannot be changed here.
- A subject can be replaced, not removed.
- To replace an email's content, edit its template with
update-email-template. - Changes to an active automation take effect immediately for subscribers already in the flow. The assistant tells you before making them.
Switching an automation off cancels its scheduled emails
When an active automation is switched off, every email it has scheduled but not yet sent is cancelled, for everyone part-way through it. Switching it on again does not bring them back. The assistant only switches an active automation off after explaining this and getting your explicit OK, and never just to make an edit.
Try asking: "In my Welcome automation, change the subject of the second email to 'A little something for you' and add a third email after 7 days."
delete-automation
Permanently deletes an automation together with its emails, their variants (dynamic sets) and the templates of those variants.
| Parameter | Type | Required | Description |
|---|---|---|---|
automation_id | number | Yes | The automation's id. |
confirm | true | Yes | Must be true. The assistant asks you first. |
confirm_active | true | Only if the automation is active | A second confirmation, needed in addition to confirm when the automation is switched on. Without it nothing is deleted. |
- This cannot be undone. The assistant tells you what is about to be lost before it deletes anything, and tells you afterwards that the templates were deleted too.
- An active automation is switched off first. Rule allows deleting a live automation, so the tool asks for the second confirmation (
confirm_active) and stops without deleting anything if it is missing. With both, it switches the automation off before deleting anything, which cancels the emails it had scheduled but not yet sent (see the warning underupdate-automation). - If a step fails, nothing is rolled back. The answer lists what was already removed, and says so if the automation was switched off, because it stays off. The assistant asks you again before retrying, which removes the rest.
- There is no tool that copies an automation, so a delete cannot be swapped for a copy.
Deleting an active automation cancels its scheduled emails
Subscribers part-way through the flow do not get the rest of it, and deleting cannot be reversed. The assistant only deletes an active automation after explaining this and getting your explicit OK.
Try asking: "Delete the automation 'Old welcome flow'."