---
title: "threads"
description: "Conversation threads. The `machinemail threads` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/threads"
---

# threads

> Conversation threads. The `machinemail threads` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/threads

Conversation threads. Also spelled `thread`.

| Command                             | Summary        |
| ----------------------------------- | -------------- |
| [`threads delete`](#threads-delete) | Delete thread  |
| [`threads get`](#threads-get)       | Get thread     |
| [`threads list`](#threads-list)     | List threads   |
| [`threads search`](#threads-search) | Search threads |
| [`threads update`](#threads-update) | Update thread  |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## threads delete

Delete thread.

Also: `machinemail threads rm`.

Permanently deletes the thread and its messages (up to 500).

Requires the thread\_delete permission.

```bash
machinemail threads delete <thread-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<thread-id>` | `string` | required | ID of the thread. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Use this inbox's scoped route. |
| `--pod <pod-id>` | `string` |  | Use this pod's scoped route. |

#### Examples

```bash
machinemail threads delete thd_01m4fy8h340001pp6c74x4688h
machinemail threads delete thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev
```

#### API

- [`DELETE /v0/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#delete-thread)
- [`DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#delete-thread) with `--inbox`
- [`DELETE /v0/pods/{pod_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#delete-thread-in-pod) with `--pod`

## threads get

Get thread.

The thread with its messages, which carry their bodies and trust reports. Messages come in pages of --limit (default and maximum 500): the first page has the newest messages, oldest first within the page; follow next\_page\_token for older ones.

Requires the thread\_read permission.

```bash
machinemail threads get <thread-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<thread-id>` | `string` | required | ID of the thread. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--limit <n>` | `integer` |  | Maximum number of messages to return. Default and maximum 500. |
| `--page-token <value>` | `string` |  | next_page_token from the previous response: the next, older page of messages. |

#### Examples

```bash
machinemail threads get thd_01m4fy8h340001pp6c74x4688h
machinemail threads get thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#get-thread)
- [`GET /v0/inboxes/{inbox_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#get-thread) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#get-thread-in-pod) with `--pod`

## threads list

List threads.

Also: `machinemail threads ls`.

Threads, most recently active first. Pass --q to keep only threads with a message matching the words.

Threads with a spam, blocked, trash, quarantined or unauthenticated message are hidden unless you pass the matching --include-\* flag or ask for the label in --label.

Requires the thread\_read permission.

```bash
machinemail threads list [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--limit <n>` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>` | `string` |  | next_page_token from the previous page. |
| `--ascending` | `boolean` |  | Sort oldest first. |
| `--label <value>` | `string[]` |  | Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them. Repeat the flag for several values. |
| `--before <time>` | `string` |  | Only items with a timestamp before this time. |
| `--after <time>` | `string` |  | Only items with a timestamp after this time. |
| `--include-spam` | `boolean` |  | Include spam (needs label_spam_read; ignored without it). |
| `--include-blocked` | `boolean` |  | Include blocked mail (needs label_blocked_read; ignored without it). |
| `--include-unauthenticated` | `boolean` |  | Include unauthenticated mail (needs label_unauthenticated_read; ignored without it). |
| `--include-trash` | `boolean` |  | Include trash (needs label_trash_read; ignored without it). |
| `--include-quarantine` | `boolean` |  | Include threads that have a quarantined message. |
| `--q <value>` | `string` |  | Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages. |
| `--all` | `boolean` |  | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail threads list
machinemail threads list --inbox agent@machinemail.dev
machinemail threads list --all --json | jq '.threads | length'
```

#### API

- [`GET /v0/threads`](https://machinemail.dev/docs/reference/api/threads#list-threads)
- [`GET /v0/inboxes/{inbox_id}/threads`](https://machinemail.dev/docs/reference/api/threads#list-threads) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads`](https://machinemail.dev/docs/reference/api/threads#list-threads-in-pod) with `--pod`

## threads search

Search threads.

Threads with a message whose subject, sender, recipients, body or attachment file names contain every word of --q, ordered by thread activity (not ranked by relevance). Scans the newest 500 matching messages; the response has truncated: true when it hit that cap.

Requires the thread\_read permission.

```bash
machinemail threads search [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--q <value>` | `string` | required | Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages. |
| `--limit <n>` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>` | `string` |  | next_page_token from the previous page. |
| `--before <time>` | `string` |  | Only items with a timestamp before this time. |
| `--after <time>` | `string` |  | Only items with a timestamp after this time. |
| `--ascending` | `boolean` |  | Sort oldest first. |
| `--label <value>` | `string[]` |  | Only threads with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them. Repeat the flag for several values. |
| `--include-spam` | `boolean` |  | Include threads with spam (needs label_spam_read; ignored without it). |
| `--include-blocked` | `boolean` |  | Include threads with blocked mail (needs label_blocked_read; ignored without it). |
| `--include-unauthenticated` | `boolean` |  | Include threads with unauthenticated mail (needs label_unauthenticated_read; ignored without it). |
| `--include-trash` | `boolean` |  | Include threads with trash (needs label_trash_read; ignored without it). |
| `--include-quarantine` | `boolean` |  | Include threads that have a quarantined message. |
| `--all` | `boolean` |  | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail threads search --q invoice
machinemail threads search --q invoice --inbox agent@machinemail.dev
machinemail threads search --q invoice --all --json | jq '.threads | length'
```

#### API

- [`GET /v0/threads/search`](https://machinemail.dev/docs/reference/api/threads#search-threads)
- [`GET /v0/inboxes/{inbox_id}/threads/search`](https://machinemail.dev/docs/reference/api/threads#search-threads) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads/search`](https://machinemail.dev/docs/reference/api/threads#search-threads-in-pod) with `--pod`

## threads update

Update thread.

Adds and removes labels on every message in the thread (up to 500 messages); the thread labels are their union. Labels are free strings, system labels included. Returns the updated thread without messages.

Requires the message\_update permission.

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

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<thread-id>` | `string` | required | ID of the thread. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Use this inbox's scoped route. |
| `--pod <pod-id>` | `string` |  | Use this pod's scoped route. |
| `--add-label <value>` | `string[]` |  | Label or labels to add to every message in the thread. Repeat the flag for several values. |
| `--remove-label <value>` | `string[]` |  | Label or labels to remove from every message in the thread. Applied after --add-label. Repeat the flag for several values. |
| `-d, --data <json|@file|->` | `string` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail threads update thd_01m4fy8h340001pp6c74x4688h
machinemail threads update thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev
machinemail threads update thd_01m4fy8h340001pp6c74x4688h --data @body.json
```

#### API

- [`PATCH /v0/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#update-thread)
- [`PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#update-thread) with `--inbox`
- [`PATCH /v0/pods/{pod_id}/threads/{thread_id}`](https://machinemail.dev/docs/reference/api/threads#update-thread-in-pod) with `--pod`