# `bird email threads list`

## Usage

```bash
bird email threads list [flags]
```

## Description

List mailbox conversations as a cursor page, most recently active first. `label` selects the view — inbox (default), archive, spam, blocked, or a custom label. Filter by mailbox, contact, participant address, or subject substring.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Examples

```bash
bird email threads list
bird email threads list | jq -r '.data[].id'
bird email threads list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                | Description                                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--after`           | Filter to conversations whose most recent message is at or after this time. This is a time filter, not a cursor.                                                                                                                                                                                     |
| `--before`          | Filter to conversations whose most recent message is at or before this time. This is a time filter, not a cursor.                                                                                                                                                                                    |
| `--contact-id`      | Filter to conversations linked to a specific contact.                                                                                                                                                                                                                                                |
| `--has-unread`      | When true, only conversations with unread messages are returned. This filters on the conversation's unread state, so it combines with label — for example, unread conversations in the archive. (The unread label itself lives on messages, not conversations.)                                      |
| `--label <v1,v2,…>` | Filter to conversations carrying this label. Repeat the parameter to require several — only conversations carrying every listed label match. A placement label selects a folder (inbox, archive, spam, blocked); a custom label matches conversations in any folder. Defaults to inbox when omitted. |
| `--mailbox-id`      | Filter to conversations in a specific mailbox.                                                                                                                                                                                                                                                       |
| `--participant`     | Conversations involving this address — matches the sender or any recipient, as a case-insensitive contains-match, so a full address or any fragment of one works.                                                                                                                                    |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                                                                                                                     |
| `--subject`         | Conversations whose subject contains this text (case-insensitive).                                                                                                                                                                                                                                   |

#### Pagination

| Name               | Description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. |
| `--limit <n>`      | Maximum number of items to return per page.                                                                                                    |
| `--starting-after` | Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.  |

## 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 update`](/docs/cli/reference/email-threads-update) | Update a thread |