List mail folders
Lists every folder in the mailbox with its message and unread counts.
GET
/v1/folders
Permission
The key must be granted mail.folders.read
A key without it gets 403 insufficient_scope, with the missing permission named in details.
Returns every folder rather than a page. A mailbox has tens of them, so paging would mean writing a loop that never runs twice.
Request
curl https://api.veruapis.com/v1/folders \
-H "Authorization: Bearer vak_live_..."Response
| Field | Type | Description |
|---|---|---|
id |
string | Use this wherever an endpoint takes a folder_id. |
name |
string | The folder's name as it appears in webmail and over IMAP. |
message_count |
integer | Messages in the folder, including read ones. |
unread_count |
integer | Messages without the read flag. |
{
"data": [
{ "id": "43e01b3d-8560-475f-93e9-c8ce9ddbf1f2", "name": "Archive", "message_count": 1, "unread_count": 0 },
{ "id": "f76e4983-abfa-4691-9624-a641333b0f07", "name": "INBOX", "message_count": 98, "unread_count": 1 },
{ "id": "31a40082-7f94-4869-a58e-5fe13b98a76b", "name": "Sent", "message_count": 15, "unread_count": 0 }
],
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" },
"pagination": { "next_cursor": "eyJ1aWQiOjQyMTF9", "has_more": true, "limit": 25 }
}
Worth knowing
The complete set, not a page: a mailbox has tens of folders, and paging one would mean writing a loop that never runs twice. IMAP synchronisation state (uidvalidity, uidnext) is deliberately not published.
Errors
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- POST Create a draft
- POST Create a mail filter
- POST Create a mail folder
- DELETE Delete a draft
- DELETE Delete a mail filter
- DELETE Delete a mail folder
- DELETE Delete a message
- GET Download an attachment
- GET Get a message
- GET Get display preferences
- GET List attachments
- GET List drafts
- GET List mail filters
- GET List messages
- POST Move messages
- PUT Replace a draft
- POST Send an email
- POST Change flags and labels
- PATCH Rename a mail folder
- PATCH Update display preferences