Skip to content
calternal docs

List Mail folders

GET
/api/v1/mail/accounts/{id}/folders
curl --request GET \
  --url https://example.com/api/v1/mail/accounts/example/folders \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User. It returns the account’s folders and shows which folders can contain messages. It returns 404 when the account is missing. Route: /api/v1/mail/accounts/{id}/folders. Inputs: id. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
Array<object>
object
account_id
required
string
backfill_complete
required
boolean
backfill_top_uid
integer | null format: int32
delimiter
string | null
id
required
string
low_water_uid
integer | null format: int32
message_count
required
integer format: int64
name
required
string
selectable
required
boolean
special_use
required
string
uid_validity
integer | null format: int32
unread_count
required

Live messages in this folder without \Seen (sidebar badge, #396).

integer format: int64
Examplegenerated
[
  {
    "account_id": "example",
    "backfill_complete": true,
    "backfill_top_uid": 1,
    "delimiter": "example",
    "id": "example",
    "low_water_uid": 1,
    "message_count": 1,
    "name": "example",
    "selectable": true,
    "special_use": "example",
    "uid_validity": 1,
    "unread_count": 1
  }
]

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}