Skip to content

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.

ParameterTypeRequiredDescription
querystringNoOnly automations whose name contains this text.
activebooleanNotrue for active only, false for inactive only. Leave out for both.
pagenumberNoPage number, starting at 1.
per_pagenumberNoAutomations per page, up to 100. Defaults to 100.
  • In an account with many automations, search by name with query rather 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.

ParameterTypeRequiredDescription
automation_idnumberYesThe automation's id.
  • A delay is shown in seconds (type: "delay"), or as type: "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.

ParameterTypeRequiredDescription
namestringYesAutomation name.
sendout_typemarketing or transactionalNoDefaults to marketing.
triggerobjectNo{ type: "tag" or "segment", id }: what starts the automation. Without a trigger, it cannot be switched on.
finish_tagsarrayNoTags to add when a subscriber finishes the automation, as { id }, or { id, detach: true } to remove the tag instead.
activebooleanNoSwitch the automation on once everything is created. Defaults to false.
messagesarrayNoThe emails, in sending order. See below.

Each email in messages:

FieldTypeRequiredDescription
templateobjectYesThe content. See below.
delayobjectNo{ amount, unit } with unit of minutes, hours or days, counted from the trigger. Leave out to send immediately.
subjectstringNoSubject line.
pre_headerstringNoPreview text.
senderobjectNo{ name, email, phone_number }.
activebooleanNoSwitch this email on. Defaults to false.
utm_campaign, utm_termstringNoTracking values added to links.

The content of each email (template) can be:

ModeYou giveWhat happens
inlinecontent (the email as RCML), optional name and brand_style_idA new template is created and styled with the brand style (the account's default if none is given).
copytemplate_idAn existing template is copied. The original is not changed.
attachtemplate_idAn 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-automation again, as that creates a second automation. Add the missing emails with update-automation instead.

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.

ParameterTypeRequiredDescription
automation_idnumberYesThe automation's id.
namestringNoNew name.
sendout_typemarketing or transactionalNoNew sendout type.
triggerobjectNoA new trigger, { type: "tag" or "segment", id }. A trigger can be replaced, not removed.
finish_tagsarrayNoReplaces all finish tags; [] removes them.
activebooleanNoSwitch the automation on or off. Switching on needs a trigger. See the warning below.
message_updatesarrayNoChanges to existing emails: each with message_id and any of subject, pre_header, sender, delay, active, utm_campaign, utm_term.
add_messagesarrayNoNew 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.

ParameterTypeRequiredDescription
automation_idnumberYesThe automation's id.
confirmtrueYesMust be true. The assistant asks you first.
confirm_activetrueOnly if the automation is activeA 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 under update-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'."