---
title: "Tasks"
description: "`tasks.list`, `get`, `create`, `update`, `delete`, `pause`, `resume`, `run`, `list_runs`, `get_run`, `start_run`, `cancel_run`, `list_approvals`, `get_approval`, `approve` and `deny`."
url: "https://openemail.uk/docs/python/tasks"
area: "Python"
category: "Mailbox"
---

# Tasks

`tasks.list`, `get`, `create`, `update`, `delete`, `pause`, `resume`, `run`, `list_runs`, `get_run`, `start_run`, `cancel_run`, `list_approvals`, `get_approval`, `approve` and `deny`.

## Every method

**tasks.py**

```
from openemail import openemail

task = openemail.tasks.create({
    'name': 'Morning digest',
    'instruction': 'Summarise what arrived since yesterday and email the summary to me.',
    'trigger': {
        'kind': 'schedule',
        'schedule': {'cadence': 'daily', 'hour': 8, 'weekdays': [1, 2, 3, 4, 5], 'timezone': 'Europe/Berlin'},
    },
    'autonomy': 'organize',
})

queued = openemail.tasks.run(task['id'])

for request in openemail.tasks.iterate_approvals(run_id=queued['id']):
    print(request['tool'], request['summary'], request['args'])

    if request['tool'] == 'replyToEmail':
        openemail.tasks.approve(request['id'], {'subject': 'Your morning digest'})
    else:
        openemail.tasks.deny(request['id'])

run = openemail.tasks.get_run(queued['id'])

for step in run['transcript']:
    for call in step['calls']:
        print(step['at'], call['tool'], call['done'])

job = openemail.tasks.start_run({
    'instruction': 'Find every invoice that arrived this month and label it Invoices.',
    'maxSteps': 30,
})

failed = openemail.tasks.list_all_runs(task_id=task['id'], status='failed')

openemail.tasks.cancel_run(job['id'])
openemail.tasks.pause(task['id'])
openemail.tasks.resume(task['id'])

print(run['status'], run['result'], len(failed))
```

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 `start_run` starts one with no task saved. Read a run again with `get_run` 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`, `start_run` 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`, `cancel_run` 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.

## Reference

- [`tasks.list()`](https://openemail.uk/docs/python/reference/tasks#list): full reference
- [`tasks.list_all()`](https://openemail.uk/docs/python/reference/tasks#listAll): full reference
- [`tasks.iterate()`](https://openemail.uk/docs/python/reference/tasks#iterate): full reference
- [`tasks.get()`](https://openemail.uk/docs/python/reference/tasks#get): full reference
- [`tasks.create()`](https://openemail.uk/docs/python/reference/tasks#create): full reference
- [`tasks.update()`](https://openemail.uk/docs/python/reference/tasks#update): full reference
- [`tasks.delete()`](https://openemail.uk/docs/python/reference/tasks#delete): full reference
- [`tasks.pause()`](https://openemail.uk/docs/python/reference/tasks#pause): full reference
- [`tasks.resume()`](https://openemail.uk/docs/python/reference/tasks#resume): full reference
- [`tasks.run()`](https://openemail.uk/docs/python/reference/tasks#run): full reference
- [`tasks.list_runs()`](https://openemail.uk/docs/python/reference/tasks#listRuns): full reference
- [`tasks.list_all_runs()`](https://openemail.uk/docs/python/reference/tasks#listAllRuns): full reference
- [`tasks.iterate_runs()`](https://openemail.uk/docs/python/reference/tasks#iterateRuns): full reference
- [`tasks.get_run()`](https://openemail.uk/docs/python/reference/tasks#getRun): full reference
- [`tasks.start_run()`](https://openemail.uk/docs/python/reference/tasks#startRun): full reference
- [`tasks.cancel_run()`](https://openemail.uk/docs/python/reference/tasks#cancelRun): full reference
- [`tasks.list_approvals()`](https://openemail.uk/docs/python/reference/tasks#listApprovals): full reference
- [`tasks.list_all_approvals()`](https://openemail.uk/docs/python/reference/tasks#listAllApprovals): full reference
- [`tasks.iterate_approvals()`](https://openemail.uk/docs/python/reference/tasks#iterateApprovals): full reference
- [`tasks.get_approval()`](https://openemail.uk/docs/python/reference/tasks#getApproval): full reference
- [`tasks.approve()`](https://openemail.uk/docs/python/reference/tasks#approve): full reference
- [`tasks.deny()`](https://openemail.uk/docs/python/reference/tasks#deny): full reference