:::endpoint GET /v1/me/mail/messages

One row per message, newest first. See
[Reading mail](/docs/api/mail/overview) for why the unit is a message rather
than a conversation.

## Request

```bash
curl "https://api.proppertrading.com/v1/me/mail/messages?folder=inbox&limit=30" \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f"
```

| Parameter        | Description                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `folder`         | `inbox`, `drafts`, `sent`, `spam` or `trash`. Defaults to `inbox`                                             |
| `mailbox`        | One mailbox id. An id you cannot read falls back to all of yours                                              |
| `starred`        | `1` for starred only. Reaches across folders                                                                  |
| `unread`         | `1` for unread only. Narrows whatever else is selected and stays in the folder                                |
| `label`          | A label id of this environment. Reaches across folders. An id that names none of them is refused, not ignored |
| `assigned`       | `me`, for the conversations handed to you. Nothing else is accepted                                           |
| `q`              | A search. See the [operators](/docs/api/mail/overview)                                                        |
| `limit`          | Up to 100. Defaults to 20                                                                                     |
| `starting_after` | The `next_cursor` of the previous page                                                                        |

`starred`, `label`, `assigned` and `q` each make the list span the inbox, the
drafts and what was sent, and leave the bin and spam out. `folder` is then only
a fallback for where a search looks.

`unread` is the exception: it narrows, it never widens. Asking for unread mail
while looking at the inbox answers with unread inbox mail, not with everything
unread wherever it sits. It combines with the others, so `starred=1&unread=1` is
the starred mail you have not read.

## Response

```json
{
    "data": [
        {
            "id": 1552,
            "object": "mail_message",
            "thread_id": 611,
            "address_id": 32,
            "direction": "inbound",
            "from_email": "jamie@example.com",
            "from_name": "Jamie Rivera",
            "participants": ["Jamie Rivera"],
            "subject": "Payout request",
            "preview": "Hi, I passed the evaluation last week and wanted to ask",
            "labels": [{ "id": 10, "name": "Payouts", "color": "blue" }],
            "position": 1,
            "count": 3,
            "folder": "inbox",
            "is_starred": false,
            "is_read": true,
            "has_attachments": false,
            "message_at": "2026-08-19T13:30:36.000000Z",
            "assignee": { "id": 41, "name": "Han Aarts" },
            "answered": {
                "id": 41,
                "name": "Han Aarts",
                "at": "2026-08-19T14:02:11.000000Z"
            },
            "notes": 2
        }
    ],
    "meta": {
        "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey",
        "has_more": true,
        "next_cursor": "MjAyNi0wOC0xOSAxMzozMDozNi4wMDAwMDB8MTU1Mg"
    }
}
```

| Field               | Description                                                                                                                                                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `position`, `count` | Which message of its conversation this is, and how long that conversation runs. The only thing on a row that says there is an exchange at all                                                                                                                                                    |
| `participants`      | Who the row is about: the sender, or the recipients on something you sent                                                                                                                                                                                                                        |
| `preview`           | The first line of the text body, quotes stripped                                                                                                                                                                                                                                                 |
| `assignee`          | Whose job the conversation is: `{ "id", "name" }`, or null. Both belong to the conversation, not to this message, so every row of the same thread carries the same one. Change it with [assign](/docs/api/mail/assign), and see who it may go to with [list assignees](/docs/api/mail/assignees) |
| `notes`             | How many notes the team has left on the conversation. The notes themselves come with [the conversation](/docs/api/mail/message)                                                                                                                                                                  |
| `answered`          | Who answered it last and when, as `{ "id", "name", "at" }`, while that answer is still the last word in it. Null once somebody replies again                                                                                                                                                     |

## Paging

The cursor is opaque and carries both the date the list sorts on and the id that
breaks its ties. Pass the whole `next_cursor` back as `starting_after`; do not
build one yourself.

Offset paging is not offered. Mail arrives while you are walking a list, and
offsets silently skip and repeat rows when it does.

## Errors

| Status | Code                    | Meaning                                                                                         |
| ------ | ----------------------- | ----------------------------------------------------------------------------------------------- |
| 400    | `invalid_folder`        | Not one of the five folders                                                                     |
| 400    | `invalid_cursor`        | Not a cursor we handed out                                                                      |
| 400    | `invalid_limit`         | Not a positive integer                                                                          |
| 403    | `insufficient_scope`    | This device does not hold `mail:read`                                                           |
| 404    | `resource_not_found`    | The `label` id names no label in this environment. A label deleted elsewhere is the usual cause |
| 403    | `mailbox_not_permitted` | The account may not open a mailbox at all                                                       |