> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruber.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders

> List, create, rename and delete the folders in a mailbox — the real IMAP folders, shared with every mail client you use.

Folders live on the mail server, not in Ruber's database. That is what makes
them real: a folder created here appears in Thunderbird, and one created in
Thunderbird appears here, because there is only ever one of it.

**Required permission:** Folders → Read for listing, Folders → Write for the rest.

<Note>
  **Renaming and deleting need the mail-server update**, which ships separately
  from the API. Until it lands, those two answer `502 mail_unavailable` and
  nothing changes. Listing and creating work now.
</Note>

<Note>
  **Folders are addressed by `path`, in the query string or the body — never as a
  URL segment.**

  A folder's identity is its IMAP path, and a path can contain the server's
  hierarchy delimiter (`/` here, `.` on plenty of other servers). Put through a
  URL segment it has to survive two rounds of encoding to arrive intact, and the
  failure mode is a caller addressing a folder that looks right and is not.
</Note>

## List folders

```
GET https://app.ruber.me/api/v1/folders?mailbox=you@yourdomain.com
```

```json theme={null}
{
  "data": [
    { "path": "INBOX", "name": "INBOX", "role": "inbox", "editable": false, "total": 32, "unread": 4 },
    { "path": "Sent", "name": "Sent", "role": "sent", "editable": false, "total": 0, "unread": 0 },
    { "path": "Receipts", "name": "Receipts", "role": null, "editable": true, "total": 118, "unread": 0 }
  ]
}
```

| Field              |                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `path`             | The IMAP path. What every other call here takes.                                         |
| `name`             | The leaf name, for display.                                                              |
| `role`             | `inbox`, `sent`, `drafts`, `junk`, `trash`, `archive` — or `null` for a folder you made. |
| `editable`         | Whether it can be renamed or deleted.                                                    |
| `total` / `unread` | Message counts.                                                                          |

`role` is read from the server's own SPECIAL-USE attribute, not guessed from
the name — Junk is "Spam" on some servers and Trash is "Deleted Items" on
others. **`editable` is false for every folder with a role**, including INBOX.
Renaming the Sent folder would not break a name, it would break "file a copy in
Sent" for every client the account uses.

## Create a folder

```
POST https://app.ruber.me/api/v1/folders
```

```bash theme={null}
curl -X POST https://app.ruber.me/api/v1/folders \
  -H "Authorization: Bearer rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"mailbox": "you@yourdomain.com", "name": "Receipts"}'
```

```json theme={null}
{ "path": "Receipts", "name": "Receipts", "role": null, "editable": true }
```

`201 Created`. **Use the returned `path`, do not assume it.** The server picks
it — the hierarchy delimiter and any namespace prefix are its to choose, so the
name you sent is not reliably the path that comes back.

Folders are flat. Separators in the name are replaced with spaces rather than
escaped, so `Work/2026` becomes one folder called `Work 2026` instead of
silently nesting under a parent you did not ask for.

Duplicate names are refused with `invalid_request`.

## Rename a folder

```
PATCH https://app.ruber.me/api/v1/folders
```

```bash theme={null}
curl -X PATCH https://app.ruber.me/api/v1/folders \
  -H "Authorization: Bearer rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"mailbox": "you@yourdomain.com", "path": "Receipts", "name": "Invoices"}'
```

Returns the new `path`, which again the server decides. Messages stay where
they are — a rename moves nothing.

Only folders with `"editable": true` can be renamed.

## Delete a folder

```
DELETE https://app.ruber.me/api/v1/folders?mailbox=you@yourdomain.com&path=Invoices
```

```json theme={null}
{ "deleted": true, "path": "Invoices", "messages_deleted": 118 }
```

<Warning>
  **This destroys the messages in the folder. There is no undo and nothing goes
  to Trash.**

  IMAP DELETE takes the messages with the folder — that is what the command
  means, and Ruber does not soften it by moving them somewhere first, because a
  "delete" that silently relocates a hundred messages into Trash is its own
  surprise. `messages_deleted` tells you afterwards how many went.

  Move anything you want to keep first, with
  [`PATCH /v1/messages/{uid}`](/api/messages#update-a-message).
</Warning>

Refused for anything with a `role`, and refused for a folder with folders
inside it — delete those first. A server that stores children inside their
parent would otherwise take a whole tree with one call.

## Errors

| Code               | HTTP  | Cause                                                                                                                   |
| ------------------ | ----- | ----------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`  | `400` | Missing `mailbox`, `name` or `path`; a duplicate name; a folder with a role; a folder with children; a Private mailbox. |
| `unauthorized`     | `401` | Missing, malformed, unknown or revoked key.                                                                             |
| `forbidden`        | `403` | The key lacks `folders:read` or `folders:write`.                                                                        |
| `not_found`        | `404` | No such mailbox on this account, or no folder with that path.                                                           |
| `rate_limited`     | `429` | Over 600 requests a minute, or over 240 folder creations a minute.                                                      |
| `mail_unavailable` | `502` | The mail server did not answer. Nothing changed.                                                                        |

See [Errors](/api/introduction#errors) for the full response shape.