POST /api/v1/accounts/{accountId}/folders
Create a folder in an email account, or return the existing folder with that name. In Gmail, the folder is a label. System folder names, including Inbox, Sent and Trash, are rejected.
Create a folder in an email account, or return the existing folder with that name. In Gmail, the folder is a label. System folder names, including Inbox, Sent and Trash, are rejected.
Authentication
Pass a Fluxmail member session or API key as a bearer token. API keys apply their mailbox scope and permissions to the request.
Request
curl 'http://localhost:8977/api/v1/accounts/acct_123/folders' \
-X POST \
-H "Authorization: Bearer $FLUXMAIL_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"name": "string"
}'Parameters
| Name | Location | Required | Type | Details |
|---|---|---|---|---|
accountId | path | Yes | string | Minimum length: 1. |
Request body
Content type: application/json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "Folder name, or the full path of a subfolder with the separator the account uses in its folder names, such as Projects/2026. Missing parent folders are created too."
}
},
"required": [
"name"
],
"additionalProperties": false
}Responses
| Status | Description | Content type |
|---|---|---|
200 | The new folder, or the existing folder with that name | application/json |
400 | Invalid request | application/json |
401 | Authentication required | application/json |
403 | Permission or plan denied | application/json |
404 | Resource not found | application/json |
409 | Request conflict | application/json |
422 | Unsupported capability | application/json |
429 | Provider rate limit | application/json |
500 | Internal error | application/json |
503 | Provider unavailable | application/json |
200 response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"inbox",
"sent",
"drafts",
"trash",
"spam",
"archive",
"starred",
"all"
]
},
"roleSource": {
"type": "string",
"enum": [
"user",
"extension",
"name"
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data"
],
"additionalProperties": false
}Last updated
GET /api/v1/accounts/{accountId}/folders
List folders in an email account.
POST /api/v1/accounts/{accountId}/folders/{folderId}/move
Move a folder under another folder, or to the top level of the account. The folder keeps its own name, its messages and its subfolders. Send either `parent` or `topLevel: true`, not both. The destination can't be the folder itself, one of its subfolders, or the trash, and it can't already hold a folder with the same name. In Gmail, where the folder is a label, the labels nested under it move with it. System folders such as Inbox, Sent and Trash can't be moved, and neither can a folder the account settings use as one. Use the folder ID in the response afterwards: in an IMAP mailbox the folder and its subfolders always get new IDs. Message IDs normally stay the same. If one stops working, list the folder again.