# 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](/content/docs/cli/commands#global-flags/index.html).

## 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}`](/content/docs/reference/api/threads#delete-thread/index.html)
- [`DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}`](/content/docs/reference/api/threads#delete-thread/index.html) with `--inbox`
- [`DELETE /v0/pods/{pod_id}/threads/{thread_id}`](/content/docs/reference/api/threads#delete-thread-in-pod/index.html) 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

#### 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}`](/content/docs/reference/api/threads#get-thread/index.html)
- [`GET /v0/inboxes/{inbox_id}/threads/{thread_id}`](/content/docs/reference/api/threads#get-thread/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads/{thread_id}`](/content/docs/reference/api/threads#get-thread-in-pod/index.html) 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`](/content/docs/reference/api/threads#list-threads/index.html)
- [`GET /v0/inboxes/{inbox_id}/threads`](/content/docs/reference/api/threads#list-threads/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads`](/content/docs/reference/api/threads#list-threads-in-pod/index.html) 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`](/content/docs/reference/api/threads#search-threads/index.html)
- [`GET /v0/inboxes/{inbox_id}/threads/search`](/content/docs/reference/api/threads#search-threads/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/threads/search`](/content/docs/reference/api/threads#search-threads-in-pod/index.html) 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

#### 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}`](/content/docs/reference/api/threads#update-thread/index.html)
- [`PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}`](/content/docs/reference/api/threads#update-thread/index.html) with `--inbox`
- [`PATCH /v0/pods/{pod_id}/threads/{thread_id}`](/content/docs/reference/api/threads#update-thread-in-pod/index.html) with `--pod`