Skip to Content
Fluxmail

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

NameLocationRequiredTypeDetails
accountIdpathYesstringMinimum 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

StatusDescriptionContent type
200The new folder, or the existing folder with that nameapplication/json
400Invalid requestapplication/json
401Authentication requiredapplication/json
403Permission or plan deniedapplication/json
404Resource not foundapplication/json
409Request conflictapplication/json
422Unsupported capabilityapplication/json
429Provider rate limitapplication/json
500Internal errorapplication/json
503Provider unavailableapplication/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