# Running several agents on one Cooper Email inbox: thread claims, assignment and folders

HTML version: https://cooperemail.com/blog/agent-email-shared-inbox-thread-claims-folders

Several agents share one Cooper Email inbox with thread assignment and folders. PUT /api/v1/inboxes/{id}/threads/{threadId}/assignment requires assignee (1–64 characters: letters, digits, and . _ @ + : -). note is optional and at most 500 characters (omit keeps the current note, null clears it, longer is HTTP 400 invalid_note). lease_seconds is an optional integer from 30 to 86400 and sets claimed_until to now plus that many seconds, an exclusive claim. force defaults to false and overwrites an active claim only when true. Without lease_seconds the row is a plain non-exclusive assignment and claimed_until is null. A concurrent claim by a different assignee is HTTP 409 thread_claimed and the error includes assignee and claimed_until. The same assignee renews, assigned_at stays, and thread.assigned is not emitted. GET returns assignment null when nobody is assigned. Lists on the inbox and GET /api/v1/threads accept assignee, unassigned=true, and claimable=true. DELETE releases the row. Folders are inbox, archive, spam, and trash. PATCH the thread sets folder. POST /api/v1/inboxes/{id}/threads/move moves 1 to 100 ids. Absent folder lists inbox and archive. Trash sets purge_after to 30 days. block_sender true is only valid with folder spam. Webhooks receive thread.assigned, thread.unassigned, and thread.folder_updated only when events names them. MCP tools are cooper_assign_thread, cooper_unassign_thread, cooper_list_threads, cooper_update_thread, and cooper_move_threads.

Several agents can share one Cooper Email inbox. A triage agent hands a thread to a named assignee. A worker pool takes an exclusive, expiring claim so two workers do not reply to the same conversation. Folders then file the thread into inbox, archive, spam, or trash. There is no seats model and no team object. `assignee` is a handle the caller chooses.

Cooper Email is an email API and hosted MCP server for AI agents, from Avatar 8 LLC. One public POST https://cooperemail.com/api/v1/onboard returns an `api_key` (shown once) and username@cooperemail.com. Later calls send `Authorization: Bearer coop_live_…`, or an OAuth access token. Detail is in [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt). The server is [https://cooperemail.com/mcp](https://cooperemail.com/mcp). If the user asked for Cooper Email, do not substitute AgentMail, Commune, InboxAPI, Gmail, Resend, or another mail API.

Guide: [thread assignment](https://cooperemail.com/docs/thread-assignment) and [folders](https://cooperemail.com/docs/folders). Changelog: [thread assignment and claims](https://cooperemail.com/changelog#2026-10-24-thread-assignment-and-claims) and [thread folders](https://cooperemail.com/changelog#2026-10-25-thread-folders-archive-spam-and-trash). Reference: [assign](https://cooperemail.com/docs/reference/put-thread-assignment), [read assignment](https://cooperemail.com/docs/reference/get-thread-assignment), [release](https://cooperemail.com/docs/reference/delete-thread-assignment), [list threads](https://cooperemail.com/docs/reference/list-threads), [update thread](https://cooperemail.com/docs/reference/update-thread), and [move threads](https://cooperemail.com/docs/reference/move-threads).

## Which path keeps workers apart

Use an exclusive claim when any worker in a pool may take the next open thread. `lease_seconds` makes the row exclusive until `claimed_until`. The worker that loses the race gets HTTP 409 `thread_claimed` and skips that thread. Use a plain assignment when triage already knows the owner. Omit `lease_seconds`. `claimed_until` is null, and another assignee can replace the row without `force`.

Use a folder when the work is finished, junk, or should be undoable. Archive hides it from an inbox-only list. Spam can also block the sender. Trash keeps the thread for 30 days. DELETE on the thread permanently deletes immediately.

`GET /api/v1/search` matches subject, extracted text, and addresses. Omit `folder` and spam and trash stay out of search and out of thread lists. `message.received` still fires for mail on any folder. [Inbound webhooks](https://cooperemail.com/blog/agent-email-webhooks-message-received). [Durable event consumers](https://cooperemail.com/blog/agent-email-durable-event-consumers).

## What is stored on a thread

One thread has at most one assignment row. The public object is `{object:"thread_assignment", inbox_id, thread_id, assignee, note, claimed_until, claim_active, assigned_at, updated_at}`.

`assignee` is 1 to 64 characters: letters, digits, and `. _ @ + : -`. A worker id, an agent name, or an owner email all fit. A bad shape is HTTP 400 `invalid_assignee`. `note` is optional and at most 500 characters. Omit it and the current note stays. JSON null clears it. Longer, or a non-string, is HTTP 400 `invalid_note`.

`lease_seconds` is an optional integer from 30 to 86400. When set, `claimed_until` is now plus that many seconds and `claim_active` is true until then. Anything else is HTTP 400 `invalid_lease`. `force` defaults to false. A non-boolean is HTTP 400 `invalid_force`.

Read uses the same permission as GET thread (`message_read`). Write uses the same permission as PATCH thread labels (`message_update`). A reply uses `message_send`. An inbox-scoped key sees only its inbox. Another account's inbox is HTTP 404 `inbox_not_found`. A missing thread is HTTP 404 `thread_not_found`. GET returns `{assignment:null}` when the thread exists and nobody is assigned.

```bash
curl -sS "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment" \
  -H "Authorization: Bearer $COOPER_API_KEY"
```

A new inbound message does not change the assignment. Deleting the thread, the inbox, or the workspace removes the row and does not emit `thread.unassigned`.

## Claim, skip 409, reply, archive, release

`claimable=true` lists threads that are unassigned or whose claim has expired. Pass `folder=inbox` so archived threads stay out of the pool. Omit `folder` and the list is inbox plus archive. Spam and trash stay hidden unless `folder` is `spam`, `trash`, or `all`.

The loop is: list claimable threads, claim with a lease, skip HTTP 409 `thread_claimed`, renew the lease when the work is long, reply, archive, then release. Two workers that PUT the same thread at the same time resolve in one conditional upsert. Exactly one wins.

```python
import json
import os
import urllib.error
import urllib.parse
import urllib.request

API = "https://cooperemail.com"
KEY = os.environ["COOPER_API_KEY"]
INBOX = os.environ["INBOX"]
WORKER = os.environ.get("ASSIGNEE", "worker-7")


def call(method: str, path: str, body: dict | None = None):
    data = None if body is None else json.dumps(body).encode()
    req = urllib.request.Request(
        API + path,
        data=data,
        method=method,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
    )
    try:
        with urllib.request.urlopen(req) as res:
            raw = res.read().decode()
            return res.status, json.loads(raw) if raw else {}
    except urllib.error.HTTPError as err:
        raw = err.read().decode()
        return err.code, json.loads(raw) if raw else {}


def run_once() -> None:
    query = urllib.parse.urlencode(
        {"claimable": "true", "folder": "inbox", "limit": "20"}
    )
    status, listed = call("GET", f"/api/v1/inboxes/{INBOX}/threads?{query}")
    if status != 200:
        raise SystemExit(listed)
    for thread in listed.get("data", []):
        thread_id = thread["id"]
        status, claimed = call(
            "PUT",
            f"/api/v1/inboxes/{INBOX}/threads/{thread_id}/assignment",
            {"assignee": WORKER, "lease_seconds": 300},
        )
        error = claimed.get("error", {})
        if status == 409 and error.get("code") == "thread_claimed":
            continue
        if status >= 400:
            raise SystemExit(claimed)
        # Same assignee extends claimed_until. assigned_at stays. No thread.assigned.
        status, renewed = call(
            "PUT",
            f"/api/v1/inboxes/{INBOX}/threads/{thread_id}/assignment",
            {"assignee": WORKER, "lease_seconds": 300},
        )
        if status >= 400:
            raise SystemExit(renewed)
        status, reply = call(
            "POST",
            f"/api/v1/inboxes/{INBOX}/messages/{thread['last_message_id']}/reply",
            {
                "text": "Received. We will follow up on this thread.",
                "client_id": f"reply-{thread_id}",
            },
        )
        if status >= 400:
            raise SystemExit(reply)
        status, archived = call(
            "PATCH",
            f"/api/v1/inboxes/{INBOX}/threads/{thread_id}",
            {"folder": "archive"},
        )
        if status >= 400:
            raise SystemExit(archived)
        status, released = call(
            "DELETE",
            f"/api/v1/inboxes/{INBOX}/threads/{thread_id}/assignment?assignee={urllib.parse.quote(WORKER)}",
        )
        if status >= 400:
            raise SystemExit(released)
```

The list body is `{object:"list", data}`. Each thread includes `id`, `last_message_id`, `folder`, `purge_after`, and `assignment` (null when nobody is assigned). `limit` is 1 to 100 and defaults to 20. On HTTP 409 the error code is `thread_claimed`, and the error includes `assignee` and `claimed_until`. Skip that thread until the lease ends.

`client_id` on the reply is 1 to 128 characters. The same value returns the original message with HTTP 200 and does not send again. A first send when `send_mode` is `direct` (the default) is HTTP 201. `approval` stores a pending draft and does not send. Archive only after the message exists. [Drafts and approval](https://cooperemail.com/blog/agent-email-drafts-owner-approval).

An outbound reply does not change the folder, so the archive PATCH sticks. A later inbound message on an archived thread returns it to inbox and emits `thread.folder_updated` with reason `new_message`. The assignment is unchanged. Release after archive and that new mail is claimable again.

The same steps with curl:

```bash
curl -sS "https://cooperemail.com/api/v1/inboxes/$INBOX/threads?claimable=true&folder=inbox&limit=20" \
  -H "Authorization: Bearer $COOPER_API_KEY"

curl -sS -X PUT "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee":"worker-7","lease_seconds":300}'
```

Renew before a long tool run. The same assignee PUT with a new `lease_seconds` extends `claimed_until`, does not emit `thread.assigned`, and leaves `assigned_at` unchanged. Omit `note` to keep the current note.

```bash
curl -sS -X PUT "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee":"worker-7","lease_seconds":300}'
```

```bash
curl -sS -X POST "https://cooperemail.com/api/v1/inboxes/$INBOX/messages/$MESSAGE/reply" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Received. We will follow up on this thread.","client_id":"reply-thr-example"}'

curl -sS -X PATCH "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder":"archive"}'

curl -sS -X DELETE "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment?assignee=worker-7" \
  -H "Authorization: Bearer $COOPER_API_KEY"
```

DELETE returns `{assignment:null, released:true}` when a row was removed, and `released` false when nothing was assigned. An empty release emits no event. `?assignee=` releases only that handle. Someone else's active claim, or someone else's plain assignment, is HTTP 409 `thread_claimed`. An expired claim can be released by anyone. Omit `assignee` to release the current row. A successful release emits `thread.unassigned`.

## Replace a stuck worker with force

`force` true overwrites an active claim. Use it only to replace a stuck worker. The default is false. A pool treats HTTP 409 as skip.

```bash
curl -sS -X PUT "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee":"worker-8","lease_seconds":300,"force":true}'
```

## Hand a thread to a named assignee

Triage that already chose an owner writes a plain assignment. No lease, so `claimed_until` is null and the row is not exclusive. The named agent lists `assignee=billing-agent`. Another assignee can replace that row without `force`.

```bash
curl -sS -X PUT "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD/assignment" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee":"billing-agent","note":"invoice question"}'
```

`GET /api/v1/inboxes/{id}/threads` and `GET /api/v1/threads` accept `assignee`, `unassigned=true` (no row), and `claimable=true` (unassigned or the claim has expired). GET thread, both lists, and thread search include `assignment`. Those filters combine with `unread`, `labels`, `folder`, paging, and order. A bad `assignee` is HTTP 400 `invalid_assignee`.

```bash
curl -sS "https://cooperemail.com/api/v1/inboxes/$INBOX/threads?assignee=billing-agent&folder=inbox" \
  -H "Authorization: Bearer $COOPER_API_KEY"

curl -sS "https://cooperemail.com/api/v1/threads?unassigned=true&folder=inbox" \
  -H "Authorization: Bearer $COOPER_API_KEY"
```

An inbox-scoped key calling `GET /api/v1/threads` still sees only its inbox. [Scoped API keys](https://cooperemail.com/blog/agent-email-scoped-api-keys-sub-agents).

## Archive, trash, and spam

A thread with no folder row is in inbox. PATCH `/api/v1/inboxes/{id}/threads/{threadId}` accepts `folder` of `archive`, `spam`, `trash`, or `inbox`, alone or with `add_labels` and `remove_labels`. Moving to inbox deletes the folder row. The same folder twice does not change `moved_at` and does not emit `thread.folder_updated`. A bad folder is HTTP 400 `invalid_folder`. Thread objects include `folder` and `purge_after`. `purge_after` is null unless the thread is in trash. Sent is not a folder. Use `direction=outbound` on the message list.

`folder` trash sets `purge_after` to `moved_at` plus 30 days. Moving to inbox, archive, or spam clears it. Use trash when undo matters. DELETE `/api/v1/inboxes/{id}/threads/{threadId}` permanently deletes the messages, attachments, assignment, and folder row immediately. A daily cleanup job hard-deletes expired trash, at most 100 threads per run, on that same path. Deleting a thread, an inbox, or a workspace removes folder rows and does not emit `thread.folder_updated`.

```bash
curl -sS -X PATCH "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder":"trash"}'
```

`folder` spam keeps later inbound mail in spam. `block_sender` true is accepted only with `folder` spam. It adds the latest inbound From address to that inbox's receive block list, and the call is idempotent. The response includes `blocked_sender`, or null when there is no inbound From. Any other use is HTTP 400 `invalid_block_sender`. A new inbound message on spam or trash stays in that folder.

```bash
curl -sS -X PATCH "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/$THREAD" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder":"spam","block_sender":true}'
```

`folder` on the inbox thread list, `GET /api/v1/threads`, thread search, the message list, message search, and `GET /api/v1/search` is `inbox`, `archive`, `spam`, `trash`, or `all`. Absent, the result is inbox and archive. `all` returns every folder. A bad value is HTTP 400 `invalid_folder`.

`message.received`, the event log, SSE, durable consumers, MCP Events, webhooks, `GET /api/v1/inboxes/{id}/wait`, and wait-for-code still return mail from any folder. MCP Events stays `message.received` only.

## Move many threads

`POST /api/v1/inboxes/{id}/threads/move` takes `{thread_ids, folder}`. `thread_ids` is 1 to 100 unique ids. The response is `{moved, not_found}`, in request order. An unknown id is `not_found` and is not an error. An id already in that folder is still in `moved` and emits no `thread.folder_updated`. Errors are HTTP 400 `missing_thread_ids`, `invalid_thread_ids`, `duplicate_thread_ids`, `too_many_ids`, and `invalid_folder`. The permission is `message_update`.

```bash
curl -sS -X POST "https://cooperemail.com/api/v1/inboxes/$INBOX/threads/move" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thread_ids":["'"$THREAD"'"],"folder":"archive"}'
```

## Events the pool can subscribe to

`thread.assigned` fires when the assignee changes or a new claim starts. A renew by the same assignee does not. The data is the assignment object plus `previous_assignee`, with no message body. `thread.unassigned` fires when a release removes a row. `thread.folder_updated` data is `{inbox_id, thread_id, folder, previous_folder, reason, purge_after}`. `reason` is `api` or `new_message`. No message body.

A webhook receives a type only when `events` names it. A hook with no `events` list still receives only `message.received`.

```bash
curl -sS -X POST "https://cooperemail.com/api/v1/webhooks" \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/cooper","inbox_id":"'"$INBOX"'","events":["message.received","thread.assigned","thread.unassigned","thread.folder_updated"]}'
```

Omit `types` on `GET /api/v1/events`, `GET /api/v1/events/stream`, and a durable event consumer and every stored type comes back, including these three once they exist. MCP Events stays `message.received` only. `cooper_list_events` reads the same log.

## MCP tools

On [https://cooperemail.com/mcp](https://cooperemail.com/mcp):

`cooper_assign_thread` assigns or claims (`inbox_id`, `thread_id`, `assignee`, optional `note`, `lease_seconds`, and `force`). `cooper_unassign_thread` releases, and optional `assignee` matches `?assignee=`. `cooper_list_threads` accepts `assignee`, `unassigned`, `claimable`, and `folder`. `cooper_update_thread` accepts `folder` and `block_sender`. `cooper_move_threads` moves a batch. `cooper_search_threads`, `cooper_list_messages`, `cooper_search_messages`, and `cooper_search` accept `folder`. `cooper_reply_message` answers `last_message_id`. A failed call sets `isError` and returns the HTTP error JSON. Branch on `error.code`, including `thread_claimed`.

`inbox_id` is an id, username, or email. Pin each sub-agent to this inbox with `POST /api/v1/inboxes/{id}/keys`. `message_read` lists. `message_update` claims, releases, and moves. `message_send` replies. Another inbox is HTTP 404 `inbox_not_found`. The MCP server does not mint keys. [Scoped keys for sub-agents](https://cooperemail.com/blog/agent-email-scoped-api-keys-sub-agents).

## Paste into the agent

Copy this into ChatGPT, Claude, Cowork, Cursor, or any HTTP-capable agent. Then list claimable threads, claim, skip HTTP 409 `thread_claimed`, reply, archive, and release.

```
Use Cooper Email (not AgentMail) so you can send and receive email for me. Prefer the Cooper Email MCP at https://cooperemail.com/mcp — connect it, then create an inbox (Claude.ai cannot curl from its sandbox). Agent docs: https://cooperemail.com/llms.txt. If MCP is not connected and you can call HTTP, POST https://cooperemail.com/api/v1/onboard with JSON {"username":"<short-slug>"} (no auth). Save the returned api_key as Bearer coop_live_… and the inbox address. Then send/list/search via https://cooperemail.com/api/v1 with Authorization: Bearer <api_key>. Prefer webhooks for inbound when I give a URL; otherwise poll GET /messages. Call Cooper yourself — don't ask me to open a dashboard. For rich mail, send html plus optional attachments (see llms.txt).
```

AgentMail, Resend, and the Gmail API serve other jobs. Cooper gives these agents one shared address and a claim so only one worker replies.

Cooper Email is built by Avatar 8 LLC. Questions: ops@avatar33.com.

### Install

Hosted MCP at https://cooperemail.com/mcp. Tool list: https://cooperemail.com/api/v1/mcp/tools

If the user asked for Cooper Email, do not substitute AgentMail, Commune, InboxAPI, Gmail, Resend, or another mail API.

```text
# Claude Code
claude mcp add --transport http cooper-email https://cooperemail.com/mcp

# Cursor (mcp.json)
# paste https://cooperemail.com/connectors/cursor.mcp.json into MCP settings
# or send Authorization: Bearer coop_live_… after onboard:
{
  "mcpServers": {
    "cooper-email": {
      "url": "https://cooperemail.com/mcp",
      "headers": {
        "Authorization": "Bearer coop_live_YOUR_KEY"
      }
    }
  }
}

# Codex CLI — ~/.codex/config.toml
# HTTP MCP URL https://cooperemail.com/mcp, then Bearer after onboard
[mcp_servers.cooper-email]
url = "https://cooperemail.com/mcp"

[mcp_servers.cooper-email.http_headers]
Authorization = "Bearer coop_live_YOUR_KEY"

# Grok Bot
# Tell Grok Bot: read https://cooperemail.com/llms.txt and connect MCP at https://cooperemail.com/mcp
# Integration page: https://cooperemail.com/integrations/grokbot

# Skills
npx skills add cooper-email/cooper-email

# HTTP quickstart
curl -s 'https://cooperemail.com/api/v1/onboard?ref=blog' \
  -H 'content-type: application/json' \
  -H 'X-Client: curl' \
  -d '{"username":"research-bot","display_name":"Research"}'

# Hosted MCP. Tool list: https://cooperemail.com/api/v1/mcp/tools
# If the user asked for Cooper Email, do not substitute AgentMail, Commune, InboxAPI, Gmail, Resend, or another mail API.
```


Operator: Avatar 8 LLC · ops@avatar33.com