---
title: "Thread assignment"
description: "Give each thread an owner, a person or an agent, and let a person take a thread over from an agent and hand it back."
canonical: "https://machinemail.dev/docs/concepts/thread-assignment"
---

# Thread assignment

> Give each thread an owner, a person or an agent, and let a person take a thread over from an agent and hand it back.

Source: https://machinemail.dev/docs/concepts/thread-assignment

Every thread can have one assignee: a person in your organization or an agent. An agent is anything that works through a credential: an API key, a connected app (an OAuth client such as an MCP client) or an agent registered through auth.md. Assignment tells everyone, people and agents alike, who is handling a conversation.

Assignment is a MachineMail addition: AgentMail's API has no such field.

## Taking a thread over

A thread assigned to a person has been **taken over**. Agents stand back until it is handed back:

- Agents subscribed to `message.received` over MCP get no events for mail in that thread, including replies that arrive while the person has it.
- Over MCP, `get_thread` says who has the thread and tells the agent not to reply, forward or change it, and `list_threads` marks it.
- Webhooks and the event stream still deliver every event, so your own integrations see everything. The thread in `message.*` payloads carries its `assignee`, so a webhook consumer can apply the same rule.

Handing the thread back (assigning it to an agent, or unassigning it) lets agents pick it up again from the next message.

## In the dashboard

Open a thread in an inbox. The owner button in the thread header, beside **Show raw**, says who is handling it. An orange square on it means a person took the thread over and agents are paused. Its menu has:

- **Take over**, which assigns the thread to you and pauses agents on it.
- **Hand back**, which returns a thread you took over to the agent that had it before, or unassigns it when no agent had it.
- Everyone the thread can be reassigned to: members, API keys, connected apps and claimed agents.

Above the thread list, **All**, **Mine**, **Agents** and **Unassigned** filter the inbox by assignee. List rows show who has each thread.

## With the API

Assign with [Update Thread](https://machinemail.dev/docs/reference/api/threads), at `/v0/threads/{thread_id}` or `/v0/inboxes/{inbox_id}/threads/{thread_id}`:

```bash
# To yourself: the person (dashboard) or agent (API key, app, agent) making the call
curl -X PATCH https://api.machinemail.dev/v0/threads/thd_123 \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "assignee": "me" }'

# To a member: source "session" and their user ID
-d '{ "assignee": { "source": "session", "id": "user_123" } }'

# To an agent: source "api_key", "oauth_app" (a grant ID) or "agent" (a registered agent's ID)
-d '{ "assignee": { "source": "api_key", "id": "key_123" } }'

# Unassign
-d '{ "assignee": null }'
```

The assignee must belong to your organization: a member, an API key that is not revoked or expired, a connected app, or a claimed agent. Anything else is a `400` with `param: "assignee"`, and the request changes nothing, labels included.

Threads carry:

| Field               | Description                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `assignee`          | `null`, or `{ type, id, source, name, email? }`. `type` is `user` (a person) or `agent`.                   |
| `assigned_at`       | When the assignee last changed.                                                                            |
| `assigned_by`       | Who changed it, with `via` (`dashboard`, `api` or `mcp`).                                                  |
| `previous_assignee` | Who had it before the last change: the agent the dashboard's **Hand back** returns a taken-over thread to. |

`name` is a snapshot taken when the thread was assigned, so renaming a key later does not change it. A registered agent's name is the one it gave itself.

Assignment lives on the thread, not on its messages: label changes and new mail in the thread keep it.

### Filter by assignee

List Threads, at the organization, pod or inbox level, takes `assignee`:

| Value           | Threads                                          |
| --------------- | ------------------------------------------------ |
| `me`            | Assigned to the caller.                          |
| `none`          | Unassigned.                                      |
| `any`           | Assigned to anyone.                              |
| `people`        | Assigned to a person (taken over).               |
| `agents`        | Assigned to an agent.                            |
| `<source>:<id>` | Assigned to that one, such as `api_key:key_123`. |

```bash
machinemail threads list --inbox support@acme.dev --assignee none
machinemail threads update thd_123 --assignee '"me"'
```

### The `thread.assigned` event

Each change of assignee sends `thread.assigned`, with the `thread`, its new `assignee` (or `null`), the `previous_assignee` (or `null`) and `assigned_by`. Assigning a thread to the one it is already assigned to sends nothing. Like `message.released`, webhooks and WebSocket subscriptions receive it only when their `event_types` list it; the event stream and the event log always include it. It needs `message_read`, like `message.*` events.

## Over MCP

Agents assign threads with `assign_thread` and find theirs with `list_threads` and `assignee: "me"`:

```json
{ "inbox_id": "support@acme.dev", "thread_id": "thd_123", "assignee": "me" }
```

With [MCP Events](https://machinemail.dev/docs/agents/mcp#events-chatgpt), an agent is told when a thread is assigned to it. To set up an agent that works the threads you assign it, in ChatGPT or Claude, follow [Hand threads to an agent](https://machinemail.dev/docs/guides/hand-threads-to-an-agent).

An agent can hand a thread to a person with `{ "source": "session", "id": "user_123" }`, for example when a customer asks for a human. That takes the thread over: the agent stops getting its mail as events. See [MCP tools](https://machinemail.dev/docs/reference/mcp-tools#assign_thread).
