Create a label
Give it a name and, if you like, a colour: a hex value or a gradient token.
Runs the real call on your workspace.
POST /labels
Give it a name and, if you like, a colour: a hex value or a gradient token.
Example
Needs labels:write.
curl -X POST "$OE/labels" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "name": "Big Clients", "color": { "backgroundColor": "gradient:aurora" } }'{ "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.