Dossiers

Les routes sont relatives à <PUBLIC_BASE_URL> ; les corps de requête et de réponse sont en JSON sauf mention contraire. L’authentification, les portées, la pagination et le format des erreurs sont décrits dans les guides de l’API REST.

GET /api/v1/folders

Lister les dossiers

Le rail des dossiers, lu dans le miroir et non chez le fournisseur : il reste affiché quand une boîte est déconnectée. Les rôles système sont toujours là, même vides ; les dossiers personnels seulement s’ils existent. Sans mailboxId, les boîtes du membre sont agrégées.

Accès — Session de membre ou clé d’API portant mailboxes:read.

Paramètres

Nom	Où	Type	Requis
mailboxId	requête	string	non

Réponses

200 — Les dossiers.

Champ	Type	Requis
folders	object[]	oui
capabilities	object	oui

Schéma JSON

{
  "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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.