# `bird email threads update`

## Usage

```bash
bird email threads update <thread-id> [flags]
```

## Description

Update a thread

Apply label changes and contact links to a conversation. System labels move it:
add "archive" to file it away, add "spam" to file it as spam, add "inbox" (or remove "spam"
or "archive") to return it to the inbox. Remove "unread" to mark all retained received
messages as read. To block a sender, add a receive rule instead.

Build the request from flags, a JSON EmailThreadUpdateRequest body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird email threads update --example
```

## Options

#### Labels

| Name                       | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `--add-label <v1,v2,…>`    | Label to add; repeatable. System labels: inbox, archive, spam, unread. |
| `--remove-label <v1,v2,…>` | Label to remove; repeatable.                                           |

#### Metadata

| Name           | Description                                      |
| -------------- | ------------------------------------------------ |
| `--contact-id` | Contact ID (cnt_…) to link to this conversation. |

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--response-schema` | Print the fields this command returns, then exit |

## Related

| Name                                                                    | Description     |
| ----------------------------------------------------------------------- | --------------- |
| [`bird email threads delete`](/docs/cli/reference/email-threads-delete) | Delete a thread |
| [`bird email threads get`](/docs/cli/reference/email-threads-get)       | Get a thread    |
| [`bird email threads list`](/docs/cli/reference/email-threads-list)     | List threads    |