Tasks

from nextmail import nextmail task = nextmail.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 = nextmail.tasks.run(task['id']) for request in nextmail.tasks.iterate_approvals(run_id=queued['id']):    print(request['tool'], request['summary'], request['args'])     if request['tool'] == 'replyToEmail':        nextmail.tasks.approve(request['id'], {'subject': 'Your morning digest'})    else:        nextmail.tasks.deny(request['id']) run = nextmail.tasks.get_run(queued['id']) for step in run['transcript']:    for call in step['calls']:        print(step['at'], call['tool'], call['done']) job = nextmail.tasks.start_run({    'instruction': 'Find every invoice that arrived this month and label it Invoices.',    'maxSteps': 30,}) failed = nextmail.tasks.list_all_runs(task_id=task['id'], status='failed') nextmail.tasks.cancel_run(job['id'])nextmail.tasks.pause(task['id'])nextmail.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. Reading a run or one of its approval requests also needs the read scopes of every toolkit the run used. Without them, a list shows such a run without its report and its requests without their arguments. Approving counts the toolkits the run started with, plus the scopes of the tool the request would call.

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. A connector read that names a web address waits for approval too.

• tasks.list()Full reference
• tasks.list_all()Full reference
• tasks.iterate()Full reference
• tasks.get()Full reference
• tasks.create()Full reference
• tasks.update()Full reference
• tasks.delete()Full reference
• tasks.pause()Full reference
• tasks.resume()Full reference
• tasks.run()Full reference
• tasks.list_runs()Full reference
• tasks.list_all_runs()Full reference
• tasks.iterate_runs()Full reference
• tasks.get_run()Full reference
• tasks.start_run()Full reference
• tasks.cancel_run()Full reference
• tasks.list_approvals()Full reference
• tasks.list_all_approvals()Full reference
• tasks.iterate_approvals()Full reference
• tasks.get_approval()Full reference
• tasks.approve()Full reference
• tasks.deny()Full reference