> ## 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, create, rename and delete a mailbox's folders (Gmail labels appear as folders).

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

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

Inbox comes first, then folders with a role, then the others by name. The list isn't paged: `has_more` is always `false`.

| Field | |
| - | - |
| `id` | The folder's `fld_…` id. Use it to [list its emails](/emails/list#one-folder) or to [move an email](/emails/update#move-to-a-folder) |
| `account_id` | The account it belongs to (`acc_…`) |
| `name` | The folder's name (for Gmail, the label name, e.g. `Clients`). A nested folder has its own name; its parent is in `parent_id` |
| `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` |
| `total_count` | How many emails it holds, as reported by the provider |

An email's `folders` lists `fld_…` ids. To know if an email is in the inbox, compare them with the id of the folder whose `role` is `INBOX`.

## One folder

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

The response is one folder object, as above.

## Create a folder

```bash theme={null}
curl -X POST "$EE_URL/api/v1/acc_ba1fa6938d8548298e8ce62e4b4b4e99/folders" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Customers" }'
```

<ParamField body="name" type="string" required>The folder's name.</ParamField>
<ParamField body="parent_id" type="string">The `fld_…` id of the folder to create it in.</ParamField>

The folder is created in the user's mailbox. The response (`201`) is the new folder object, and an `email.folder.create` event follows.

## Rename a folder

```bash theme={null}
curl -X PATCH "$EE_URL/api/v1/acc_ba1fa6938d8548298e8ce62e4b4b4e99/folders/fld_5e3b1c2d4a6f4e7b8c9d0a1b2c3d4e5f" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "VIP Customers" }'
```

The response is the renamed folder. It keeps its `id`, and an `email.folder.update` event follows.

## Delete a folder

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

```json Response theme={null}
{ "object": "FolderDeleted", "id": "fld_5e3b1c2d4a6f4e7b8c9d0a1b2c3d4e5f" }
```

<Warning>
  Deleting a folder also deletes **the emails in it**: IMAP has no labels to keep them under. Move the emails you want to keep first. An `email.folder.delete` event follows.
</Warning>

Only folders with the role `UNKNOWN` (the user's own folders) can be renamed or deleted. Inbox, Sent, Trash and other special folders get `400 errors/invalid_parameters`.

## Changes

Folders are kept in sync: folders the user creates, renames or deletes in their own email app show up on the next sync. Each change, made through the API or elsewhere, sends an event with the folder in `data.folder`:

| Event | When |
| - | - |
| `email.folder.create` | A folder or label was created |
| `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.