---
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/ruby/tasks"
area: "Ruby"
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.rb**

```
task = client.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 = client.tasks.run(task[:id])

client.tasks.iterate_approvals(run_id: queued[:id]) do |request|
  puts "#{request[:tool]} #{request[:summary]}"

  if request[:tool] == "replyToEmail"
    client.tasks.approve(request[:id], subject: "Your morning digest")
  else
    client.tasks.deny(request[:id])
  end
end

run = client.tasks.get_run(queued[:id])

run[:transcript].to_a.each do |step|
  step[:calls].to_a.each { |call| puts "#{step[:at]} #{call[:tool]} #{call[:done]}" }
end

job = client.tasks.start_run(
  instruction: "Find every invoice that arrived this month and label it Invoices.",
  maxSteps: 30
)

failed = client.tasks.list_all_runs(task_id: task[:id], status: "failed")

client.tasks.cancel_run(job[:id])
client.tasks.pause(task[:id])
client.tasks.resume(task[:id])

puts run[:status], run[:result], failed.size
```

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.