---
title: Threads
---

## List Threads
**Endpoint**: `GET /agent/v0/threads`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `after` | query | string | No |  |
| `ascending` | query | boolean | No |  |
| `before` | query | string | No |  |
| `include_blocked` | query | boolean | No |  |
| `include_spam` | query | boolean | No |  |
| `include_trash` | query | boolean | No |  |
| `labels` | query | array\<string\> | No |  |
| `limit` | query | integer | No |  |
| `page_token` | query | string | No |  |

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `count` | integer | Yes | Number of items returned. |
| `limit` | integer | No | Limit of number of items returned. |
| `next_page_token` | string | No | Page token for pagination. |
| `threads` | array\<object\> | Yes | Ordered by `timestamp` descending. |

##### Example

```json
{
  "count": 0,
  "limit": 0,
  "next_page_token": "<string>",
  "threads": [
    {
      "attachments": [
        {
          "attachment_id": "<string>",
          "content_disposition": "inline",
          "content_id": "<string>",
          "content_type": "<string>",
          "filename": "<string>",
          "size": 0
        }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "inbox_id": "<string>",
      "labels": [
        "<string>"
      ],
      "last_message_id": "<string>",
      "message_count": 0,
      "preview": "<string>",
      "received_timestamp": "2026-01-01T00:00:00Z",
      "recipients": [
        "<string>"
      ],
      "senders": [
        "<string>"
      ],
      "sent_timestamp": "2026-01-01T00:00:00Z",
      "size": 0,
      "subject": "<string>",
      "thread_id": "<string>",
      "timestamp": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Get Thread
**Endpoint**: `GET /agent/v0/threads/{thread_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `thread_id` | path | string | Yes |  |

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments in thread. |
| `created_at` | string | Yes | Time at which thread was created. |
| `inbox_id` | string | Yes | The ID of the inbox. |
| `labels` | array\<string\> | Yes | Labels of thread. |
| `last_message_id` | string | Yes | ID of last message in thread. |
| `message_count` | integer | Yes | Number of messages in thread. |
| `messages` | array\<object\> | Yes | Messages in thread. Ordered by `timestamp` ascending. |
| `preview` | string | No | Text preview of last message in thread. |
| `received_timestamp` | string | No | Timestamp of last received message. |
| `recipients` | array\<string\> | Yes | Recipients in thread. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `senders` | array\<string\> | Yes | Senders in thread. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `sent_timestamp` | string | No | Timestamp of last sent message. |
| `size` | integer | Yes | Size of thread in bytes. |
| `subject` | string | No | Subject of thread. |
| `thread_id` | string | Yes | ID of thread. |
| `timestamp` | string | Yes | Timestamp of last sent or received message. |
| `updated_at` | string | Yes | Time at which thread was last updated. |

##### Example

```json
{
  "attachments": [
    {
      "attachment_id": "<string>",
      "content_disposition": "inline",
      "content_id": "<string>",
      "content_type": "<string>",
      "filename": "<string>",
      "size": 0
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "inbox_id": "<string>",
  "labels": [
    "<string>"
  ],
  "last_message_id": "<string>",
  "message_count": 0,
  "messages": [
    {
      "attachments": [
        {
          "attachment_id": "<string>",
          "content_disposition": "inline",
          "content_id": "<string>",
          "content_type": "<string>",
          "filename": "<string>",
          "size": 0
        }
      ],
      "bcc": [
        "<string>"
      ],
      "cc": [
        "<string>"
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "extracted_html": "<string>",
      "extracted_text": "<string>",
      "from": "<string>",
      "headers": {},
      "html": "<string>",
      "in_reply_to": "<string>",
      "inbox_id": "<string>",
      "labels": [
        "<string>"
      ],
      "message_id": "<string>",
      "preview": "<string>",
      "references": [
        "<string>"
      ],
      "reply_to": [
        "<string>"
      ],
      "size": 0,
      "subject": "<string>",
      "text": "<string>",
      "thread_id": "<string>",
      "timestamp": "2026-01-01T00:00:00Z",
      "to": [
        "<string>"
      ],
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "preview": "<string>",
  "received_timestamp": "2026-01-01T00:00:00Z",
  "recipients": [
    "<string>"
  ],
  "senders": [
    "<string>"
  ],
  "sent_timestamp": "2026-01-01T00:00:00Z",
  "size": 0,
  "subject": "<string>",
  "thread_id": "<string>",
  "timestamp": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Update Thread
Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.
**Endpoint**: `PATCH /agent/v0/threads/{thread_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `thread_id` | path | string | Yes |  |

### Request Body
Content-Type: `application/json`
#### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `add_labels` | array\<string\> | No | Labels to add to thread. Cannot be system labels. |
| `remove_labels` | array\<string\> | No | Labels to remove from thread. Cannot be system labels. Takes priority over `add_labels` (in the event of duplicate labels passed in). |

#### Example

```json
{
  "add_labels": [
    "<string>"
  ],
  "remove_labels": [
    "<string>"
  ]
}
```

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `labels` | array\<string\> | Yes | Labels of thread. |
| `thread_id` | string | Yes | ID of thread. |

##### Example

```json
{
  "labels": [
    "<string>"
  ],
  "thread_id": "<string>"
}
```

#### `400`

Error response with status 400

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `errors` | object | Yes | Validation errors. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "errors": null,
  "name": "<string>"
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```

#### `422`

Error response with status 422

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Delete Thread
Moves the thread to trash by adding a trash label to all messages. If the thread is already in trash, it will be permanently deleted. Use `permanent=true` to force permanent deletion.
**Endpoint**: `DELETE /agent/v0/threads/{thread_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `thread_id` | path | string | Yes |  |
| `permanent` | query | boolean | No | If true, permanently delete the thread instead of moving to trash. |

### Responses

#### `200`

Successful response

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```


## Get Attachment
**Endpoint**: `GET /agent/v0/threads/{thread_id}/attachments/{attachment_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `attachment_id` | path | string | Yes |  |
| `thread_id` | path | string | Yes |  |

### Responses

#### `200`

Response with status 200

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachment_id` | string | Yes | ID of attachment. |
| `content_disposition` | `inline` \| `attachment` | No | Content disposition of attachment. |
| `content_id` | string | No | Content ID of attachment. |
| `content_type` | string | No | Content type of attachment. |
| `download_url` | string | Yes | URL to download the attachment. |
| `expires_at` | string | Yes | Time at which the download URL expires. |
| `filename` | string | No | Filename of attachment. |
| `size` | integer | Yes | Size of attachment in bytes. |

##### Example

```json
{
  "attachment_id": "<string>",
  "content_disposition": "inline",
  "content_id": "<string>",
  "content_type": "<string>",
  "download_url": "<string>",
  "expires_at": "2026-01-01T00:00:00Z",
  "filename": "<string>",
  "size": 0
}
```

#### `404`

Error response with status 404

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | Yes | Error message. |
| `name` | string | Yes | Name of error. |

##### Example

```json
{
  "message": "<string>",
  "name": "<string>"
}
```