Python

openemail.tasks

Every method in this namespace: its signature, its parameters, what it returns and an example.

Methods

Instructions the assistant runs by itself, on a schedule, when mail arrives or when asked: create a task, change, pause, resume and delete it, run it now, hand the assistant a one-off job, follow each run step by step, and approve or deny what a run asks before it acts.

`tasks.list()`

List the tasks of the workspace, a page at a time

tasks:readthreads:reademails:readPages through results

Signature

def list(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[TaskResource]

Returns one page of tasks, the most recently changed first. list_all collects every page and iterate walks them lazily. A task is an instruction in plain words that the assistant runs by itself: on a schedule, when mail arrives, or only when asked. Each one says what starts it in trigger, how much it may do without asking in autonomy, when it runs next in nextRunAt, how its last run ended in lastRunStatus and how many approval requests wait for an answer in pendingApprovals.

Give status= to read only the tasks that are active or only the ones that are paused. pausedReason says why a paused task stopped: user when somebody paused it, failures after 5 failed runs in a row, and plan_limit when the plan no longer covers it.

Parameters

limitint: Page size, from 1 to 100. The server defaults to 25.
cursorstr: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
statusTaskStatus: Only tasks in this state: active or paused. Left out, both are listed.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Page[TaskResource], a dict with items, hasMore and nextCursor. Each item has id, name, instruction, status, pausedReason, trigger, autonomy, toolkits, model, notify, maxRunsPerDay, maxSteps, nextRunAt, heldUntil, lastRunAt, lastRunStatus, runCount, pendingApprovals, chatId, createdAt and updatedAt.

Example

from openemail import openemail page = openemail.tasks.list(status='active') for task in page['items']:    print(task['name'], task['trigger']['kind'], task['nextRunAt'], task['pendingApprovals'])

Notes

Reading tasks needs threads:read and emails:read beside tasks:read.
A task works across every address of the workspace. A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
The order follows updatedAt, which moves when a task changes or starts a run. A workspace holds at most 100 tasks, so limit=100 reads them all in one request and no task can move between pages.

Also available in

API: GET /tasks
TypeScript: tasks.list()
Ruby: tasks.list
PHP: tasks->list
Go: Tasks.List
Java: tasks().list
C#: Tasks.ListAsync
CLI: openemail tasks list

`tasks.list_all()`

Collect every task into one list

tasks:readthreads:reademails:readPages through results

Signature

def list_all(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[TaskResource]

Walks every page of list and returns all tasks, the most recently changed first. One request per page. Give status= to collect only the active tasks or only the paused ones.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
statusTaskStatus: Only tasks in this state: active or paused. Left out, both are collected.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[TaskResource] holding every task.

Example

from openemail import openemail tasks = openemail.tasks.list_all(limit=100) waiting = [task for task in tasks if task['pendingApprovals'] > 0] for task in waiting:    print(task['name'], task['pendingApprovals'])

Notes

If any page fails, the call raises and the tasks already fetched are discarded.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /tasks
TypeScript: tasks.listAll()
Ruby: tasks.list_all
PHP: tasks->listAll
Go: Tasks.ListAll
Java: tasks().listAll
C#: Tasks.ListAllAsync

`tasks.iterate()`

Stream the tasks one at a time

tasks:readthreads:reademails:readPages through results

Signature

def iterate(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[TaskResource]

Returns a generator that yields tasks individually, the most recently changed first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
statusTaskStatus: Only tasks in this state: active or paused. Left out, both are walked.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Iterator[TaskResource], a generator yielding one task per step.

Example

from openemail import openemail for task in openemail.tasks.iterate(status='paused'):    print(task['name'], 'was paused by', task['pausedReason'])

Notes

The generator is lazy, so an abandoned loop costs only the pages you consumed.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /tasks
TypeScript: tasks.iterate()
Ruby: tasks.iterate
PHP: tasks->iterate
Go: Tasks.Iterate
Java: tasks().iterate
C#: Tasks.IterateAsync

`tasks.get()`

Read one task by id

tasks:readthreads:reademails:read

Signature

def get(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskResource

Looks up a single task and returns it in the same shape as a row of list: its instruction, its trigger with the schedule or the mail filter, how much it may do alone, its toolkits and limits, when it runs next and how the last run ended.

nextRunAt is set for an active schedule task and None for the other kinds and while paused. heldUntil is set when the workspace ran out of AI actions for the day: the task starts nothing until then. pendingApprovals counts the approval requests of its runs that still wait for an answer.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskResource with id, name, instruction, status, pausedReason, trigger, autonomy, toolkits, model, notify, maxRunsPerDay, maxSteps, nextRunAt, heldUntil, lastRunAt, lastRunStatus, runCount, pendingApprovals, chatId, createdAt and updatedAt.

Example

from openemail import openemail task = openemail.tasks.get('tsk_5c1e9a7b3d2f48e6a0b4c7d1') print(task['name'], task['status'], task['trigger']['kind'], task['nextRunAt'])

Notes

A missing task raises OpenEmailApiError with is_not_found set to True and code task_not_found.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /tasks/{id}
TypeScript: tasks.get()
Ruby: tasks.get
PHP: tasks->get
Go: Tasks.Get
Java: tasks().get
C#: Tasks.GetAsync
CLI: openemail tasks get

`tasks.create()`

Save a task for the assistant to run by itself

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def create(    body: TaskCreate,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskResource

Saves an instruction for the assistant with what starts it and how much it may do alone, and returns the task as it is stored. instruction says what to do in plain words, as you would tell a person. It is the only instruction a run follows: text inside emails is read, never obeyed.

trigger.kind says what starts a run. A schedule task needs trigger.schedule and gets its first run time at once, in nextRunAt. A mail task starts with the next message that reaches an inbox and matches trigger.mail, or with every message when no filter is sent. Mail from an address of the workspace itself never starts one. A manual task waits for run.

autonomy limits what a run does without asking. ask sends every change to a person to approve. organize, the default, lets the run label, archive, bin, snooze, draft, take notes and keep contacts by itself, and email the addresses of the workspace. reply also lets it answer an email without asking, as long as it adds no recipients. Anything else waits as an approval request, which list_approvals reads. A run never reaches billing, members, roles, domains, rules, keys or webhooks.

A task acts with what its caller holds, so the call needs more than tasks:write: threads:read, threads:write, emails:read, emails:send and labels:write, and the read and write scopes of every toolkit the task names.

Parameters

body['name']strRequired: What the task is called in the app, trimmed, 1 to 120 characters.
body['instruction']strRequired: What the assistant should do, in plain words, trimmed, 1 to 8,000 characters.
body['trigger']['kind']TaskTriggerKindRequired: schedule runs on a clock, mail runs when a message arrives, and manual runs only when started with run.
body['trigger']['schedule']['cadence']TaskCadenceRequired: Needed for a schedule task and ignored for the other kinds. hourly runs every everyHours hours at minute, daily runs at hour:minute on each of weekdays, and monthly runs at hour:minute on monthDay.
body['trigger']['schedule']['everyHours']int: For hourly: how many hours lie between runs, from 1 to 12, counted from midnight in the time zone. Defaults to 1.
body['trigger']['schedule']['hour']int: The hour of the day, 0 to 23, in the time zone of the schedule. Defaults to 8.
body['trigger']['schedule']['minute']int: The minute of the hour, 0 to 59. Defaults to 0.
body['trigger']['schedule']['weekdays']list[int]: For daily: the days it runs, 0 for Sunday to 6 for Saturday. Left out, it runs every day.
body['trigger']['schedule']['monthDay']int: For monthly: the day of the month, 1 to 28. Defaults to 1.
body['trigger']['schedule']['timezone']str: An IANA time zone such as Europe/Berlin. The schedule follows its clock changes. Defaults to UTC.
body['trigger']['mail']['addresses']list[str]: For a mail task: start only for mail delivered to one of these addresses of the workspace, at most 25. Left out or empty, every address counts.
body['trigger']['mail']['fromContains']str | None: For a mail task: start only when the sender address contains this text, whatever the case, up to 200 characters.
body['trigger']['mail']['subjectContains']str | None: For a mail task: start only when the subject contains this text, whatever the case, up to 200 characters.
body['autonomy']TaskAutonomy: How much a run may do without asking: ask, organize or reply. Defaults to organize.
body['toolkits']list[TaskToolkit]: Extra groups of tools a run may use beyond reading and organising mail: contacts, audiences, templates, tracking, translate, files, notes, drafts, sent, insights, subscriptions, calendar, knowledge and web. Left out, drafts, notes and knowledge. An empty list gives it none.
body['model']TaskModel: standard is the everyday model. advanced reasons better over long jobs and costs ten AI actions where the standard one costs one. Defaults to standard.
body['notify']TaskNotifyMode: attention notifies the workspace owner when a run waits for approval or fails, always also when it finishes, and never stays silent. Defaults to attention.
body['maxRunsPerDay']int: The most runs the task may start in any 24 hours, however often its trigger fires, from 1 to 500. Defaults to 50.
body['maxSteps']int: The most model steps one run may take before it has to write its report, from 1 to 60. Defaults to 20.
body['paused']bool: True creates the task paused, so it does not run until resume. A paused task does not count against the active tasks of the plan.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskResource with the new id, status active, or paused when you asked for that, the trigger as it is stored with every default filled in, and nextRunAt set for a schedule.

Example

from openemail import openemail task = openemail.tasks.create(    {        'name': 'Label invoices',        'instruction': 'When an invoice arrives, label it Invoices and add a note with the amount and the due date.',        'trigger': {'kind': 'mail', 'mail': {'subjectContains': 'invoice'}},        'autonomy': 'organize',    }) print(task['id'], task['status'], task['trigger']['kind'])

Notes

Each toolkit brings its own scopes: contacts needs contacts:read and contacts:write, audiences needs audiences:read, audiences:write and contacts:read, and templates, files, drafts, calendar and knowledge need their read and write scope. The default toolkits therefore need drafts:read, drafts:write, knowledge:read and knowledge:write. A missing scope is a 403 insufficient_scope.
A workspace runs 1 active task on Free, 5 on Starter and 25 on Business, with no cap on Enterprise, and holds at most 100 tasks, paused ones included. One more active task than the plan covers is a 403 task_active_limit_reached, and a task past the 100 a 403 task_limit_reached.
A schedule trigger without its schedule, a time zone that is not known and a toolkit a task may not use are 422 invalid_task. A value of the wrong type or length is 422 invalid_parameter with param naming it, and a key the body does not take is 422 unknown_parameter.
A task works across every address of the workspace. A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Not retried automatically, and nothing deduplicates by name, so a retry after a lost response can leave two tasks. List them and delete the spare.

Also available in

API: POST /tasks
TypeScript: tasks.create()
Ruby: tasks.create
PHP: tasks->create
Go: Tasks.Create
Java: tasks().create
C#: Tasks.CreateAsync
CLI: openemail tasks create

`tasks.update()`

Change what a task does, what starts it or how much it may do alone

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def update(    id: str,    patch: TaskPatch,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskResource

Changes a task and returns it as it is stored. Send only what changes: a field left out stays as it is, and a patch with nothing in it is a 422.

A new trigger replaces the old one whole. Send its kind and, for a schedule, the whole schedule again, because what the new trigger leaves out goes back to its default, not to what the task had. A schedule change moves nextRunAt of an active task.

Runs already started keep the settings they began with, and later runs follow the new ones. It neither pauses nor resumes a task: pause and resume do that. Like create, the call needs the scopes the task acts with, counted from the toolkits it has after the change.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
patch['name']str: New name, trimmed, 1 to 120 characters. Left out, the name stays.
patch['instruction']str: New instruction in plain words, trimmed, 1 to 8,000 characters. Left out, the instruction stays.
patch['trigger']['kind']TaskTriggerKindRequired: Needed whenever any part of trigger is sent: schedule, mail or manual.
patch['trigger']['schedule']['cadence']TaskCadenceRequired: Needed for a schedule trigger: hourly, daily or monthly.
patch['trigger']['schedule']['everyHours']int: For hourly: how many hours lie between runs, from 1 to 12, counted from midnight in the time zone. Defaults to 1.
patch['trigger']['schedule']['hour']int: The hour of the day, 0 to 23, in the time zone of the schedule. Defaults to 8.
patch['trigger']['schedule']['minute']int: The minute of the hour, 0 to 59. Defaults to 0.
patch['trigger']['schedule']['weekdays']list[int]: For daily: the days it runs, 0 for Sunday to 6 for Saturday. Left out, it runs every day.
patch['trigger']['schedule']['monthDay']int: For monthly: the day of the month, 1 to 28. Defaults to 1.
patch['trigger']['schedule']['timezone']str: An IANA time zone such as Europe/Berlin. Defaults to UTC.
patch['trigger']['mail']['addresses']list[str]: For a mail trigger: start only for mail delivered to one of these addresses of the workspace, at most 25. Left out or empty, every address counts.
patch['trigger']['mail']['fromContains']str | None: For a mail trigger: start only when the sender address contains this text, whatever the case, up to 200 characters.
patch['trigger']['mail']['subjectContains']str | None: For a mail trigger: start only when the subject contains this text, whatever the case, up to 200 characters.
patch['autonomy']TaskAutonomy: How much a run may do without asking: ask, organize or reply. Left out, it stays.
patch['toolkits']list[TaskToolkit]: The toolkits a run may use from now on, replacing the list the task had. An empty list gives it none. Left out, they stay.
patch['model']TaskModel: standard or advanced, which costs ten AI actions where the standard one costs one. Left out, it stays.
patch['notify']TaskNotifyMode: When the workspace owner is notified: attention, always or never. Left out, it stays.
patch['maxRunsPerDay']int: The most runs the task may start in any 24 hours, from 1 to 500. Left out, it stays.
patch['maxSteps']int: The most model steps one run may take, from 1 to 60. Left out, it stays.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskResource with the unchanged id and status, and everything else as it is now.

Example

from openemail import openemail task = openemail.tasks.update(    'tsk_5c1e9a7b3d2f48e6a0b4c7d1',    {        'trigger': {            'kind': 'schedule',            'schedule': {                'cadence': 'daily',                'hour': 8,                'weekdays': [1, 2, 3, 4, 5],                'timezone': 'Europe/Berlin',            },        }    },) print(task['trigger']['schedule'], task['nextRunAt'])

Notes

A missing task is a 404 task_not_found. An empty patch or a value of the wrong type or length is 422 invalid_parameter, a key the patch does not take 422 unknown_parameter, and a trigger without its schedule, a time zone that is not known or a toolkit a task may not use 422 invalid_task.
The key or app needs the read and write scopes of every toolkit the task has after the change, or the call is a 403 insufficient_scope.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
The SDK retries this call after a network failure, since the same patch sent twice leaves the same task.

Also available in

API: PATCH /tasks/{id}
TypeScript: tasks.update()
Ruby: tasks.update
PHP: tasks->update
Go: Tasks.Update
Java: tasks().update
C#: Tasks.UpdateAsync
CLI: openemail tasks update

`tasks.delete()`

Delete a task with every run it made

tasks:write

Signature

def delete(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> DeletedTaskResource

Deletes a task for good, with every run it made and their records. A run in flight is stopped and its open approval requests are closed. What the runs already did in the mailbox stays done.

There is no undo. To stop a task and keep its history, use pause.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

DeletedTaskResource, a dict with object set to task, the id and deleted set to True.

Example

from openemail import openemail removed = openemail.tasks.delete('tsk_5c1e9a7b3d2f48e6a0b4c7d1') print(removed['id'], removed['deleted'])

Notes

The SDK does not retry a delete. A 404 task_not_found on your own second attempt after a lost response means the first one worked.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: DELETE /tasks/{id}
TypeScript: tasks.delete()
Ruby: tasks.delete
PHP: tasks->delete
Go: Tasks.Delete
Java: tasks().delete
C#: Tasks.DeleteAsync
CLI: openemail tasks delete

`tasks.pause()`

Stop a task from starting new runs

tasks:write

Signature

def pause(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskResource

Stops a task from starting new runs: its schedule no longer fires and arriving mail no longer starts it. A run already going carries on, and its approval requests can still be answered. run still starts a paused task by hand. Pausing a paused task leaves it paused. It takes no body.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskResource with status paused, pausedReason user and nextRunAt None.

Example

from openemail import openemail task = openemail.tasks.pause('tsk_5c1e9a7b3d2f48e6a0b4c7d1') print(task['status'], task['pausedReason'])

Notes

A missing task is a 404 task_not_found.
To stop a run that is already going, use cancel_run.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Retried automatically on network failure and retryable statuses, since pausing twice leaves the same paused task.

Also available in

API: POST /tasks/{id}/pause
TypeScript: tasks.pause()
Ruby: tasks.pause
PHP: tasks->pause
Go: Tasks.Pause
Java: tasks().pause
C#: Tasks.PauseAsync
CLI: openemail tasks pause

`tasks.resume()`

Turn a paused task back on

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def resume(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskResource

Turns a paused task back on, whoever or whatever paused it: a person, 5 failed runs in a row or the plan. It clears the failure count and heldUntil, and gives a schedule task its next run time. A schedule picks up at its next time, and the runs it missed while paused are not made up. It takes no body.

A task acts with what its caller holds, so the call needs the same scopes as create: threads:read, threads:write, emails:read, emails:send and labels:write beside tasks:write, and the read and write scopes of every toolkit the task names.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskResource with status active, pausedReason and heldUntil None and, for a schedule, nextRunAt set.

Example

from openemail import openemail task = openemail.tasks.resume('tsk_5c1e9a7b3d2f48e6a0b4c7d1') print(task['status'], task['nextRunAt'])

Notes

A plan that covers no more active tasks answers 403 task_active_limit_reached: 1 on Free, 5 on Starter, 25 on Business and no cap on Enterprise. A missing task is a 404 task_not_found.
A key or an app without the scopes of a toolkit the task names is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Retried automatically on network failure and retryable statuses, since resuming twice leaves the same active task.

Also available in

API: POST /tasks/{id}/resume
TypeScript: tasks.resume()
Ruby: tasks.resume
PHP: tasks->resume
Go: Tasks.Resume
Java: tasks().resume
C#: Tasks.ResumeAsync
CLI: openemail tasks resume

`tasks.run()`

Start a run of a task now

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def run(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskRunDetailResource

Starts a run of a task at once, whatever its trigger and whether or not it is paused, and returns the run as it was queued. The run works in the background. Read it again with get_run to follow it until status is done, failed or cancelled. While it is waiting, an approval request is open, which list_approvals reads.

The run uses the instruction and the settings the task has now, and counts towards its maxRunsPerDay. It takes no body. A task acts with what its caller holds, so the call needs the same scopes as create, counted from the toolkits of the task.

Parameters

idstrRequired: Task id such as tsk_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskRunDetailResource with a new id, status queued, trigger manual and the taskId and taskName of the task. transcript and approvals fill in as the run works.

Example

from openemail import openemail queued = openemail.tasks.run('tsk_5c1e9a7b3d2f48e6a0b4c7d1') run = openemail.tasks.get_run(queued['id']) print(run['status'], run['result'])

Notes

A task that has started maxRunsPerDay runs in the last 24 hours answers 409 task_run_limit_reached. A missing task is a 404 task_not_found.
A key or an app without the scopes of a toolkit the task names is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Not retried automatically: every call starts another run, so a retry after a lost response can start two. Read list_runs with task_id= before you try again.

Also available in

API: POST /tasks/{id}/run
TypeScript: tasks.run()
Ruby: tasks.run
PHP: tasks->run
Go: Tasks.Run
Java: tasks().run
C#: Tasks.RunAsync
CLI: openemail tasks run

`tasks.list_runs()`

List task runs, a page at a time

tasks:readthreads:reademails:readPages through results

Signature

def list_runs(    *,    limit: int | None = None,    cursor: str | None = None,    task_id: str | None = None,    status: TaskRunStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[TaskRunResource]

Returns one page of runs, newest first: every run in the workspace, or the runs of one task with task_id=. list_all_runs collects every page and iterate_runs walks them lazily. A run is one execution. It belongs to a task, named in taskId and taskName, or it is a one-off job started with start_run, where both are None.

status is queued until a runner picks the run up, running while it works, waiting while an approval request is open, then done, failed or cancelled. result is the report the run wrote when it finished, and error says why a failed run failed. steps, toolCalls and actions count how often the model was asked what to do next, how many tool calls ran and how many AI actions the run has cost the workspace. get_run adds the record of each step.

Runs are kept for 90 days.

Parameters

limitint: Page size, from 1 to 100. The server defaults to 25.
cursorstr: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
task_idstr: Only the runs of this task, by its id. Left out, the runs of every task and the one-off runs are listed.
statusTaskRunStatus: Only runs in this state: queued, running, waiting, done, failed or cancelled.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Page[TaskRunResource], a dict with items, hasMore and nextCursor. Each item has id, taskId, taskName, trigger, threadId, status, instruction, autonomy, model, steps, toolCalls, actions, result, error, errorDetail, pendingApprovals, chatId, createdAt, updatedAt, startedAt and finishedAt.

Example

from openemail import openemail page = openemail.tasks.list_runs(task_id='tsk_5c1e9a7b3d2f48e6a0b4c7d1', status='failed') for run in page['items']:    print(run['id'], run['createdAt'], run['error'], run['errorDetail'])

Notes

trigger says what started the run: schedule, mail or manual. A run that mail started names the conversation in threadId.
error is ai_limit when the workspace ran out of AI actions for the day, ai_unavailable when AI is not set up, and attempts or no_progress when the run kept failing or stood still. errorDetail adds a sentence about it.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
The cursor is opaque and holds where the last row sat in this order, so a run that starts between pages never breaks the walk.

Also available in

API: GET /task-runs
TypeScript: tasks.listRuns()
Ruby: tasks.list_runs
PHP: tasks->listRuns
Go: Tasks.ListRuns
Java: tasks().listRuns
C#: Tasks.ListRunsAsync
CLI: openemail tasks list-runs

`tasks.list_all_runs()`

Collect every task run into one list

tasks:readthreads:reademails:readPages through results

Signature

def list_all_runs(    *,    limit: int | None = None,    cursor: str | None = None,    task_id: str | None = None,    status: TaskRunStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[TaskRunResource]

Follows nextCursor from page to page and returns every run that matches, newest first, in the shape list_runs returns. limit= sets the page size of each request, not the total. A busy workspace keeps a great many runs for its 90 days, so give task_id= or status=, or prefer iterate_runs when you do not need them all in memory.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
task_idstr: Only the runs of this task, by its id.
statusTaskRunStatus: Only runs in this state: queued, running, waiting, done, failed or cancelled.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[TaskRunResource] holding every matching run across all pages.

Example

from openemail import openemail runs = openemail.tasks.list_all_runs(task_id='tsk_5c1e9a7b3d2f48e6a0b4c7d1', limit=100) actions = sum(run['actions'] for run in runs) print(f'{len(runs)} runs cost {actions} AI actions')

Notes

If any page fails, the call raises and the runs already fetched are discarded.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-runs
TypeScript: tasks.listAllRuns()
Ruby: tasks.list_all_runs
PHP: tasks->listAllRuns
Go: Tasks.ListAllRuns
Java: tasks().listAllRuns
C#: Tasks.ListAllRunsAsync

`tasks.iterate_runs()`

Stream the task runs one at a time

tasks:readthreads:reademails:readPages through results

Signature

def iterate_runs(    *,    limit: int | None = None,    cursor: str | None = None,    task_id: str | None = None,    status: TaskRunStatus | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[TaskRunResource]

Returns a generator that yields runs one by one, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
task_idstr: Only the runs of this task, by its id.
statusTaskRunStatus: Only runs in this state: queued, running, waiting, done, failed or cancelled.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Iterator[TaskRunResource], a generator yielding one run per step.

Example

from openemail import openemail for run in openemail.tasks.iterate_runs(status='waiting'):    print(run['id'], run['taskName'], 'waits for', run['pendingApprovals'], 'answers')

Notes

The generator is lazy, so an abandoned loop costs only the pages you consumed.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-runs
TypeScript: tasks.iterateRuns()
Ruby: tasks.iterate_runs
PHP: tasks->iterateRuns
Go: Tasks.IterateRuns
Java: tasks().iterateRuns
C#: Tasks.IterateRunsAsync

`tasks.get_run()`

Read one run with every step it took

tasks:readthreads:reademails:read

Signature

def get_run(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskRunDetailResource

Returns one run with everything it did: the fields of a row of list_runs, the record of the run in transcript, in order, and its approval requests in approvals, newest first. steps stays the count it is in list_runs.

The entry of transcript with role user holds the instruction the run started with. Each entry with role assistant is one step: the text the assistant wrote and calls, the tools it called at that step. A call names its tool as the MCP server lists it, with the args it was called with, done, which is False while the call waits for approval or has not run yet, and result, what the tool answered.

A run is queued, then running, and waiting while an approval request is open. Read it again until it is done, failed or cancelled. result then holds the report it wrote.

Parameters

idstrRequired: Run id such as run_2b8d4f6a1c3e5079b6d8f0a2, as list_runs returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskRunDetailResource: the fields of TaskRunResource, plus transcript, a list of steps with role, text, at and calls, and approvals, a list of TaskApprovalResource.

Example

from openemail import openemail run = openemail.tasks.get_run('run_2b8d4f6a1c3e5079b6d8f0a2') for step in run['transcript']:    for call in step['calls']:        print(step['at'], call['tool'], call['done']) print(run['status'], run['result'])

Notes

A missing run raises OpenEmailApiError with is_not_found set to True and code task_run_not_found. Runs are kept for 90 days, so an older one is missing too.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /task-runs/{id}
TypeScript: tasks.getRun()
Ruby: tasks.get_run
PHP: tasks->getRun
Go: Tasks.GetRun
Java: tasks().getRun
C#: Tasks.GetRunAsync
CLI: openemail tasks get-run

`tasks.start_run()`

Hand the assistant a one-off job to do in the background

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def start_run(    body: TaskRunStart,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskRunDetailResource

Hands the assistant one job to do in the background, with no task saved: a long tidy-up, a report, or anything that should not wait on an open chat. It returns the run as it was queued. Follow it with get_run, and answer what it asks with approve or deny.

instruction is the whole job, in plain words. threadId hands the run one conversation as its starting point. autonomy, toolkits, model and maxSteps mean what they mean on a task and take the same defaults. The workspace owner is notified when the run waits for approval or fails.

A workspace starts at most 100 of these in any 24 hours. A run acts with what its caller holds, so the call needs the same scopes as create: threads:read, threads:write, emails:read, emails:send and labels:write beside tasks:write, and the read and write scopes of every toolkit it names.

Parameters

body['instruction']strRequired: What the assistant should do, in plain words, trimmed, 1 to 8,000 characters. It is the only instruction the run follows: text inside emails is read, never obeyed.
body['autonomy']TaskAutonomy: How much the run may do without asking: ask, organize or reply. Defaults to organize.
body['toolkits']list[TaskToolkit]: Extra groups of tools the run may use beyond reading and organising mail, such as contacts, calendar, knowledge or web. Left out, drafts, notes and knowledge. An empty list gives it none.
body['model']TaskModel: standard is the everyday model. advanced reasons better over long jobs and costs ten AI actions where the standard one costs one. Defaults to standard.
body['maxSteps']int: The most model steps the run may take before it has to write its report, from 1 to 60. Defaults to 20.
body['threadId']str: A conversation to hand the run as its starting point, by the id threads.list returns.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskRunDetailResource with a new id, status queued, trigger manual, and taskId and taskName None. transcript and approvals fill in as the run works.

Example

from openemail import openemail queued = openemail.tasks.start_run(    {        'instruction': 'Find every invoice that arrived this month and label it Invoices.',        'autonomy': 'organize',        'maxSteps': 30,    }) print(queued['id'], queued['status'])

Notes

Past 100 one-off runs in 24 hours the call answers 409 task_run_limit_reached.
A toolkit a run may not use is 422 invalid_task, a value of the wrong type or length 422 invalid_parameter with param naming it, and a key the body does not take 422 unknown_parameter. A missing scope of a toolkit is a 403 insufficient_scope.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Not retried automatically: every call starts another run, so a retry after a lost response can start two. Read list_runs before you try again.

Also available in

API: POST /task-runs
TypeScript: tasks.startRun()
Ruby: tasks.start_run
PHP: tasks->startRun
Go: Tasks.StartRun
Java: tasks().startRun
C#: Tasks.StartRunAsync
CLI: openemail tasks start-run

`tasks.cancel_run()`

Stop a run that has not ended

tasks:write

Signature

def cancel_run(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskRunDetailResource

Stops a run that is queued, running or waiting for approval, and closes its open approval requests, which become cancelled. What the run already did stays done: nothing is rolled back. The task it belongs to is left as it is and runs again when its trigger next fires. It takes no body.

Parameters

idstrRequired: Run id such as run_2b8d4f6a1c3e5079b6d8f0a2, as list_runs returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskRunDetailResource with status cancelled and finishedAt set, and transcript showing how far it got.

Example

from openemail import openemail run = openemail.tasks.cancel_run('run_2b8d4f6a1c3e5079b6d8f0a2') print(run['status'], run['finishedAt'], run['toolCalls'])

Notes

A run that has already ended answers 409 task_run_finished, and a missing one 404 task_run_not_found.
To keep a task from starting more runs, use pause.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
Not retried automatically. A 409 task_run_finished on your own second attempt after a lost response means the first one worked or the run ended by itself, and get_run says which.

Also available in

API: POST /task-runs/{id}/cancel
TypeScript: tasks.cancelRun()
Ruby: tasks.cancel_run
PHP: tasks->cancelRun
Go: Tasks.CancelRun
Java: tasks().cancelRun
C#: Tasks.CancelRunAsync
CLI: openemail tasks cancel-run

`tasks.list_approvals()`

List what runs are waiting for a person to allow

tasks:readthreads:reademails:readPages through results

Signature

def list_approvals(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskApprovalStatus | None = None,    run_id: str | None = None,    task_id: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[TaskApprovalResource]

Returns one page of approval requests, newest first. An approval request is a tool call a run stopped at because it may not make it alone: tool names the tool, summary says in one line what would happen, and args holds the exact arguments it would be called with. A reply shows the recipients worked out from the message it answers.

Without status= the list holds only the requests still pending. Give status= to read the ones that were approved, denied, expired or cancelled, and run_id= or task_id= to read those of one run or of one task. list_all_approvals collects every page and iterate_approvals walks them lazily.

A request waits 7 days. Then it expires and the run carries on without it. Answer one with approve or deny.

Parameters

limitint: Page size, from 1 to 100. The server defaults to 25.
cursorstr: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
statusTaskApprovalStatus: Only requests in this state: pending, approved, denied, expired or cancelled. Left out, the list holds the ones still pending.
run_idstr: Only the requests of this run, by its id.
task_idstr: Only the requests of the runs of this task, by its id.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Page[TaskApprovalResource], a dict with items, hasMore and nextCursor. Each item has id, runId, taskId, taskName, tool, summary, args, status, createdAt, expiresAt and decidedAt.

Example

from openemail import openemail page = openemail.tasks.list_approvals() for approval in page['items']:    print(approval['id'], approval['taskName'], approval['summary'], approval['expiresAt'])

Notes

No value of status= means the requests still pending. Read each other state in turn to see the rest.
taskId and taskName are None on a request of a one-off run.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-approvals
TypeScript: tasks.listApprovals()
Ruby: tasks.list_approvals
PHP: tasks->listApprovals
Go: Tasks.ListApprovals
Java: tasks().listApprovals
C#: Tasks.ListApprovalsAsync
CLI: openemail tasks list-approvals

`tasks.list_all_approvals()`

Collect every approval request into one list

tasks:readthreads:reademails:readPages through results

Signature

def list_all_approvals(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskApprovalStatus | None = None,    run_id: str | None = None,    task_id: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[TaskApprovalResource]

Walks every page of list_approvals and returns all the requests that match, newest first. One request per page. Without status= it collects only the requests still pending, which is the list a person has to answer.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
statusTaskApprovalStatus: Only requests in this state: pending, approved, denied, expired or cancelled. Left out, the ones still pending are collected.
run_idstr: Only the requests of this run, by its id.
task_idstr: Only the requests of the runs of this task, by its id.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[TaskApprovalResource] holding every matching request.

Example

from openemail import openemail pending = openemail.tasks.list_all_approvals(run_id='run_2b8d4f6a1c3e5079b6d8f0a2') for approval in pending:    print(approval['tool'], approval['summary'])

Notes

If any page fails, the call raises and the requests already fetched are discarded.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-approvals
TypeScript: tasks.listAllApprovals()
Ruby: tasks.list_all_approvals
PHP: tasks->listAllApprovals
Go: Tasks.ListAllApprovals
Java: tasks().listAllApprovals
C#: Tasks.ListAllApprovalsAsync

`tasks.iterate_approvals()`

Stream the approval requests one at a time

tasks:readthreads:reademails:readPages through results

Signature

def iterate_approvals(    *,    limit: int | None = None,    cursor: str | None = None,    status: TaskApprovalStatus | None = None,    run_id: str | None = None,    task_id: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[TaskApprovalResource]

Returns a generator that yields approval requests one by one, newest first, and requests the next page only once the current one is drained. Without status= it yields only the requests still pending. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
statusTaskApprovalStatus: Only requests in this state: pending, approved, denied, expired or cancelled. Left out, the ones still pending are walked.
run_idstr: Only the requests of this run, by its id.
task_idstr: Only the requests of the runs of this task, by its id.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Iterator[TaskApprovalResource], a generator yielding one approval request per step.

Example

from openemail import openemail for approval in openemail.tasks.iterate_approvals(task_id='tsk_5c1e9a7b3d2f48e6a0b4c7d1'):    print(approval['id'], approval['tool'], approval['summary'])

Notes

The generator is lazy, so an abandoned loop costs only the pages you consumed.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-approvals
TypeScript: tasks.iterateApprovals()
Ruby: tasks.iterate_approvals
PHP: tasks->iterateApprovals
Go: Tasks.IterateApprovals
Java: tasks().iterateApprovals
C#: Tasks.IterateApprovalsAsync

`tasks.get_approval()`

Read one approval request by id

tasks:readthreads:reademails:read

Signature

def get_approval(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskApprovalResource

Looks up a single approval request and returns it in the same shape as a row of list_approvals: the run that asked and its task, the tool the run wants to call, the one-line summary, the exact args and its status. args are what will be done once it is approved, unless approve replaces the subject or the words of a send or a reply.

Parameters

idstrRequired: Approval request id such as apr_9f3a1c5e7b2d4608a1c3e5f7, as list_approvals returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskApprovalResource with id, runId, taskId, taskName, tool, summary, args, status, createdAt, expiresAt and decidedAt.

Example

from openemail import openemail approval = openemail.tasks.get_approval('apr_9f3a1c5e7b2d4608a1c3e5f7') print(approval['tool'], approval['summary'], approval['args'])

Notes

A missing request raises OpenEmailApiError with is_not_found set to True and code task_approval_not_found.
taskId and taskName are None on a request of a one-off run.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.

Also available in

API: GET /task-approvals/{id}
TypeScript: tasks.getApproval()
Ruby: tasks.get_approval
PHP: tasks->getApproval
Go: Tasks.GetApproval
Java: tasks().getApproval
C#: Tasks.GetApprovalAsync
CLI: openemail tasks get-approval

`tasks.approve()`

Let a run do what it asked for

tasks:writethreads:readthreads:writeemails:reademails:sendlabels:write

Signature

def approve(    id: str,    body: TaskApprovalEdits | None = None,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskApprovalResource

Approves a pending request, so the run makes the tool call with the arguments the request shows. For a send or a reply, subject and body replace what the run wrote, and the answer shows the changed args. For any other tool they are ignored. Call it with no body to approve the request as it stands.

The run picks up again once every request of its step is answered, so a run that asked for three things waits for three answers. A task acts with what its caller holds, so approving needs the scopes the run works with: the same as create, counted from the toolkits of its task.

Parameters

idstrRequired: Approval request id such as apr_9f3a1c5e7b2d4608a1c3e5f7, as list_approvals returns it.
body['subject']str: For a send or a reply: the subject to use instead of the one the run wrote, trimmed, 1 to 998 characters.
body['body']str: For a send or a reply: the words to send instead of the ones the run wrote, trimmed, 1 to 100,000 characters.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskApprovalResource with status approved, decidedAt set and args as the tool will be called with them.

Example

from openemail import openemail approval = openemail.tasks.approve(    'apr_9f3a1c5e7b2d4608a1c3e5f7', {'subject': 'Your refund is on its way'}) print(approval['status'], approval['decidedAt'])

Notes

A request that was already answered, has expired, or whose run has ended answers 409 task_approval_decided. A missing one is a 404 task_approval_not_found.
There is no undo once the run has acted, so read args first.
A key or an app without the scopes of a toolkit the task names is refused with 403 insufficient_scope, and a key the body does not take is 422 unknown_parameter.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
The SDK does not retry it. A 409 task_approval_decided on your own second attempt after a lost response means the first one worked or somebody else answered, and get_approval says how.

Also available in

API: POST /task-approvals/{id}/approve
TypeScript: tasks.approve()
Ruby: tasks.approve
PHP: tasks->approve
Go: Tasks.Approve
Java: tasks().approve
C#: Tasks.ApproveAsync
CLI: openemail tasks approve

`tasks.deny()`

Refuse what a run asked for

tasks:write

Signature

def deny(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> TaskApprovalResource

Denies a pending request. The run is told, does not try that call again, and carries on with the rest of its task once every request of its step is answered. Nothing the request described is done. It takes no body.

Parameters

idstrRequired: Approval request id such as apr_9f3a1c5e7b2d4608a1c3e5f7, as list_approvals returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

TaskApprovalResource with status denied and decidedAt set.

Example

from openemail import openemail approval = openemail.tasks.deny('apr_9f3a1c5e7b2d4608a1c3e5f7') print(approval['status'], approval['tool'])

Notes

A request that was already answered, has expired, or whose run has ended answers 409 task_approval_decided. A missing one is a 404 task_approval_not_found.
To stop the whole run instead of one request, use cancel_run.
A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported, and an app acting for a member whose role does not reach every address with 403 owner_only.
The SDK does not retry it. A 409 task_approval_decided on your own second attempt after a lost response means the first one worked or somebody else answered, and get_approval says how.

Also available in

API: POST /task-approvals/{id}/deny
TypeScript: tasks.deny()
Ruby: tasks.deny
PHP: tasks->deny
Go: Tasks.Deny
Java: tasks().deny
C#: Tasks.DenyAsync
CLI: openemail tasks deny