---
title: Messages
---

## List Messages
List messages across all inboxes for the tenant (Agentry extension).
**Endpoint**: `GET /agent/v0/messages`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `after` | query | string | No |  |
| `ascending` | query | boolean | No |  |
| `before` | query | string | No |  |
| `inbox_id` | query | string | No | When set, list messages only for this inbox. |
| `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`

Messages

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. |
| `messages` | array\<object\> | Yes | Ordered by `timestamp` descending. |
| `next_page_token` | string | No | Page token for pagination. |

##### Example

```json
{
  "count": 0,
  "limit": 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",
      "from": "<string>",
      "headers": {},
      "in_reply_to": "<string>",
      "inbox_id": "<string>",
      "labels": [
        "<string>"
      ],
      "message_id": "<string>",
      "preview": "<string>",
      "references": [
        "<string>"
      ],
      "size": 0,
      "subject": "<string>",
      "thread_id": "<string>",
      "timestamp": "2026-01-01T00:00:00Z",
      "to": [
        "<string>"
      ],
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_page_token": "<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>"
}
```


## Get Message
Get a message by ID without inbox in the path (Agentry extension).
**Endpoint**: `GET /agent/v0/messages/{message_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

### Responses

#### `200`

Message

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments in message. |
| `bcc` | array\<string\> | No | Addresses of BCC recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `cc` | array\<string\> | No | Addresses of CC recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `created_at` | string | Yes | Time at which message was created. |
| `extracted_html` | string | No | Extracted new HTML content. |
| `extracted_text` | string | No | Extracted new text content. |
| `from` | string | Yes | Address of sender. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `headers` | object | No | Headers in message. |
| `html` | string | No | HTML body of message. |
| `in_reply_to` | string | No | ID of message being replied to. |
| `inbox_id` | string | Yes | The ID of the inbox. |
| `labels` | array\<string\> | Yes | Labels of message. |
| `message_id` | string | Yes | ID of message. |
| `preview` | string | No | Text preview of message. |
| `references` | array\<string\> | No | IDs of previous messages in thread. |
| `reply_to` | array\<string\> | No | Reply-to addresses. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `size` | integer | Yes | Size of message in bytes. |
| `subject` | string | No | Subject of message. |
| `text` | string | No | Plain text body of message. |
| `thread_id` | string | Yes | ID of thread. |
| `timestamp` | string | Yes | Time at which message was sent or drafted. |
| `to` | array\<string\> | Yes | Addresses of recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `updated_at` | string | Yes | Time at which message was last updated. |

##### Example

```json
{
  "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"
}
```

#### `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 Message
Update message labels (Agentry extension).
**Endpoint**: `PATCH /agent/v0/messages/{message_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `add_labels` | object | No | Label or list of labels. |
| `remove_labels` | object | No | Label or list of labels. |

#### Example

```json
{
  "add_labels": null,
  "remove_labels": null
}
```

### Responses

#### `200`

Updated message

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments in message. |
| `bcc` | array\<string\> | No | Addresses of BCC recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `cc` | array\<string\> | No | Addresses of CC recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `created_at` | string | Yes | Time at which message was created. |
| `extracted_html` | string | No | Extracted new HTML content. |
| `extracted_text` | string | No | Extracted new text content. |
| `from` | string | Yes | Address of sender. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `headers` | object | No | Headers in message. |
| `html` | string | No | HTML body of message. |
| `in_reply_to` | string | No | ID of message being replied to. |
| `inbox_id` | string | Yes | The ID of the inbox. |
| `labels` | array\<string\> | Yes | Labels of message. |
| `message_id` | string | Yes | ID of message. |
| `preview` | string | No | Text preview of message. |
| `references` | array\<string\> | No | IDs of previous messages in thread. |
| `reply_to` | array\<string\> | No | Reply-to addresses. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `size` | integer | Yes | Size of message in bytes. |
| `subject` | string | No | Subject of message. |
| `text` | string | No | Plain text body of message. |
| `thread_id` | string | Yes | ID of thread. |
| `timestamp` | string | Yes | Time at which message was sent or drafted. |
| `to` | array\<string\> | Yes | Addresses of recipients. In format `username@domain.com` or `Display Name \<username@domain.com\>`. |
| `updated_at` | string | Yes | Time at which message was last updated. |

##### Example

```json
{
  "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"
}
```

#### `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 Message Attachment
Get attachment metadata and presigned URL (Agentry extension).
**Endpoint**: `GET /agent/v0/messages/{message_id}/attachments/{attachment_id}`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

### Responses

#### `200`

Attachment

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>"
}
```


## Forward Message
Forward a message (Agentry extension).
**Endpoint**: `POST /agent/v0/messages/{message_id}/forward`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments to include in message. |
| `bcc` | object | No | BCC recipient address or addresses. |
| `cc` | object | No | CC recipient address or addresses. |
| `headers` | object | No | Headers to include in message. |
| `html` | string | No | HTML body of message. |
| `labels` | array\<string\> | No | Labels of message. |
| `reply_to` | object | No | Reply-to address or addresses. |
| `subject` | string | No | Subject of message. |
| `text` | string | No | Plain text body of message. |
| `to` | object | No | Recipient address or addresses. |

#### Example

```json
{
  "attachments": [
    {
      "content": "<string>",
      "content_disposition": "inline",
      "content_id": "<string>",
      "content_type": "<string>",
      "filename": "<string>",
      "url": "<string>"
    }
  ],
  "bcc": null,
  "cc": "[Circular]",
  "headers": {},
  "html": "<string>",
  "labels": [
    "<string>"
  ],
  "reply_to": "[Circular]",
  "subject": "<string>",
  "text": "<string>",
  "to": "[Circular]"
}
```

### Responses

#### `200`

Sent message identifiers

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message_id` | string | Yes | ID of message. |
| `thread_id` | string | Yes | ID of thread. |

##### Example

```json
{
  "message_id": "<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>"
}
```

#### `403`

Error response with status 403

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>"
}
```

#### `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 Message Raw
Download raw RFC822 message (Agentry extension).
**Endpoint**: `GET /agent/v0/messages/{message_id}/raw`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

### Responses

#### `200`

Presigned URL for raw message

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `download_url` | string | Yes | S3 presigned URL to download the raw message. Expires at expires_at. |
| `expires_at` | string | Yes | Time at which the download URL expires. |
| `message_id` | string | Yes | ID of message. |
| `size` | integer | Yes | Size of message in bytes. |

##### Example

```json
{
  "download_url": "<string>",
  "expires_at": "2026-01-01T00:00:00Z",
  "message_id": "<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>"
}
```


## Reply to Message
Reply to a message (Agentry extension).
**Endpoint**: `POST /agent/v0/messages/{message_id}/reply`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments to include in message. |
| `bcc` | object | No | BCC recipient address or addresses. |
| `cc` | object | No | CC recipient address or addresses. |
| `headers` | object | No | Headers to include in message. |
| `html` | string | No | HTML body of message. |
| `labels` | array\<string\> | No | Labels of message. |
| `reply_all` | boolean | No | Reply to all recipients of the original message. |
| `reply_to` | object | No | Reply-to address or addresses. |
| `text` | string | No | Plain text body of message. |
| `to` | object | No | Recipient address or addresses. |

#### Example

```json
{
  "attachments": [
    {
      "content": "<string>",
      "content_disposition": "inline",
      "content_id": "<string>",
      "content_type": "<string>",
      "filename": "<string>",
      "url": "<string>"
    }
  ],
  "bcc": null,
  "cc": "[Circular]",
  "headers": {},
  "html": "<string>",
  "labels": [
    "<string>"
  ],
  "reply_all": true,
  "reply_to": "[Circular]",
  "text": "<string>",
  "to": "[Circular]"
}
```

### Responses

#### `200`

Sent message identifiers

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message_id` | string | Yes | ID of message. |
| `thread_id` | string | Yes | ID of thread. |

##### Example

```json
{
  "message_id": "<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>"
}
```

#### `403`

Error response with status 403

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>"
}
```

#### `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>"
}
```


## Reply All to Message
Reply-all to a message (Agentry extension).
**Endpoint**: `POST /agent/v0/messages/{message_id}/reply-all`
**Authentication**: `Authorization: Bearer <token>`
### Parameters

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

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `attachments` | array\<object\> | No | Attachments to include in message. |
| `headers` | object | No | Headers to include in message. |
| `html` | string | No | HTML body of message. |
| `labels` | array\<string\> | No | Labels of message. |
| `reply_to` | object | No | Reply-to address or addresses. |
| `text` | string | No | Plain text body of message. |

#### Example

```json
{
  "attachments": [
    {
      "content": "<string>",
      "content_disposition": "inline",
      "content_id": "<string>",
      "content_type": "<string>",
      "filename": "<string>",
      "url": "<string>"
    }
  ],
  "headers": {},
  "html": "<string>",
  "labels": [
    "<string>"
  ],
  "reply_to": null,
  "text": "<string>"
}
```

### Responses

#### `200`

Sent message identifiers

Content-Type: `application/json`

##### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message_id` | string | Yes | ID of message. |
| `thread_id` | string | Yes | ID of thread. |

##### Example

```json
{
  "message_id": "<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>"
}
```

#### `403`

Error response with status 403

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>"
}
```

#### `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>"
}
```