---
title: "Create a task"
description: "Saves an instruction with a trigger and turns it on. A schedule task runs at its next time, and a mail task from the next message that arrives."
url: "https://openemail.uk/docs/api/tasks/create"
area: "API"
category: "Mailbox"
---

# Create a task

Saves an instruction with a trigger and turns it on. A schedule task runs at its next time, and a mail task from the next message that arrives.

`POST /tasks`

## POST /tasks

Saves an instruction with a trigger and turns it on. A schedule task runs at its next time, and a mail task from the next message that arrives.

## Example

Needs `tasks:write`, `threads:read`, `threads:write`, `emails:read`, `emails:send` and `labels:write`, and the scopes of each toolkit in `toolkits`.

**curl**

```
curl -X POST "$OE/tasks" -H "$AUTH" -H 'content-type: application/json' -d '{
  "name": "Morning summary",
  "instruction": "Go through the mail that arrived since yesterday. Tell me which conversations need a reply from me, most urgent first, and draft a short reply for each.",
  "trigger": {
    "kind": "schedule",
    "schedule": { "cadence": "daily", "hour": 8, "minute": 0, "weekdays": [1, 2, 3, 4, 5], "timezone": "Europe/London" }
  },
  "autonomy": "organize"
}'
```

**Response**

```
{
  "object": "task",
  "id": "tsk_4b9e2c7a1f3d86e05a9c2b7d",
  "name": "Morning summary",
  "instruction": "Go through the mail that arrived since yesterday. Tell me which conversations need a reply from me, most urgent first, and draft a short reply for each.",
  "status": "active",
  "pausedReason": null,
  "trigger": {
    "kind": "schedule",
    "schedule": {
      "cadence": "daily",
      "everyHours": 1,
      "hour": 8,
      "minute": 0,
      "weekdays": [1, 2, 3, 4, 5],
      "monthDay": 1,
      "timezone": "Europe/London"
    },
    "mail": null
  },
  "autonomy": "organize",
  "toolkits": ["notes", "drafts", "knowledge"],
  "model": "standard",
  "notify": "attention",
  "maxRunsPerDay": 50,
  "maxSteps": 20,
  "nextRunAt": "2026-10-14T07:00:00.000Z",
  "heldUntil": null,
  "lastRunAt": "2026-10-13T07:00:04.112Z",
  "lastRunStatus": "done",
  "runCount": 12,
  "pendingApprovals": 0,
  "createdAt": "2026-10-01T09:12:44.000Z",
  "updatedAt": "2026-10-13T07:01:10.530Z"
}
```

> Only `name`, `instruction` and `trigger` are required. `autonomy` defaults to `organize`, `model` to `standard`, `notify` to `attention`, `maxRunsPerDay` to 50 and `maxSteps` to 20.

> Left out, `toolkits` is `drafts`, `notes` and `knowledge`, so the request also needs `drafts:read`, `drafts:write`, `knowledge:read` and `knowledge:write`. Send `"toolkits": []` for a task that only reads and organises mail.

> `"paused": true` saves the task without turning it on, which also keeps it out of the plan’s count of active tasks.

> A schedule without a `timezone` runs on UTC. The parts a cadence does not use are filled in and ignored.

> A mail task with no `mail` filter runs for every message that reaches an inbox, so narrow it with `addresses`, `fromContains` or `subjectContains` where you can.

> `notify` says when the owner and whoever made the task hear about a run: `attention` when it waits for approval or fails, `always` also when it finishes, `never` not at all.

> A value that does not fit is refused with 422 `invalid_task`, and `param` names the field.

## Reference

- [`POST /tasks`](https://openemail.uk/docs/api/reference/tasks#post-tasks): full reference