---
title: "Update a label"
method: PATCH
path: "/v1/labels/{id}"
tags: ["Labels"]
---

# Update a label

`PATCH /v1/labels/{id}`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/labels/{id}`
- Auth: HTTP bearer

**Requires scope:** `manage` or `inbox` (`inbox` only in a signed-in dashboard session; no API key or app can hold it). Renaming a label renames it on every thread that carries it.

## Path parameters

- `id` string, required

## Request body

- UpdateLabelRequest
  - `name` string: Renaming a label renames it on every thread that carries it.
  - `color` 'gray' | 'red' | 'orange' | 'amber' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink': A new colour from the same palette of 12. Left out, the colour stays as it is; a request must carry `name`, `color` or both.

## Response `200`

The updated label.

- Label
  - `id` string, required: Label id (`lbl_…`).
  - `name` string, required: Unique in the workspace, ignoring case.
  - `color` 'gray' | 'red' | 'orange' | 'amber' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink', required: The label's colour, one of 12 palette names: `gray` unless another was chosen.
  - `created_at` string, date-time, required: When the label was created (UTC).
  - `updated_at` string, date-time, required: When the label was last changed with PATCH, even by a request that left it as it was. Equal to `created_at` on a label never patched.

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `409`: Conflict — duplicate resource, an in-progress idempotent request, a draft or scheduled message that started sending while it was being changed, or a thread deleted for good while one of its messages is being sent (`duplicate_resource`); or an agent name more than one agent has (`agent_name_conflict`: use the agent's id); or a status change on an archived agent, since archiving cannot be undone (`agent_archived`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)