Skip to Content
Fluxmail

POST /api/v1/accounts/{accountId}/labels

Create a Gmail label or an Outlook category, or return the existing one with that name. In Gmail, a name such as Projects/2026 creates a nested label and any missing parent labels, and the label also works as a folder. Gmail refuses names it uses for system labels and folders, such as Inbox, Archive and Starred. A new Outlook category has no color. IMAP accounts don't have labels.

Create a Gmail label or an Outlook category, or return the existing one with that name. In Gmail, a name such as Projects/2026 creates a nested label and any missing parent labels, and the label also works as a folder. Gmail refuses names it uses for system labels and folders, such as Inbox, Archive and Starred. A new Outlook category has no color. IMAP accounts don't have labels.

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/labels' \
  -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": "Label or category name. For a nested Gmail label, give the full path, such as Projects/2026."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Responses

StatusDescriptionContent type
200The new label, or the existing label 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"
        },
        "color": {
          "type": "object",
          "properties": {
            "background": {
              "type": "string"
            },
            "text": {
              "type": "string"
            },
            "preset": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}

Last updated