Folders

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.

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.

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.

List folders

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

{
  "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

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"}'

{ "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

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

{ "deleted": true, "path": "Invoices", "messages_deleted": 118 }

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}.

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 for the full response shape.

Start here

Using Ruber

API

Reference

List folders

Create a folder

Rename a folder

Delete a folder

Errors

​List folders

​Create a folder

​Rename a folder

​Delete a folder

​Errors

List folders

Create a folder

Rename a folder

Delete a folder

Errors