---
title: "Update a label"
description: "Rename, recolour, or both. A field left out stays as it is."
url: "https://nextmail.sh/docs/api/labels/update"
area: "API"
category: "Mailbox"
---

# Update a label

Rename, recolour, or both. A field left out stays as it is.

`PATCH /labels/{id}`

## PATCH /labels/{id}

Rename, recolour, or both. A field left out stays as it is.

## Example

Needs `labels:write`.

**curl**

```
curl -X PATCH "$OE/labels/USER_INVOICES" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "name": "Billing", "color": { "backgroundColor": "gradient:sunset" } }'
```

**Response**

```
{
  "object": "label",
  "id": "USER_INVOICES",
  "name": "Billing",
  "type": "user",
  "color": { "backgroundColor": "gradient:sunset", "textColor": "#18181B" },
  "threadCount": 318,
  "aiInstructions": "invoices and receipts",
  "aiEnabled": true,
  "createdAt": "2026-09-22T08:14:03.117Z",
  "updatedAt": "2026-09-23T10:05:12.031Z"
}
```

> Send `name`, `color` or both. `color: null`, or an empty `backgroundColor`, clears the colour, and a body with neither field is a 422.

> The id never changes, so every conversation keeps the label through a rename. A new name another label already has is a 409 `label_name_taken`.

> `aiInstructions` and `aiEnabled` are changed here too, under the same plan and the same limit of 10 as on create. `aiEnabled: false` stops the labelling and keeps the description, and `aiInstructions: null` clears it and stops the labelling.

## Reference

- [`PATCH /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#patch-labels-id): full reference