---
title: "Update an address"
description: "Renames the address in the app, turns it off and on, or chooses where its mail goes. A field left out keeps its value."
url: "https://nextmail.sh/docs/api/domains/addresses/update"
area: "API"
category: "Mailbox"
---

# Update an address

Renames the address in the app, turns it off and on, or chooses where its mail goes. A field left out keeps its value.

`PATCH /domains/{id}/addresses/{addressId}`

## PATCH /domains/{id}/addresses/{addressId}

Renames the address in the app, turns it off and on, or chooses where its mail goes. A field left out keeps its value.

## The request

**Parameters**

- `label` (string | null): A new name, at most 120 characters. `null` or an empty string clears it.
- `enabled` (boolean): Whether the address takes mail. A disabled address bounces mail at SMTP time, so the sender gets a bounce rather than silence.
- `destination` ("mailbox" | "forward"): Where the mail of the address goes. `mailbox` keeps a copy here, with a copy to every forwarding destination that is on. `forward` only sends it to the destinations and keeps nothing here.

## Example

Needs `domains:write`. A key limited to particular addresses or domains needs to hold the whole domain.

**curl**

```
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

**Response**

```
{
  "object": "address",
  "id": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18",
  "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",
  "address": "billing@acme.com",
  "localPart": "billing",
  "label": "Invoices",
  "enabled": false,
  "destination": "mailbox",
  "lastReceivedAt": null,
  "createdAt": "2026-09-25T10:00:00.000Z",
  "updatedAt": "2026-09-25T10:00:00.000Z"
}
```

> `destination: "forward"` needs at least one forwarding destination that is switched on, or the call is 409 `forward_required` and changes nothing. Add destinations with `POST /domains/{id}/addresses/{addressId}/forwards` first.

> Sending `destination` from an OAuth access token needs a verification code, and an app acting for a member can only change it on an address that member reaches. Until the app has verified one in the last 60 minutes, the call answers `403` `step_up_required` and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.

## Reference

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