Tasks
Every command for tasks, the runs they make and the approvals those runs ask for, with worked examples.
How it fits together
A task is an instruction the assistant runs by itself, with a trigger that starts it and an autonomy that says how much it may change without asking. Each run leaves a record, and anything it may not do alone waits as an approval request. Reading needs tasks:read with threads:read and emails:read. Creating, changing, resuming, running and approving need tasks:write with threads:read, threads:write, emails:read, emails:send and labels:write, and the scopes of each toolkit.
openemail tasks create --name "Morning summary" --instruction "Tell me which conversations need a reply, most urgent first." --trigger-kind schedule --trigger-schedule-cadence daily --trigger-schedule-hour 8 --trigger-schedule-timezone Europe/Londonopenemail tasks run tsk_5c1e9a7b3d2f48e6a0b4c7d1openemail tasks get-run run_2b8d4f6a1c3e5079b6d8f0a2openemail tasks list-approvalsopenemail tasks approve apr_9f3a1c5e7b2d4608a1c3e5f7A trigger with many parts is easier as JSON: write the task to a file and pass it with --data @task.json. openemail tasks get <id> --json prints one in that shape.
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.
Tasks
| Command | What it does |
|---|---|
| openemail tasks list | One page of the tasks, most recently changed first. --status narrows it to active or paused |
| openemail tasks create --name <value> --instruction <value> --trigger-kind <kind> | Save a task and turn it on. --trigger-kind is schedule, mail or manual, --autonomy is ask, organize or reply, and --paused saves it without turning it on |
| openemail tasks get <id> | One task with its trigger, its settings and its last and next run |
| openemail tasks update <id> | Change what you pass and leave the rest. A new trigger replaces the old one whole |
| openemail tasks pause <id> | Stop a task from starting runs. A run already going carries on |
| openemail tasks resume <id> | Turn a paused task back on and clear its count of failed runs |
| openemail tasks run <id> | Start a run now, whatever the trigger, and print the run |
| openemail tasks delete <id> | Delete a task for good with every run it made, once you confirm |
Runs
| Command | What it does |
|---|---|
| openemail tasks list-runs | Runs across the workspace, newest first. --task-id and --status narrow it |
| openemail tasks get-run <id> | One run with every step it took, the tools it called and what it asked |
| openemail tasks start-run --instruction <value> | Hand the assistant one job to do in the background, with no task saved |
| openemail tasks cancel-run <id> | Stop a run that is queued, running or waiting, once you confirm. What it did stays done |
openemail tasks start-run --instruction "Find every invoice that arrived this month and label it Invoices." --autonomy organize --max-steps 30openemail tasks list-runs --status waitingopenemail tasks get-run run_2b8d4f6a1c3e5079b6d8f0a2 --jsonA run is queued, then running, then waiting while a request is open, and ends done, failed or cancelled. get-run --json prints the transcript, so a script can read it again until the status settles.
Approvals
| Command | What it does |
|---|---|
| openemail tasks list-approvals | What runs are waiting for you to allow, newest first. --task-id, --run-id and --status narrow it |
| openemail tasks get-approval <id> | One request with the tool and the exact arguments it would be called with |
| openemail tasks approve <id> | Let it happen, once you confirm. --subject and --body replace the words of a send or a reply |
| openemail tasks deny <id> | Refuse it, once you confirm. The run is told and carries on without it |
A request waits 7 days and then expires, which the run reads as a refusal. --yes skips the confirmation in a script.