---
title: "Hand threads to an agent"
description: "Assign email threads to an agent from the dashboard or the API, have it pick them up with the thread.assigned MCP event (ChatGPT) or by checking list_threads (clients without events), and take a thread back when it needs a person."
canonical: "https://machinemail.dev/docs/guides/hand-threads-to-an-agent"
---

# Hand threads to an agent

> Assign email threads to an agent from the dashboard or the API, have it pick them up with the thread.assigned MCP event (ChatGPT) or by checking list_threads (clients without events), and take a thread back when it needs a person.

Source: https://machinemail.dev/docs/guides/hand-threads-to-an-agent

Assignment turns an inbox into a queue you share with your agents. You pick which conversations an agent handles, it is told when one lands on its desk, and you can take any thread back from it. This guide sets that up end to end. For how assignment works, see [Thread assignment](https://machinemail.dev/docs/concepts/thread-assignment).

## Connect the agent

The agent needs its own identity in your organization, so a thread can be assigned to it. Any of these works:

- **An MCP client**, such as ChatGPT or Claude, signed in over OAuth. It shows up as a connected app. See [Connect an agent](https://machinemail.dev/docs/guides/connect-an-agent).
- **An API key** for an agent that calls the API or the MCP server with a key. See [Create a key for an agent](https://machinemail.dev/docs/guides/api-key-for-an-agent).
- **An agent registered through auth.md** and claimed by you. See [auth.md](https://machinemail.dev/docs/agents/auth-md).

The connection needs `messages.read` to read the thread and `messages.write` (`message_update`) to assign threads itself.

## Assign a thread to it

**Dashboard**

Open the thread. Choose the owner button in the thread header, beside **Show raw**, and pick the agent under **Agents**. Connected apps are listed by their app name, API keys by their key name.

**Agents** above the thread list shows every thread an agent has, and the row says which one.

**API**

```bash title="Terminal"
curl -X PATCH https://api.machinemail.dev/v0/threads/thd_123 \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "assignee": { "source": "oauth_app", "id": "grant_123" } }'
```

`source` is `api_key`, `oauth_app` (a connected app's grant ID) or `agent` (a registered agent's ID). An agent assigning a thread to itself sends `"assignee": "me"`.

**MCP**

An agent can route mail to another agent, or claim a thread itself, with `assign_thread`:

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

## Have the agent pick it up

How the agent learns about the thread depends on whether its client supports [MCP Events](https://machinemail.dev/docs/agents/mcp#events-chatgpt).

**ChatGPT (events)**

ChatGPT subscribes to `thread.assigned` and is woken the moment a thread is assigned to it. Set up a task as in [Set up a task in ChatGPT](https://machinemail.dev/docs/agents/mcp#set-up-a-task-in-chatgpt), and tell it what to do with its threads, for example:

> *"When a MachineMail thread is assigned to you, read it, check the sender's trust level, and draft a reply for me to review. If a thread is taken from you, stop working on it."*

Each event carries the thread, not the email:

```json title="thread.assigned"
{
  "thread_id": "thd_123",
  "inbox_id": "support@acme.dev",
  "subject": "Refund for order 4411",
  "assignee": { "type": "agent", "source": "oauth_app", "id": "grant_123", "name": "ChatGPT" },
  "previous_assignee": null,
  "assigned_by": { "type": "user", "source": "session", "id": "user_123", "name": "Dana" },
  "assigned_at": "2026-11-17T14:02:11.000Z",
  "assigned_to_you": true,
  "taken_from_you": false
}
```

`assigned_to_you` means the thread is now the agent's to handle: it reads the conversation with `get_thread`. `taken_from_you` means it was reassigned, unassigned or taken over, and the agent should stop. The subject is the sender's text, so it is untrusted like the email itself.

To have the agent also follow the conversation as replies come in, subscribe it to `message.received` with `assignee: "me"`. It is then woken only for new mail in its own threads, not for every message in the inbox.

**Clients without events**

Clients without MCP Events check for work instead. At the start of each run, or on a schedule, the agent calls `list_threads` with `assignee: "me"`:

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

It gets every thread assigned to it, newest first, and reads each with `get_thread`. A thread it has finished can be unassigned with `assign_thread` and `"assignee": "none"`, so the list stays a to-do list.

A prompt that works well: &#x2A;"Check MachineMail for threads assigned to you, handle each one, and unassign it when you are done."* Pair it with a scheduled task to work the queue every hour.

## Take a thread back

When a conversation needs a person, open it and choose &#x2A;*Take over (pause agents)** in the owner button's menu. The thread is assigned to you and an orange square marks it as taken over:

- The agent gets `thread.assigned` with `taken_from_you: true`.
- Agents get no `message.received` events for the thread, including replies that arrive while you have it.
- `get_thread` tells any agent that opens it who has it and not to reply.

When you are done, **Hand back** returns the thread to the agent that had it, which gets `thread.assigned` again with `assigned_to_you: true`.

An agent can do the reverse: when a customer asks for a human, it assigns the thread to a member with `{ "source": "session", "id": "user_123" }`, and stands back until it is handed back.

## Webhooks

Your own integrations can follow every change too. Add `thread.assigned` to a webhook's `event_types`, for example to post in a team channel when an agent hands a thread to a person. It is opt-in, so a webhook with an empty list does not get it. See [Webhook events](https://machinemail.dev/docs/reference/webhook-events#threadassigned).
