List messages

Lists message summaries in a folder, newest first, with cursor pagination.

GET /v1/messages

Permission

The key must be granted mail.messages.read

A key without it gets 403 insufficient_scope, with the missing permission named in details.

At least one of folder_id, flag, label or unread is required. An unfiltered list would be the whole mailbox, so it is refused rather than quietly narrowed to the inbox. Recipients are not on the summary; fetch the message for to and cc.

Query parameters

Field	Type	Description
`folder_id`	string	Limit to one folder. Repeat it for several.
`flag`	string	Only messages carrying all the flags listed. Repeat for several. `readstarredanswereddraftdeleted`
`label`	string	Only messages carrying this user-defined label. Repeat for several.
`unread`	boolean	Only messages without the read flag.
`limit`	integer	Rows in this page, 1 to 200. Defaults to `50`
`cursor`	string	The next_cursor from the previous page.

Request

curl https://api.veruapis.com/v1/messages?folder_id=f76e4983-abfa-4691-9624-a641333b0f07&unread=true&limit=25 \
  -H "Authorization: Bearer vak_live_..."

Response

Field	Type	Description
`id`	string	Use this wherever an endpoint takes a message id.
`folder_id`	string	Where the message is now. Needed to change its flags or move it.
`thread_id`	string	Groups a conversation. Absent on mail that predates threading, so do not treat missing as a thread of one.
`subject`	string
`from`	string	The sender, as written on the message: "Name <address>".
`date`	RFC 3339	When the server received it, not when the sender wrote it.
`size`	integer	Bytes of the whole message, including attachments.
`flags`	object	Which system flags the message carries. Its fields are below.
`labels`	string[]	User-defined labels. Empty rather than absent when there are none.
`message_id`	string	The RFC 5322 Message-Id header, for threading a reply.

The flags

Field	Type	Description
`read`	boolean	The IMAP Seen flag. Absent means unread.
`starred`	boolean	The IMAP Flagged bit. One star, not a colour.
`answered`	boolean	Set automatically when you reply through this API.
`draft`	boolean
`deleted`	boolean	Marked for removal but still present until the folder is expunged.

{
  "data": [
  {
    "id": "d9038c5a-3bca-4e27-a016-4b7ad1416948",
    "folder_id": "f76e4983-abfa-4691-9624-a641333b0f07",
    "thread_id": "a0650fe0-97e6-461a-8772-e4e2deadee3d",
    "subject": "Quarterly numbers",
    "from": "Alice Ng <[email protected]>",
    "date": "2026-09-03T08:11:53Z",
    "size": 31460,
    "flags": { "read": true, "starred": false, "answered": false, "draft": false, "deleted": false },
    "labels": [],
    "message_id": "<[email protected]>"
  }
],
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" },
  "pagination": { "next_cursor": "eyJ1aWQiOjQyMTF9", "has_more": true, "limit": 25 }
}

Worth knowing

At least one filter is required: folder_id, flag, label or unread=true. An unfiltered list would be the whole mailbox, so it is refused rather than silently narrowed. Note there is no recipient here — the summary carries the sender only; fetch the message for to and cc.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

GET `/v1/messages`

Your API key Used once, never stored. Query