> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonpost-developer.27communication.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders

> List a mailbox's folders (Gmail labels appear as folders).

```bash theme={null}
curl "$EE_URL/api/v1/folders?account_id=acc_ba1fa6938d8548298e8ce62e4b4b4e99" -H "X-API-KEY: $EE_KEY"
```

```json Response theme={null}
{
  "object": "Folders",
  "data": [
    {
      "object": "Folder",
      "id": "fld_0b7e2d4c1a3f4e5b8c9d7f6e5d4c3b2a",
      "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
      "provider_id": "INBOX",
      "name": "INBOX",
      "role": "INBOX",
      "parent_id": null,
      "nb_mails": 1284,
      "nb_unread": 12
    }
  ],
  "has_more": false
}
```

Inbox comes first, then folders with a role, then the others by name. Leave out `account_id` to list the folders of every account. The list isn't paged: `has_more` is always `false`.

| Field | |
| - | - |
| `id` | The folder's `fld_…` id. Use it with `GET /api/v1/emails?folder=…` or to [move an email](/emails/update) |
| `account_id` | The account it belongs to (`acc_…`) |
| `provider_id` | The IMAP folder path (for Gmail, the label name, e.g. `Clients` or `[Gmail]/Sent Mail`) |
| `name` | The folder's name |
| `role` | `INBOX`, `SENT`, `DRAFTS`, `TRASH`, `SPAM`, `ARCHIVE`, `ALL`, `IMPORTANT`, `STARRED`, or `UNKNOWN` for the user's own folders. See [Core concepts](/concepts#folder-and-role) |
| `parent_id` | The parent folder's `fld_…` id, for nested folders, or `null` |
| `nb_mails`, `nb_unread` | Counts reported by the provider |

## One folder

```bash theme={null}
curl "$EE_URL/api/v1/folders/fld_0b7e2d4c1a3f4e5b8c9d7f6e5d4c3b2a" -H "X-API-KEY: $EE_KEY"
```

The response is one folder object, as above.

## Changes

Folders are kept in sync: folders the user creates, renames or deletes show up on the next sync. Each change sends an event with the folder in `data.folder`:

| Event | When |
| - | - |
| `email.folder.create` | The user created a folder or label |
| `email.folder.update` | A folder was renamed, or its role or parent changed |
| `email.folder.delete` | A folder was deleted |

The folders a new account already has don't send events when it first syncs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.