---
title: "Update a contact"
description: "A partial update, never an upsert. A field you leave out keeps its stored value and an explicit `null` clears it, so `{\"notes\": null}` empties the notes while `{}` changes nothing. An address not in the book is a `404`."
url: "https://nextmail.sh/docs/api/contacts/update"
area: "API"
category: "Mailbox"
---

# Update a contact

A partial update, never an upsert. A field you leave out keeps its stored value and an explicit `null` clears it, so `{"notes": null}` empties the notes while `{}` changes nothing. An address not in the book is a `404`.

`PATCH /contacts/{email}`

## PATCH /contacts/{email}

A partial update, never an upsert. A field you leave out keeps its stored value and an explicit `null` clears it, so `{"notes": null}` empties the notes while `{}` changes nothing. An address not in the book is a `404`.

## Example

Needs `contacts:write`. URL-encode the `@`.

**curl**

```
curl -X PATCH "$OE/contacts/grace%40example.com" -H "$AUTH" -H 'content-type: application/json' -d '{
  "name": "Grace Hopper",
  "notes": null,
  "attributes": { "plan": "team", "trialEnds": null }
}'
```

**Response**

```
{
  "object": "contact",
  "email": "grace@example.com",
  "name": "Grace Hopper",
  "source": "manual",
  "notes": null,
  "attributes": { "plan": "team" },
  "lastSeenAt": null,
  "createdAt": "2026-09-18T09:00:00.000Z",
  "updatedAt": "2026-09-18T09:04:00.000Z",
  "audiences": [
    { "id": "aud_9f2c4b7e1a0d63d84c5f2e7b", "name": "All contacts", "builtin": "default" }
  ]
}
```

> The address cannot be changed here. It is the identity, the path segment and the unique key of the book, so moving a contact to a new address is a delete and a create.

> A contact recorded automatically stays `auto` after you give it a name. Naming it is not the same claim as somebody having saved it.

> Audience membership is untouched. `PUT /contacts/{email}/audiences` sets it in one call, and the audience routes change one audience at a time.

> In `attributes` a text value sets a custom field and `null` removes it. Fields you leave out keep what they hold.

## Reference

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