---
title: "Tasks"
description: "`tasks->list`, `get`, `create`, `update`, `delete`, `pause`, `resume`, `run`, `listRuns`, `getRun`, `startRun`, `cancelRun`, `listApprovals`, `getApproval`, `approve` and `deny`."
url: "https://openemail.uk/docs/php/tasks"
area: "PHP"
category: "Mailbox"
---

# Tasks

`tasks->list`, `get`, `create`, `update`, `delete`, `pause`, `resume`, `run`, `listRuns`, `getRun`, `startRun`, `cancelRun`, `listApprovals`, `getApproval`, `approve` and `deny`.

## Every method

**tasks.php**

```
use OpenEmail\Constants\TaskAutonomies;
use OpenEmail\Constants\TaskCadences;
use OpenEmail\Constants\TaskRunStatuses;
use OpenEmail\Constants\TaskTriggerKinds;

$task = $client->tasks->create([
    'name' => 'Morning digest',
    'instruction' => 'Summarise what arrived since yesterday and email the summary to me.',
    'trigger' => [
        'kind' => TaskTriggerKinds::SCHEDULE,
        'schedule' => ['cadence' => TaskCadences::DAILY, 'hour' => 8, 'weekdays' => [1, 2, 3, 4, 5], 'timezone' => 'Europe/Berlin'],
    ],
    'autonomy' => TaskAutonomies::ORGANIZE,
]);

$queued = $client->tasks->run($task['id']);

foreach ($client->tasks->iterateApprovals(runId: $queued['id']) as $request) {
    echo $request['tool'], ': ', $request['summary'], PHP_EOL;

    if ($request['tool'] === 'replyToEmail') {
        $client->tasks->approve($request['id'], ['subject' => 'Your morning digest']);
    } else {
        $client->tasks->deny($request['id']);
    }
}

$run = $client->tasks->getRun($queued['id']);

foreach ($run['transcript'] as $step) {
    foreach ($step['calls'] as $call) {
        echo $step['at'], ' ', $call['tool'], $call['done'] ? ' done' : ' waiting', PHP_EOL;
    }
}

$job = $client->tasks->startRun([
    'instruction' => 'Find every invoice that arrived this month and label it Invoices.',
    'maxSteps' => 30,
]);

$failed = $client->tasks->listAllRuns(taskId: $task['id'], status: TaskRunStatuses::FAILED);

$client->tasks->cancelRun($job['id']);
$client->tasks->pause($task['id']);
$client->tasks->resume($task['id']);

echo $run['status'], ': ', $run['result'], ', ', count($failed), ' failed', PHP_EOL;
```

A task is an instruction in plain words with what starts it: a `schedule`, `mail` that arrives, or `manual` for only when asked. A run is one execution, and `startRun` starts one with no task saved. Read a run again with `getRun` until its `status` is `done`, `failed` or `cancelled`. Its `transcript` holds every step it took and the tools each step called.

`autonomy` says how much a run may do without asking: `ask`, `organize` or `reply`. Anything past that waits as an approval request for 7 days. `approve` lets the run go ahead, with `subject` and `body` to replace what it wrote in a send or a reply, and `deny` refuses it. The run carries on once every request of its step is answered.

Reading needs `tasks:read`, `threads:read` and `emails:read`. A task acts with what its caller holds, so `create`, `update`, `resume`, `run`, `startRun` and `approve` need `tasks:write`, `threads:read`, `threads:write`, `emails:read`, `emails:send` and `labels:write`, and the scopes of every toolkit the task names. `delete`, `pause`, `cancelRun` and `deny` need `tasks:write` alone.

A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with 422 `capability_unsupported`.

A task whose `toolkits` hold `connectors` may use the apps connected for the workspace, never a connector that belongs to one person, and it then also needs `connectors:read` and `connectors:use`. Such a run reads through a connector alone, every change in an app waits as an approval request whatever the `autonomy`, and with `reply` every answer to an email waits for approval as well.