---
title: "Create a label"
description: "Give it a name and, if you like, a colour: a hex value or a gradient token."
url: "https://nextmail.sh/docs/api/labels/create"
area: "API"
category: "Mailbox"
---

# Create a label

Give it a name and, if you like, a colour: a hex value or a gradient token.

`POST /labels`

## POST /labels

Give it a name and, if you like, a colour: a hex value or a gradient token.

## Example

Needs `labels:write`.

**curl**

```
curl -X POST "$OE/labels" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "name": "Big Clients", "color": { "backgroundColor": "gradient:aurora" } }'
```

**Response**

```
{
  "object": "label",
  "id": "USER_BIG_CLIENTS",
  "name": "Big Clients",
  "type": "user",
  "color": { "backgroundColor": "gradient:aurora", "textColor": "#18181B" },
  "threadCount": 0,
  "aiInstructions": null,
  "aiEnabled": false,
  "createdAt": "2026-09-23T10:02:44.508Z",
  "updatedAt": "2026-09-23T10:02:44.508Z"
}
```

> The id comes from the name (`Big Clients` becomes `USER_BIG_CLIENTS`) and never changes afterwards. A name another label already has, compared without case, is a 409 `label_name_taken`, and so is a name whose id a renamed label still holds. An existing label is never overwritten.

> `color.backgroundColor` is a hex colour (`#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`, stored upper-cased) or a gradient token, and anything else is a 422 `invalid_parameter`. Leave `color` out for no colour. `textColor` is accepted and ignored.

> A workspace holds at most 50 labels. The one past that is a 422 `label_limit_reached`.

> Send `aiInstructions`, what the label is for in plain words and at most 500 characters, with `aiEnabled: true`, and AI adds the label to arriving mail that fits. It skips spam, the Bin, encrypted mail and muted threads, and it only ever adds the label. `aiEnabled: true` with no instructions is a 422 `invalid_parameter`.

> A label that AI applies needs a paid plan, and without one the call is a 403 `plan_required`. A workspace may have 10 of them, and turning on one more is a 422 `ai_label_limit_reached`.

## Reference

- [`POST /labels`](https://nextmail.sh/docs/api/reference/labels#post-labels): full reference