# API reference: Inbox

> Every inbox endpoint: what it takes, what it answers with, and which key it needs.

## List messages

`GET /api/v1/messages` · Secret key only

| Parameter | Type | Required | |
|---|---|---|---|
| `folder` | string |  | One of `inbox`, `archived`, `spam`. Defaults to inbox. |
| `page` | integer |  | A page number within the paginated result set. |
| `page_size` | integer |  | Number of results to return per page. |

Answers `200` with [PaginatedMessageList](#paginatedmessagelist).

## Send a message

`POST /api/v1/messages` · Any key · needs an `Idempotency-Key`

| Field | Type | Required | |
|---|---|---|---|
| `name` | string | yes |  |
| `email` | email | yes | Where the business's reply goes. |
| `subject` | string |  |  |
| `message` | string | yes |  |
| `page` | string |  | The page the form was on, as a path or an address. Only the path is kept. |
| `fields` | object |  | Up to 10 more answers your form asks for, such as a phone number, under keys of lowercase letters, digits and underscores. |
| `honeypot` | string |  | The value of a field people never see. Leave it empty; anything in it means a script filled the form, and the message is answered as received and not kept. |
| `filled_in_seconds` | double or null |  | How long the form was open before it was sent, measured in the browser. |
| `bot_check` | string |  | The Cloudflare Turnstile token, when the website has its keys set on the inbox settings. |

Answers `202` with [Received](#received).

## Fetch one message

`GET /api/v1/messages/{message_id}` · Secret key only

| Parameter | Type | Required | |
|---|---|---|---|
| `message_id` | uuid | yes |  |

Answers `200` with [Message](#message).

## Shapes

### PaginatedMessageList

| Field | Type | Always there | |
|---|---|---|---|
| `count` | integer | yes |  |
| `results` | list of [Message](#message) | yes |  |

### Received

| Field | Type | Always there | |
|---|---|---|---|
| `received` | boolean | yes |  |

### Message

| Field | Type | Always there | |
|---|---|---|---|
| `id` | uuid | yes |  |
| `livemode` | boolean | yes |  |
| `folder` | string | yes | One of `inbox`, `archived`, `spam`. |
| `spam_reason` | string | yes | One of `links`, `markup`, `too_fast`, `marked`. Empty unless in spam. |
| `read` | boolean | yes | Whether it has been opened in the inbox. |
| `received_at` | date-time | yes |  |
| `name` | string | yes |  |
| `email` | email | yes |  |
| `subject` | string | yes |  |
| `message` | string | yes |  |
| `page` | string | yes |  |
| `fields` | object | yes |  |