Folders

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET /api/v1/folders

List folders

The folder rail, read from the mirror and not from the provider, so it stays available when a mailbox is disconnected. The system roles are always present, even empty; personal folders only when they exist. Without mailboxId, the member’s mailboxes are aggregated.

Access — Member session or API key with scope mailboxes:read.

Parameters

Name	In	Type	Required
mailboxId	query	string	no

Responses

200 — The folders.

Field	Type	Required
folders	object[]	yes
capabilities	object	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "folders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "minLength": 1, "maxLength": 256 },
          "role": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "inbox",
                  "starred",
                  "sent",
                  "drafts",
                  "archive",
                  "all",
                  "spam",
                  "trash"
                ]
              },
              { "type": "null" }
            ]
          },
          "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "parentKey": {
            "anyOf": [
              { "type": "string", "minLength": 1, "maxLength": 256 },
              { "type": "null" }
            ]
          },
          "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "depth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "totalCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
        },
        "required": [
          "key",
          "role",
          "label",
          "name",
          "parentKey",
          "color",
          "depth",
          "unreadCount",
          "totalCount"
        ],
        "additionalProperties": false
      }
    },
    "capabilities": {
      "type": "object",
      "properties": { "permanentDelete": { "type": "boolean" } },
      "required": [ "permanentDelete" ],
      "additionalProperties": false
    }
  },
  "required": [ "folders", "capabilities" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.