# Update a thread

`PATCH /v1/email/threads/{thread_id}`

Applies label changes to a conversation, and links or unlinks a contact. Adding `spam` files the conversation, and its received messages, as spam. Adding `archive` files it away without deleting it. Adding `inbox`, or removing `spam`, `blocked`, or `archive`, returns it to the inbox, and its unread count recomputes to match. An archived conversation returns to the inbox by itself when a new message arrives that isn't spam or blocked; a junk reply or an outbound send leaves it archived. To block a sender going forward, add a receive rule instead. Any field you leave out stays unchanged.

## Code samples

**TypeScript**

```ts
const thread = await bird.email.threads.update("thr_01abc", {
  labels: { add: ["archive"] },
});
console.log(thread.id);
```

Examples: [TypeScript](/docs/api/reference/update-email-thread.ts.md) · [Python](/docs/api/reference/update-email-thread.py.md) · [Go](/docs/api/reference/update-email-thread.go.md) · [PHP](/docs/api/reference/update-email-thread.php.md) · [CLI](/docs/api/reference/update-email-thread.cli.md) · [MCP](/docs/api/reference/update-email-thread.mcp.md) · [cURL](/docs/api/reference/update-email-thread.curl.md)

## Example response `200`

```json
{
  "id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
  "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
  "channel": "email",
  "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "subject": "Re: Your order",
  "last_direction": "inbound",
  "labels": [
    "inbox",
    "urgent"
  ],
  "highlights": {
    "subject": [
      "Re: your **order** **4821**"
    ],
    "text": [
      "confirming your **order** **4821** shipped"
    ]
  }
}
```

## Path parameters

- `thread_id` (string): Thread identifier. Starts with `thr_`.

## Request body

- `labels` (object): Label changes to apply. Labels in `add` are applied and labels in `remove` are taken off; other labels are left untouched. Adding a label that is already present, or removing one that is not, has no effect. System labels express state changes. On a conversation, adding `spam` files it as spam. Adding `archive` files it away without deleting it. Adding `inbox`, or removing `spam`, `blocked`, or `archive`, returns it to the inbox. Removing `unread` marks all retained received messages as read in one call. On a message, adding or removing `unread` flips read state. Adding or removing `trash` moves it to or out of the trash. The API rejects changes that contradict this model. A request cannot add more than one placement label. It cannot add `blocked`, because blocking a sender is a receive-rule decision. Removing `inbox` requires adding a destination. A conversation cannot add `trash` or `unread`; removing `unread` is the mark-all-read shortcut, and `trash` uses the `DELETE` verb. A message cannot use placement labels; move its conversation instead. A sent message cannot use `unread`. Custom labels are 1-64 characters with no commas, control characters, or leading or trailing whitespace. System label names and a small reserved set (`all`, `archived`, `deleted`, `draft`, `drafts`, `flagged`, `important`, `junk`, `muted`, `none`, `outbox`, `pinned`, `read`, `scheduled`, `snoozed`, `starred`) cannot be used as custom labels, in any casing. A conversation or message has at most 20 labels, system labels included.
- `labels.add` (array of string): Labels to apply.
- `labels.remove` (array of string): Labels to take off.
- `contact_id` (nullable string): Contact to link this conversation to, or null to unlink the current contact.

## Response body

- `id` (string, required): Thread ID.
- `mailbox_id` (string, required): Mailbox this conversation belongs to.
- `channel` (string, required): Channel this conversation lives on. Always `email`.
- `contact_id` (nullable string, required): Contact linked to this conversation, or null when none is linked.
- `subject` (nullable string, required): Subject of the conversation, taken from its first message. Null when that message had no subject.
- `participants` (array of string, required): Addresses that appear on the retained messages in this conversation, including the mailbox's own address.
- `message_count` (integer, required): Number of retained messages in this conversation, both directions.
- `unread_count` (integer, required): Number of retained received messages that are still unread. Spam and blocked mail is not counted.
- `last_message_at` (string, required): When the most recent retained message in this conversation was received or sent.
- `last_direction` (string, required)

  Direction of the most recent message: `inbound` for a received message, `outbound` for a sent one.

  Possible values: `inbound`, `outbound`
- `labels` (array of string, required)

  Labels on this conversation. Exactly one system placement label is always present, set by the message that started the conversation:

  - `inbox`: The conversation is in the inbox.
  - `archive`: The conversation was filed away and is done for now.
  - `spam`: The conversation's opening message is filed in Spam.
  - `blocked`: The conversation's opening message was rejected by the mailbox's receive policy or rules.

  Move a conversation by updating its labels. Add `spam` to file it as spam, add `archive` to clean it out of the inbox, and add `inbox`, or remove `spam`, `blocked`, or `archive`, to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list, and a conversation has at most 20 labels in total.
- `created_at` (string, required): When the thread was created.
- `updated_at` (string, required): When the thread last changed.
- `highlights` (object): Matched search fragments, keyed by the field that matched. Returned only by thread search. Omitted when listing threads.
- `highlights.subject` (array of string): Matched fragments from the conversation's subject.
- `highlights.text` (array of string): Matched fragments from a message's body text.

## Related resources

- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Email](/email-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=email)