Use tasks

Task support requires a server implementing urn:ietf:params:jmap:tasks (the JMAP Tasks specification). If the server does not support this capability, get_task_lists() raises JMAPMethodError.

Note

urn:ietf:params:jmap:tasks is an expired IETF draft with no known public server implementation, including Cyrus and Stalwart. The methods on this page are covered by unit tests with mocked responses, but haven’t been verified against a live server.

Task lists and tasks are returned as raw dicts using JMAP wire property names, not typed objects.

List task lists

task_lists = client.get_task_lists()
for tl in task_lists:
    print(tl["id"], tl["name"])

Create a task

title is required; everything else is optional.

task_list_id = task_lists[0]["id"]

task_id = client.create_task(
    task_list_id,
    title="Review pull request",
    due="2026-02-15T17:00:00",
    timeZone="Europe/Oslo",
)

Optional keyword arguments for create_task() use JMAP wire property names, not snake_case: description, start, due, timeZone, estimatedDuration, percentComplete, progress, priority.

Fetch a task

task = client.get_task(task_id)
print(task["title"])
print(task.get("progress", "needs-action"))
print(task.get("percentComplete", 0))

Update a task

Pass a partial patch dict using JMAP wire property names:

client.update_task(task_id, {"progress": "completed", "percentComplete": 100})

Delete a task

client.delete_task(task_id)