---
title: "Automations"
description: "`automations->list`, `get`, `create`, `update`, `publish`, `pause`, `resume`, `archive`, `duplicate`, `delete`, `sendTest`, `stats`, `listVersions`, `restoreVersion`, `listStarters`, `listEnrollments`, `getEnrollment`, `enroll` and `exitEnrollment`, with `events->send`, `sendBatch` and `listNames`."
url: "https://openemail.uk/docs/php/automations"
area: "PHP"
category: "Mailbox"
---

# Automations

`automations->list`, `get`, `create`, `update`, `publish`, `pause`, `resume`, `archive`, `duplicate`, `delete`, `sendTest`, `stats`, `listVersions`, `restoreVersion`, `listStarters`, `listEnrollments`, `getEnrollment`, `enroll` and `exitEnrollment`, with `events->send`, `sendBatch` and `listNames`.

## Every method

**automations.php**

```
use OpenEmail\Constants\AutomationEnrollmentStatuses;
use OpenEmail\Constants\AutomationTriggerKinds;

$automation = $client->automations->create([
    'name' => 'Welcome series',
    'starter' => 'welcome-series',
    'settings' => ['timezone' => 'Europe/London'],
]);

$definition = $automation['definition'];
$definition['trigger'] = ['kind' => AutomationTriggerKinds::EVENT, 'eventName' => 'trial.started', 'filters' => []];

$saved = $client->automations->update($automation['id'], [
    'definition' => $definition,
    'expectedUpdatedAt' => $automation['updatedAt'],
]);

foreach ($saved['problems'] as $problem) {
    if ($problem['blocking']) {
        throw new \RuntimeException($problem['message']);
    }
}

$client->automations->sendTest($saved['id'], ['stepKey' => $saved['definition']['entry'] ?? '']);
$live = $client->automations->publish($saved['id']);

$sent = $client->events->send([
    'name' => 'trial.started',
    'email' => 'ann@example.com',
    'properties' => ['plan' => 'starter'],
    'createContact' => true,
], idempotencyKey: 'trial:ann@example.com');

foreach ($client->automations->iterateEnrollments($live['id'], status: AutomationEnrollmentStatuses::ACTIVE) as $enrollment) {
    if ($enrollment['heldFor'] !== null) {
        echo $enrollment['contact']['email'], ' ', $enrollment['heldFor'], PHP_EOL;
    }
}

$stats = $client->automations->stats($live['id']);
$history = $client->contacts->listEvents('ann@example.com', name: 'trial.started');

$client->automations->pause($live['id']);
$client->automations->resume($live['id']);

echo count($sent['enrolled']), ' ', $stats['totals']['entered'], ' ', count($history->items), PHP_EOL;
```

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 `sendTest` also need `emails:send`. `events->send` and `events->sendBatch` need `contacts:write`, and `contacts->listEvents` needs `contacts:read`. `delete` asks an OAuth access token for a verification code, and an API key never.

`events->sendBatch` takes up to 100 events and never throws for one bad event: the answer lists `accepted` and `failed`, each with the `index` of the event in the array you sent.

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