:::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`, `archive`, `drafts`, `sent`, `spam` or `trash`. Defaults to `inbox` | | `mailbox` | One mailbox `id`, such as `mbx_w6sy3skvgydh5e3b`. An id you cannot read, a number included, 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, such as `lbl_p6m3x8b2k9q4w7td`. Reaches across folders. An id that names none of them, a number included, 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": [ { "object": "mail_message", "id": "msg_h3k8q2w7n4r9t5vx", "thread_id": "thr_c4n8w2k7p5x9m3qd", "address_id": "mbx_w6sy3skvgydh5e3b", "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": "lbl_p6m3x8b2k9q4w7td", "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": "usr_t7q3m8k2x9n4w6pb", "name": "Han Aarts" }, "answered": { "id": "usr_t7q3m8k2x9n4w6pb", "name": "Han Aarts", "at": "2026-08-19T14:02:11.000000Z" }, "notes": 2 } ], "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey", "has_more": true, "next_cursor": "MjAyNi0wOC0xOSAxMzozMDozNi4wMDAwMDB8bXNnX2gzazhxMnc3bjRyOXQ1dng" } } ``` | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | The message, such as `msg_h3k8q2w7n4r9t5vx`. What every other mail endpoint takes in its path. See [Ids](/docs/api/mail/overview) | | `thread_id` | The conversation, such as `thr_c4n8w2k7p5x9m3qd`. The same on every row of one exchange, so it is what to group on when an app wants to | | `address_id` | The mailbox the message sits in, the `id` from [list mailboxes](/docs/api/mail/mailboxes) | | `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` of the last row, which breaks its ties. Pass the whole `next_cursor` back as `starting_after`, and do not build one yourself. A cursor handed out before 2026-10-08 carries a number instead of an id and is refused with `invalid_cursor`. Start again from the first page. 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 six folders | | 400 | `invalid_cursor` | Not a cursor we handed out, or one from before 2026-10-08 | | 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, and a number is another | | 403 | `mailbox_not_permitted` | The account may not open a mailbox at all |