Create a label

POST/labels

Creates a label for everyone in your organisation to use.

Needs the permissionlabels:create

Administrators can always create labels, and members can when the organisation lets them. A key acts as its owner, so the same rule applies to it.

Send parentId to put it inside another label, up to three levels deep.

Body

namestringrequired: Up to 40 characters, and different from the other labels at the same level, whatever the case or accents. “Invoices” can sit inside two different labels.
parentIdstringoptional: The label to put it inside. Its scope is then that label’s unless you send one, and it can’t be wider.
colourstringrequired: One of the 52 presets, such as amber-200. List labels lists the hues and strengths.
scopestringoptional: everywhere (the default), teams or mailboxes.
teamIdslist of stringsoptional: With scope teams: at least one team.
mailboxIdslist of stringsoptional: With scope mailboxes: at least one mailbox.

Returns

The label, as List labels describes it.

Errors

400invalid_name: The name is empty or too long. invalid_colour and invalid_scope are the same for those fields.
400no_teams: Scope teams with no teams, or no_mailboxes for mailboxes. unknown_team and unknown_mailbox name an id that isn’t one.
400unknown_parent: parentId isn’t a label in your organisation.
401invalid_key: The key is wrong, expired or revoked. With no Authorization header at all, the code is missing_credentials.
403missing_scope: The key doesn’t have labels:create. The X-Required-Scope header names what’s missing.
403not_allowed: The key’s owner isn’t allowed to manage labels in this organisation.
409too_deep: It would sit more than three levels deep.
409scope_wider: It could be used somewhere the label it sits inside can’t. Narrow its scope first.
409duplicate: Another label at the same level already has that name, perhaps with different capitals.
429rate_limited: More than 120 requests a minute from this key. Wait for Retry-After seconds.

curl https://app.dmu.email/api/v1/labels \ -X POST \ -H "Authorization: Bearer dmk_7f3a9c2e1b4d_Xq8v…" \ -H "Content-Type: application/json" \ -d '{ "name": "Waiting on client", "colour": "amber-200", "scope": "everywhere" }'

{ "data": { "id": "e2a4f809", "name": "Waiting on client", "parentId": null, "colour": "amber-200", "scope": "everywhere", "teamIds": [], "mailboxIds": [], "conversations": 0, "openConversations": 0 } }