---
title: "Automations"
description: "`automations.list`, `get`, `create`, `update`, `publish`, `pause`, `resume`, `archive`, `duplicate`, `delete`, `send_test`, `stats`, `list_versions`, `restore_version`, `list_starters`, `list_enrollments`, `get_enrollment`, `enroll` and `exit_enrollment`, with `events.send`, `send_batch` and `list_names`."
url: "https://openemail.uk/docs/ruby/automations"
area: "Ruby"
category: "Mailbox"
---

# Automations

`automations.list`, `get`, `create`, `update`, `publish`, `pause`, `resume`, `archive`, `duplicate`, `delete`, `send_test`, `stats`, `list_versions`, `restore_version`, `list_starters`, `list_enrollments`, `get_enrollment`, `enroll` and `exit_enrollment`, with `events.send`, `send_batch` and `list_names`.

## Every method

**automations.rb**

```
automation = client.automations.create(
  name: "Welcome series",
  starter: "welcome-series",
  settings: {timezone: "Europe/London"}
)

trigger = {kind: "event", eventName: "trial.started", filters: []}
saved = client.automations.update(
  automation[:id],
  definition: automation[:definition].to_h.merge(trigger: trigger),
  expectedUpdatedAt: automation[:updatedAt]
)

blocking = saved[:problems].to_a.find { |problem| problem[:blocking] }
raise blocking[:message] if blocking

client.automations.send_test(saved[:id], stepKey: saved.dig(:definition, :entry))
live = client.automations.publish(saved[:id])

sent = client.events.send(
  name: "trial.started",
  email: "ann@example.com",
  properties: {plan: "starter"},
  createContact: true,
  idempotency_key: "trial:ann@example.com"
)

client.automations.iterate_enrollments(live[:id], status: "active") do |enrollment|
  puts "#{enrollment.dig(:contact, :email)} #{enrollment[:heldFor]}" if enrollment[:heldFor]
end

stats = client.automations.stats(live[:id])
history = client.contacts.list_events("ann@example.com", name: "trial.started")

client.automations.pause(live[:id])
client.automations.resume(live[:id])

puts sent[:enrolled], stats.dig(:totals, :entered), history.items.size
```

An automation keeps a draft `definition` and the `published` version that runs. `update` changes the draft and the settings, and `publish` freezes the draft as the next version and turns the automation on. `problems` says what still stops a draft from being published, and `expectedUpdatedAt` refuses a save that would overwrite someone else’s with 409 `version_conflict`.

Reading needs `automations:read` and changing needs `automations:write`. `publish`, `resume` and `send_test` also need `emails:send`. `events.send` and `events.send_batch` need `contacts:write`, and `contacts.list_events` needs `contacts:read`. `delete` asks an OAuth access token for a verification code, and an API key never.

`events.send_batch` takes up to 100 events and never raises for one bad event: the answer lists `accepted` and `failed`, each with the `index` of the event in the list you sent.

`attributes` on a contact holds its custom fields, and an automation reads one as `attributes.<key>`.