Update a label

PATCH/labels/{id}

Renames a label, changes its colour, changes where it can be used or moves it inside another. Send only what changes.

Needs the permissionlabels:update

Narrowing where a label can be used takes it off nothing: conversations outside the new scope keep it, but it can’t be added there any more.

The labels inside a label can’t be used anywhere it can’t. So narrowing one with labels inside it answers 409 narrows_inside, naming them in the message, and changes nothing until you send it again with "narrowInside": true.

Path parameters

idstringrequired: The label.

Body

namestringoptional: 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.
parentIdstring or nulloptional: Moves it inside another label, or to the top level with null. The labels inside it move with it.
colourstringoptional: One of the 52 presets, such as amber-200. List labels lists the hues and strengths.
scopestringoptional: everywhere, teams or mailboxes.
teamIdslist of stringsoptional: With scope teams: at least one team.
mailboxIdslist of stringsoptional: With scope mailboxes: at least one mailbox.
narrowInsidebooleanoptional: true to go ahead when narrowing its scope narrows the labels inside it too.

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:update. The X-Required-Scope header names what’s missing.
403not_allowed: The key’s owner isn’t allowed to manage labels in this organisation.
404not_found: There’s no such label, or the key’s owner can’t see it.
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.
409cycle: A label can’t go inside itself, or inside a label that’s inside it.
409narrows_inside: The new scope would narrow the labels inside it too. Send narrowInside: true to go ahead.
429rate_limited: More than 120 requests a minute from this key. Wait for Retry-After seconds.