---
title: "Settings"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://nextmail.sh/docs/api/reference/settings"
area: "API"
category: "Reference"
---

# Settings

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

Mailbox preferences, the signature and tracking of each address, and the brand of the workspace: its images, fonts and sign-in background.

### `GET /branding`

Retrieve the brand

The brand of the workspace, as its Customisations page shows it: a link to each brand image, the primary and secondary fonts, and the background of the sign-in page.

The mark shows in the app's workspace switcher. The logo shows at the top of the sidebar, and it is what brands the web app address, `GET /app-host`, and, on a paid plan, the emails Nextmail sends for the workspace, which carry it at the top and the foot. Without a logo, the web app address and the emails look like Nextmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, either way.

A personal space carries no brand, so its images and fonts read as null and `editable` is false.

Requires the `settings:read` scope.

- Scopes: `settings:read`.

**Returns**

- `200` `Branding`: The brand of the workspace.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.branding.get()`](https://nextmail.sh/docs/sdk/reference/branding#get); Python [`branding.get()`](https://nextmail.sh/docs/python/reference/branding#get); Ruby [`branding.get`](https://nextmail.sh/docs/ruby/reference/branding#get); PHP [`branding->get`](https://nextmail.sh/docs/php/reference/branding#get); Go [`Branding.Get`](https://nextmail.sh/docs/go/reference/branding#get); Java [`branding().get`](https://nextmail.sh/docs/java/reference/branding#get); C# [`Branding.GetAsync`](https://nextmail.sh/docs/csharp/reference/branding#get); CLI [`nextmail branding get`](https://nextmail.sh/docs/cli/reference/branding#branding-get); MCP [`getBranding`](https://nextmail.sh/docs/mcp/tools/domains#getBranding).

### `PATCH /branding`

Change the fonts and the sign-in background

Changes the fonts, the sign-in page background or both, and returns the brand in the same shape as `GET /branding`. A field left out keeps its value, and so does a font left out of `fonts`. `loginBackground` replaces the background there was, and null sets the default.

With `kind: "image"` the sign-in page shows the photo uploaded with `PUT /branding/images/login-background`, so upload that first: without it the call is refused. Uploading one switches the page to it on its own.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Request body**

- `fonts` (`object`): The fonts to change. A font left out keeps its value, and null sets the default.
  - `primary` (`string`, nullable, one of `"system"`, `"arial"`, `"helvetica"`, `"verdana"`, `"tahoma"`, `"trebuchet-ms"`, `"georgia"`, `"times-new-roman"`, `"courier-new"`, `"dm-sans"`, `"inter"`, `"roboto"`, `"open-sans"`, `"lato"`, `"montserrat"`, `"poppins"`, `"nunito"`, `"work-sans"`, `"source-sans-3"`, `"ibm-plex-sans"`, `"merriweather"`, `"playfair-display"`, `"instrument-serif"`, `"jetbrains-mono"`, `"dm-mono"`, `"geist-mono"`): The primary font, or null for the default.
  - `secondary` (`string`, nullable, one of `"system"`, `"arial"`, `"helvetica"`, `"verdana"`, `"tahoma"`, `"trebuchet-ms"`, `"georgia"`, `"times-new-roman"`, `"courier-new"`, `"dm-sans"`, `"inter"`, `"roboto"`, `"open-sans"`, `"lato"`, `"montserrat"`, `"poppins"`, `"nunito"`, `"work-sans"`, `"source-sans-3"`, `"ibm-plex-sans"`, `"merriweather"`, `"playfair-display"`, `"instrument-serif"`, `"jetbrains-mono"`, `"dm-mono"`, `"geist-mono"`): The secondary font, or null for the default.
- `loginBackground` (`object`, nullable): The sign-in page background, replacing the one there was, or null for the default.
  - `kind` (`string`, required, one of `"preset"`, `"color"`, `"image"`): `preset` shows `preset`, `color` fills it with `color`, and `image` shows the image uploaded with `PUT /branding/images/login-background`. `image` is refused with 422 `invalid_parameter` until that image is uploaded, and once it is removed the background falls back to the `preset` or `color` kept with it, or to null.
  - `preset` (`string`, nullable, one of `"dusk"`, `"mist"`, `"sand"`, `"night"`, `"meadow"`, `"dots"`, `"brush"`, `"trail"`, `"ember"`, `"canvas"`, `"bloom"`, `"field"`, `"wanderer"`, `"gold"`): One of the built-in backgrounds. Required when `kind` is `preset`.
  - `color` (`string`, nullable, pattern `^#[0-9a-f]{6}$`): A colour as `#` and six hex digits, such as `#1f2937`, stored lowercased. Required when `kind` is `color`.
  - `logo` (`string`, nullable, one of `"dark"`, `"light"`): Which logo the sign-in page shows: `dark`, your logo, or `light`, your logo for dark mode (Nextmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.

**Returns**

- `200` `Branding`: The brand as this call left it.

**Errors**

- `400`: `malformed_json`: the body is not valid JSON.
- `403`: `insufficient_scope`: the key lacks `settings:write`.
- `409`: `branding_unavailable`: the workspace is a personal space, which carries no brand.
- `422`: `invalid_parameter` naming the field, such as `fonts.primary` for a font that is not on the list, `loginBackground.preset` when `kind` is `preset` and no preset is given, `loginBackground.kind` when `kind` is `image` and no sign-in photo is uploaded, or `loginBackground.color` for a colour that is not `#` and six hex digits. `unknown_parameter` for any other field, and `capability_unsupported` with `param: "domainAllowlist"` for a key or app limited to particular addresses or domains.
- The errors every operation can return: `401`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.branding.update()`](https://nextmail.sh/docs/sdk/reference/branding#update); Python [`branding.update()`](https://nextmail.sh/docs/python/reference/branding#update); Ruby [`branding.update`](https://nextmail.sh/docs/ruby/reference/branding#update); PHP [`branding->update`](https://nextmail.sh/docs/php/reference/branding#update); Go [`Branding.Update`](https://nextmail.sh/docs/go/reference/branding#update); Java [`branding().update`](https://nextmail.sh/docs/java/reference/branding#update); C# [`Branding.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/branding#update); CLI [`nextmail branding update`](https://nextmail.sh/docs/cli/reference/branding#branding-update); MCP [`updateBranding`](https://nextmail.sh/docs/mcp/tools/domains#updateBranding).

### `PUT /branding/images/{variant}`

Upload a brand image

Uploads one brand image, replacing the one there was, and returns the brand. Send the image itself as the body, not JSON, with its type in `Content-Type`. Up to 5 MB goes in. `variant` names the image:

- `mark`: the square mark. `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp`, fitted into 512 by 512 pixels and stored as WebP.
- `wordmark`: the logo. `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp`, fitted into 1024 by 256 pixels and stored as WebP.
- `wordmark-dark`: the logo for dark mode, shown in place of the logo when the app is dark. `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp`, fitted into 1024 by 256 pixels and stored as WebP.
- `login-background`: the photo behind the sign-in page of the web app address. `image/png`, `image/jpeg`, `image/webp`, `image/gif`, fitted into 2560 by 1600 pixels and stored as WebP. Uploading it also switches the sign-in page to it.

An SVG is turned into a picture, and an animated image keeps its first frame.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Path parameters**

- `variant` (`string`, required, one of `"mark"`, `"wordmark"`, `"wordmark-dark"`, `"login-background"`): Which image: `mark`, the square icon, `wordmark`, the logo, `wordmark-dark`, the logo for dark mode, or `login-background`, the photo behind the sign-in page.

**Request body**

Content type: `image/webp`, `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`.

`binary`

**Returns**

- `200` `Branding`: The brand, with the new image.

**Errors**

- `403`: `insufficient_scope`: the key lacks `settings:write`.
- `409`: `branding_unavailable`: the workspace is a personal space, which carries no brand.
- `422`: `invalid_image` when the body is not an image of a type that variant accepts, is too large or cannot be read. `invalid_parameter` on `variant` for a name that is not one of the four, and `capability_unsupported` with `param: "domainAllowlist"` for a key or app limited to particular addresses or domains.
- `502`: `image_not_stored`: the image was read but could not be stored. Try again.
- `503`: `image_busy`: the image service is saturated. Try again shortly.
- The errors every operation can return: `400`, `401`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.branding.uploadImage()`](https://nextmail.sh/docs/sdk/reference/branding#uploadImage); Python [`branding.upload_image()`](https://nextmail.sh/docs/python/reference/branding#uploadImage); Ruby [`branding.upload_image`](https://nextmail.sh/docs/ruby/reference/branding#uploadImage); PHP [`branding->uploadImage`](https://nextmail.sh/docs/php/reference/branding#uploadImage); Go [`Branding.UploadImage`](https://nextmail.sh/docs/go/reference/branding#uploadImage); Java [`branding().uploadImage`](https://nextmail.sh/docs/java/reference/branding#uploadImage); C# [`Branding.UploadImageAsync`](https://nextmail.sh/docs/csharp/reference/branding#uploadImage); CLI [`nextmail branding upload-image`](https://nextmail.sh/docs/cli/reference/branding#branding-upload-image); MCP [`setBrandImage`](https://nextmail.sh/docs/mcp/tools/domains#setBrandImage).

### `DELETE /branding/images/{variant}`

Remove a brand image

Removes one brand image, deletes the stored file and returns the brand, so the default shows in its place. Removing the sign-in photo while the sign-in page shows it switches the page back to the preset or colour chosen before it, or to the default. Removing an image that is not set changes nothing, so a repeated call is safe.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Path parameters**

- `variant` (`string`, required, one of `"mark"`, `"wordmark"`, `"wordmark-dark"`, `"login-background"`): Which image: `mark`, the square icon, `wordmark`, the logo, `wordmark-dark`, the logo for dark mode, or `login-background`, the photo behind the sign-in page.

**Returns**

- `200` `Branding`: The brand, without that image.

**Errors**

- `403`: `insufficient_scope`: the key lacks `settings:write`.
- `409`: `branding_unavailable`: the workspace is a personal space, which carries no brand.
- `422`: `invalid_parameter` on `variant` for a name that is not one of the four, and `capability_unsupported` with `param: "domainAllowlist"` for a key or app limited to particular addresses or domains.
- The errors every operation can return: `400`, `401`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.branding.removeImage()`](https://nextmail.sh/docs/sdk/reference/branding#removeImage); Python [`branding.remove_image()`](https://nextmail.sh/docs/python/reference/branding#removeImage); Ruby [`branding.remove_image`](https://nextmail.sh/docs/ruby/reference/branding#removeImage); PHP [`branding->removeImage`](https://nextmail.sh/docs/php/reference/branding#removeImage); Go [`Branding.RemoveImage`](https://nextmail.sh/docs/go/reference/branding#removeImage); Java [`branding().removeImage`](https://nextmail.sh/docs/java/reference/branding#removeImage); C# [`Branding.RemoveImageAsync`](https://nextmail.sh/docs/csharp/reference/branding#removeImage); CLI [`nextmail branding remove-image`](https://nextmail.sh/docs/cli/reference/branding#branding-remove-image); MCP [`removeBrandImage`](https://nextmail.sh/docs/mcp/tools/domains#removeBrandImage).

### `GET /settings`

Read mailbox settings

Every field with defaults filled in, so reading a setting never requires knowing which release introduced it.

Without `address` this is your account and the workspace. The account fields are the caller's own: for an API key the workspace owner's, for a connected app the person who connected it. The privacy fields and `workspaceName` are the workspace's. `signature`, `openEmailSignature`, `trackOpens` and `trackClicks` belong to each address and read as the built-in defaults here: no signature, the Nextmail footer on, and open and link tracking off.

With `address`, the fields as they apply to that scope. For one address the four per-address fields resolve the way a send from it does: the address's own values, then its domain's catch-all when the catch-all caught that address rather than it being one you created, then the built-in defaults, and a plus address with no settings of its own reads its base address's. `externalImages`, `trustedSenders` and the blocklist resolve from the workspace, then the domain, then the catch-all, then the base of a plus address, then the address itself, and the last of them that sets a field wins. `*@domain` reads a catch-all the same way, and `@domain` reads the workspace's privacy with the domain's own on top. Every other field reads the same whatever the scope.

`overrides` holds what the scope sets itself, and everything not in it is inherited. `address` in the response is the scope the call named, lowercased, or null.

Requires the `settings:read` scope.

- Scopes: `settings:read`.

**Query parameters**

- `address` (`string`, up to 320 characters): The scope to read or change: one address such as `hello@example.com`, `*@example.com` for the catch-all of that domain, or `@example.com` for the whole domain. An address or a catch-all keeps its own `signature`, `openEmailSignature`, `trackOpens`, `trackClicks`, `externalImages`, `trustedSenders` and blocklist, and a domain its own `externalImages`, `trustedSenders` and blocklist. On a read any address resolves the way mail to and from it does. On a write it has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all or a domain only when it holds that domain whole, or it is 422 `capability_unsupported`.

**Returns**

- `200` `Settings`: Settings.

**Errors**

- `422`: `invalid_parameter` on `address` when it is not one address, `*@domain` or `@domain`, or `capability_unsupported` when a narrowed key names an address or a domain it does not hold.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.settings.get()`](https://nextmail.sh/docs/sdk/reference/settings#get); Python [`settings.get()`](https://nextmail.sh/docs/python/reference/settings#get); Ruby [`settings.get`](https://nextmail.sh/docs/ruby/reference/settings#get); PHP [`settings->get`](https://nextmail.sh/docs/php/reference/settings#get); Go [`Settings.Get`](https://nextmail.sh/docs/go/reference/settings#get); Java [`settings().get`](https://nextmail.sh/docs/java/reference/settings#get); C# [`Settings.GetAsync`](https://nextmail.sh/docs/csharp/reference/settings#get); CLI [`nextmail settings get`](https://nextmail.sh/docs/cli/reference/settings#settings-get); MCP [`getSettings`](https://nextmail.sh/docs/mcp/tools/workspace#getSettings).

### `PATCH /settings`

Change mailbox settings

A partial update: a field you omit keeps its value, and a list replaces the old one.

Without `address`, this changes your account and the workspace. The account fields (time zone and formats, theme, sounds, notifications and the rest) are saved on the caller's account: for an API key the workspace owner's, for a connected app the person who connected it. `workspaceName` renames the workspace. The privacy fields (`externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords`, `useDefaultBlockedWords`, `semanticSearch`, `replySuggestions`, `knowledgeLearning`) and the marketing footer fields (`marketingSenderName`, `marketingPostalAddress`) are saved on the workspace, and `null` removes the workspace's own value so the default applies again. A key narrowed to particular addresses or domains may change none of those workspace fields or the name, and gets 422 `capability_unsupported`. `signature`, `openEmailSignature`, `trackOpens` and `trackClicks` are refused without `address` with 422 `address_required` naming the field, because they are set on each address, and nothing is written. `semanticSearch: false` turns search by meaning off for the whole workspace: its mail stops going to the embedding model, what was stored for it is deleted at once, and `semantic` on `GET /threads` runs a text search until it is turned back on, when the mail is read for meaning again over the next minutes. `replySuggestions: false` stops suggested replies for the whole workspace: no thread goes to a model for them any more, what was stored is deleted at once, and `GET /threads/{id}/reply-suggestions` answers `none` until it is turned back on.

With `address`, the body gives that scope a choice of its own. One address or a catch-all (`*@domain`) takes `signature`, `openEmailSignature`, `trackOpens`, `trackClicks`, `externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords` and `useDefaultBlockedWords`, and a whole domain (`@domain`) the last six only. `null` removes the scope's own value, so it inherits again from the scope above it. Any other field is 422 `not_per_address` naming it, `semanticSearch`, `replySuggestions`, `knowledgeLearning` and the marketing footer fields included, since they belong to the whole workspace. The scope has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace, or it is 422 `invalid_parameter` on `address`. The response is what `GET /settings?address=` returns for it. A catch-all's values apply to the addresses its domain catches, and a new address created on that domain starts with a copy of them and changes on its own from then on.

Returns the SAVED state, so the signature you get back is the sanitised one that will actually be sent rather than what you asked for.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Query parameters**

- `address` (`string`, up to 320 characters): The scope to read or change: one address such as `hello@example.com`, `*@example.com` for the catch-all of that domain, or `@example.com` for the whole domain. An address or a catch-all keeps its own `signature`, `openEmailSignature`, `trackOpens`, `trackClicks`, `externalImages`, `trustedSenders` and blocklist, and a domain its own `externalImages`, `trustedSenders` and blocklist. On a read any address resolves the way mail to and from it does. On a write it has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all or a domain only when it holds that domain whole, or it is 422 `capability_unsupported`.

**Request body**

- `timezone` (`string`): IANA time zone such as `Europe/Berlin`. Saved on the account.
- `timeFormat` (`string`, one of `"12h"`, `"24h"`): `12h` or `24h`, how the app writes times. Saved on the account.
- `dateFormat` (`string`, one of `"dmy"`, `"mdy"`, `"ymd"`): `dmy`, `mdy` or `ymd`, the order the app writes dates in. Saved on the account.
- `weekStart` (`string`, one of `"monday"`, `"sunday"`): `monday` or `sunday`, the first day of the week in the calendar and date pickers. Saved on the account.
- `workspaceName` (`string`): Renames this workspace, 1 to 64 characters once trimmed. A personal space has no name of its own, so it is 422 `invalid_parameter` there. Not with `address`.
- `externalImages` (`boolean`, nullable): Loads pictures in mail automatically. Off means senders cannot tell you read it. On by default. Without `address` it is the workspace's choice, and with an address, a catch-all or `@domain` that scope's own. `null` removes the value the scope sets itself, so it inherits again.
- `semanticSearch` (`boolean`, nullable): Search by meaning for the whole workspace. On by default. `false` stops its mail going to the embedding model, deletes what was stored and makes `semantic` run a text search, and `null` turns it back on. Not with `address`.
- `replySuggestions` (`boolean`, nullable): Suggested replies for the whole workspace. On by default. `false` stops threads going to a model for them and deletes the suggestions that were stored, and `null` turns them back on. Not with `address`.
- `knowledgeLearning` (`boolean`, nullable): Knowledge base suggestions for the whole workspace. On by default: the AI reads the replies sent in a conversation and the questions nothing answered, and suggests notes from them, and it checks closely related items for conflicts. `false` stops all three, and `null` turns them back on. Suggestions already made stay until they are accepted or dismissed. Not with `address`.
- `trustedSenders` (`string[]`, nullable): Senders whose pictures always load while `externalImages` is off. Replaces the whole list. Without `address` it is the workspace's list, and with an address, a catch-all or `@domain` that scope's own. `null` removes the scope's own list, so it inherits again.
- `colorTheme` (`string`, one of `"light"`, `"dark"`, `"system"`): `light`, `dark` or `system`, the app's theme. Saved on the account.
- `openEmailSignature` (`boolean`, nullable): Adds the Nextmail footer to mail from the address named by `address` while it has no signature. On by default. `null` removes the address's own value. Only with an address or a catch-all.
- `signature` (`string`, nullable, up to 150000 characters): HTML of the default signature of the address named by `address`, the one new mail from it carries, at most 150,000 characters before and after sanitising. Sanitised on write. An address keeps a list of signatures, which `GET /signatures` returns, and this field is the one that is the default for new mail. Writing it rewrites that signature, or adds one called `Signature` and makes it the default when the address has none. An empty string or `null` leaves new mail from the address with no signature, and replies too when they used the same one, and deletes nothing. Only with an address or a catch-all.
- `defaultEmailAlias` (`string`): The address the composer starts from when you write new mail in the app. Saved on the account.
- `undoSendEnabled` (`boolean`): Holds each send from the app for 30 seconds so it can be cancelled. Off by default. Saved on the account.
- `trackOpens` (`boolean`, nullable): Open tracking on mail from the address named by `address`, for a send that does not set `tracking.opens`. Off by default. `null` removes the address's own value. Only with an address or a catch-all.
- `trackClicks` (`boolean`, nullable): Link tracking on mail from the address named by `address`, for a send that does not set `tracking.clicks`. Off by default. `null` removes the address's own value. Only with an address or a catch-all.
- `imageCompression` (`string`, one of `"low"`, `"medium"`, `"original"`): `low`, `medium` or `original`, how far pictures attached in the app are compressed before they are sent. Saved on the account.
- `attachmentDelivery` (`string`, one of `"mime"`, `"link"`, `"auto"`): How files go out on a send that does not set `attachmentDelivery` itself: `mime` attaches them to the message, `link` sends download links, and `auto` links large files only, which needs a files address. Saved on the account.
- `autoRead` (`boolean`): Marks mail read when you open it in the app. Saved on the account.
- `aiWrittenLabel` (`boolean`): Shows the AI-written label on mail whose words look generated. Mail is scored either way and the sender is never told. Saved on the account.
- `animations` (`boolean`): Motion in the app. Off makes everything appear at once. Saved on the account.
- `desktopNewMail` (`boolean`): A desktop notification when a message reaches the inbox while the app is open in a browser that allows them. Saved on the account.
- `desktopOnlyWhenHidden` (`boolean`): Desktop notifications only while the tab is hidden, so they stay quiet while you watch the inbox. Saved on the account.
- `phoneNewMail` (`boolean`): A push to your phones when a message reaches the inbox. Saved on the account.
- `phoneReplies` (`boolean`): A push to your phones when someone answers your mail. Saved on the account.
- `phoneScheduledSend` (`boolean`): A push to your phones when a scheduled message goes out. Saved on the account.
- `phoneFollowUps` (`boolean`): A push to your phones when a message you asked to be reminded about has had no reply by then. Saved on the account.
- `inboxTabs` (`boolean`): Shows the inbox as tabs: Primary, Promotions, Updates, Social and Forums. Mail is sorted either way, and turning this on sorts the last 1,000 inbox threads of the open workspace. Saved on the account.
- `primaryOnlyAlerts` (`boolean`): With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
- `phoneSendFailures` (`boolean`): A push to your phones when a message fails to send. Saved on the account.
- `phonePreviews` (`boolean`): Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
- `phoneSound` (`boolean`): Plays a sound with each push. Off makes them silent. Saved on the account.
- `phoneMutedWorkspaces` (`string[]`, up to 200 items): Workspace ids whose mail sends no push to your phones. Replaces the whole list. `PUT /account/notifications/push/{workspaceId}` changes one workspace at a time. Saved on the account.
- `soundNewMail` (`boolean`): Chimes when mail arrives while the app is open. Saved on the account.
- `soundAiDone` (`boolean`): Chimes when the assistant finishes a reply. Saved on the account.
- `soundSent` (`boolean`): Chimes when your message goes out. Saved on the account.
- `blockedSenders` (`string[]`, nullable): Senders whose mail is refused on arrival, plus-tags included. Mail already delivered stays. Replaces the whole list. Without `address` it is the workspace's list, and with an address, a catch-all or `@domain` that scope's own. `null` removes the scope's own list, so it inherits again.
- `blockedDomains` (`string[]`, nullable): Domains whose mail is refused on arrival, subdomains included. Replaces the whole list. Without `address` it is the workspace's list, and with an address, a catch-all or `@domain` that scope's own. `null` removes the scope's own list, so it inherits again.
- `blockedWords` (`string[]`, nullable): Words that open matching mail behind a warning. Nothing is deleted. Replaces the whole list. Without `address` it is the workspace's list, and with an address, a catch-all or `@domain` that scope's own. `null` removes the scope's own list, so it inherits again.
- `useDefaultBlockedWords` (`boolean`, nullable): Adds the built-in list of English profanities and slurs to `blockedWords`. Off by default. Without `address` it is the workspace's choice, and with an address, a catch-all or `@domain` that scope's own. `null` removes the scope's own value, so it inherits again.
- `translateLanguage` (`string`): The language Translate offers first, a language code such as `de`. Empty means English. Saved on the account.
- `translateReplies` (`boolean`): Opens replies on threads you translated already translated into your language. Saved on the account.
- `showAvatarToContacts` (`boolean`): Shows your profile photo to Nextmail users on your address. Saved on the account.
- `lookupContactPhotos` (`boolean`): Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
- `marketingSenderName` (`string`, nullable, up to 120 characters, pattern `^[^\u0000-\u001F\u007F]*$`): Who the footer of broadcasts and automation emails names as the sender, one line of at most 120 characters, shown above `marketingPostalAddress`. Empty, the default, uses the workspace name. `null` empties it. Not with `address`.
- `marketingPostalAddress` (`string`, nullable, up to 500 characters, pattern `^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$`): The postal address the footer of broadcasts and automation emails shows, at most 500 characters on one line or several, which many countries require of marketing email. The footer is the one Nextmail adds to a message that does not place `{{unsubscribeUrl}}` itself, written in English. Empty, the default, shows no address. `null` empties it. Not with `address`.

**Returns**

- `200` `Settings`: The saved settings.

**Errors**

- `422`: Rejected: `address_required` (a per-address field sent without `address`), `not_per_address` (a field the scope `address` names does not keep), `signature_too_long`, `blocklist_entry_too_broad`, `invalid_parameter` (including `null` for a field that cannot be cleared, and `workspaceName` on a personal space), or `capability_unsupported` when a narrowed key names an address or a domain it does not hold, or changes a workspace field.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.settings.update()`](https://nextmail.sh/docs/sdk/reference/settings#update); Python [`settings.update()`](https://nextmail.sh/docs/python/reference/settings#update); Ruby [`settings.update`](https://nextmail.sh/docs/ruby/reference/settings#update); PHP [`settings->update`](https://nextmail.sh/docs/php/reference/settings#update); Go [`Settings.Update`](https://nextmail.sh/docs/go/reference/settings#update); Java [`settings().update`](https://nextmail.sh/docs/java/reference/settings#update); C# [`Settings.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/settings#update); CLI [`nextmail settings update`](https://nextmail.sh/docs/cli/reference/settings#settings-update); MCP [`updateSettings`](https://nextmail.sh/docs/mcp/tools/workspace#updateSettings).

### `GET /out-of-office`

Read out of office replies

Every out of office reply saved in the workspace, by address. With `address` the list holds exactly one row, the reply of that address, which reads `enabled: false` with empty text when none was ever saved. `active` says whether the reply is going out right now: it is on, the start has passed and the end has not.

Requires the `settings:read` scope.

- Scopes: `settings:read`.

**Query parameters**

- `address` (`string`, up to 320 characters): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.

**Returns**

- `200` `OutOfOfficeList`: The replies, by address.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.outOfOffice.list()`](https://nextmail.sh/docs/sdk/reference/out-of-office#list); Python [`out_of_office.list()`](https://nextmail.sh/docs/python/reference/out-of-office#list); Ruby [`out_of_office.list`](https://nextmail.sh/docs/ruby/reference/out-of-office#list); PHP [`outOfOffice->list`](https://nextmail.sh/docs/php/reference/out-of-office#list); Go [`OutOfOffice.List`](https://nextmail.sh/docs/go/reference/out-of-office#list); Java [`outOfOffice().list`](https://nextmail.sh/docs/java/reference/out-of-office#list); C# [`OutOfOffice.ListAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#list); CLI [`nextmail out-of-office list`](https://nextmail.sh/docs/cli/reference/out-of-office#out-of-office-list); MCP [`getOutOfOffice`](https://nextmail.sh/docs/mcp/tools/workspace#getOutOfOffice).

### `PUT /out-of-office`

Set an out of office reply

Saves the out of office reply of one address, or of a catch-all with `*@example.com`, replacing whatever was saved. While it is active, each person who writes to the address gets the message once for the whole away period, as a reply in the same thread. Mail that would not alert anyone gets no reply: spam, mail a rule filed away, newsletters and other bulk mail, automatic mail, bounces, blocked senders and the workspace's own addresses. With `contactsOnly`, only people in the contacts, or people the workspace has written to, are answered.

Leave `startsAt` out to start now, or to keep the start of a reply that is already on, and `endsAt` out or null to keep it on until it is switched off. An address with a reply of its own is never answered by the catch-all. Replies count toward the monthly sends, carry no tracking, and still go out on muted threads.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Query parameters**

- `address` (`string`, required, up to 320 characters): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.

**Request body**

- `enabled` (`boolean`, default `true`): Whether the reply is switched on. Left out, true. `false` keeps the text and pauses the reply.
- `startsAt` (`string`, nullable, format `date-time`): When the reply starts. Left out or null, now, or the start it already has while the reply is on.
- `endsAt` (`string`, nullable, format `date-time`): When it stops, later than `startsAt`. Left out or null, it stays on until it is switched off.
- `subject` (`string`, up to 255 characters, default `""`): The subject of the reply, at most 255 characters. Left out or empty, the reply answers with `Re:` and the subject received.
- `message` (`string`, required, 1 to 10000 characters): The reply, as plain text, 1 to 10,000 characters once trimmed. Line breaks are kept.
- `contactsOnly` (`boolean`, default `false`): Answer only contacts and people the workspace has written to. Left out, false.

**Returns**

- `200` `OutOfOffice`: Saved, read back as it is stored.

**Errors**

- `422`: `invalid_parameter`: `address` is missing, is not an address of the workspace or names a whole domain, the message is empty, or `endsAt` is not after `startsAt` or is already in the past. `capability_unsupported`: the key or app does not hold that address.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.outOfOffice.set()`](https://nextmail.sh/docs/sdk/reference/out-of-office#set); Python [`out_of_office.set()`](https://nextmail.sh/docs/python/reference/out-of-office#set); Ruby [`out_of_office.set`](https://nextmail.sh/docs/ruby/reference/out-of-office#set); PHP [`outOfOffice->set`](https://nextmail.sh/docs/php/reference/out-of-office#set); Go [`OutOfOffice.Set`](https://nextmail.sh/docs/go/reference/out-of-office#set); Java [`outOfOffice().set`](https://nextmail.sh/docs/java/reference/out-of-office#set); C# [`OutOfOffice.SetAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#set); CLI [`nextmail out-of-office set`](https://nextmail.sh/docs/cli/reference/out-of-office#out-of-office-set); MCP [`setOutOfOffice`](https://nextmail.sh/docs/mcp/tools/workspace#setOutOfOffice).

### `DELETE /out-of-office`

Remove an out of office reply

Removes the saved reply of one address or catch-all, so nothing is answered from it any more. Removing a reply that was never saved changes nothing. To pause a reply and keep its text, save it with `enabled: false` instead.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Query parameters**

- `address` (`string`, required, up to 320 characters): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.

**Returns**

- `200` `DeletedOutOfOffice`: Removed.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.outOfOffice.clear()`](https://nextmail.sh/docs/sdk/reference/out-of-office#clear); Python [`out_of_office.clear()`](https://nextmail.sh/docs/python/reference/out-of-office#clear); Ruby [`out_of_office.clear`](https://nextmail.sh/docs/ruby/reference/out-of-office#clear); PHP [`outOfOffice->clear`](https://nextmail.sh/docs/php/reference/out-of-office#clear); Go [`OutOfOffice.Clear`](https://nextmail.sh/docs/go/reference/out-of-office#clear); Java [`outOfOffice().clear`](https://nextmail.sh/docs/java/reference/out-of-office#clear); C# [`OutOfOffice.ClearAsync`](https://nextmail.sh/docs/csharp/reference/out-of-office#clear); CLI [`nextmail out-of-office clear`](https://nextmail.sh/docs/cli/reference/out-of-office#out-of-office-clear); MCP [`clearOutOfOffice`](https://nextmail.sh/docs/mcp/tools/workspace#clearOutOfOffice).

### `GET /signatures`

List signatures

Every signature in the workspace, by address and then oldest first, or the signatures of one address with `address`. An address keeps a list of named signatures, as the Signature tab of an address shows it. At most one is the default for new mail (`isDefault`) and at most one the default for replies and forwards (`isReplyDefault`), and they can be the same one. A key or an app limited to particular addresses or domains reaches only the signatures of the addresses it holds, and those of a catch-all only when it holds the domain whole.

Requires the `settings:read` scope.

- Scopes: `settings:read`.

**Query parameters**

- `address` (`string`, up to 320 characters): One address, such as `hello@example.com`, or `*@example.com` for the catch-all of a domain. Left out, the list holds every address.
- `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100.
- `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`.

**Returns**

- `200` `SignatureList`: A page of signatures.

**Errors**

- `422`: `invalid_parameter`: `address` is not an address or names a whole domain. `capability_unsupported`: the key or app does not hold that address.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.list()`](https://nextmail.sh/docs/sdk/reference/signatures#list), [`nextmail.signatures.listAll()`](https://nextmail.sh/docs/sdk/reference/signatures#listAll), [`nextmail.signatures.iterate()`](https://nextmail.sh/docs/sdk/reference/signatures#iterate); Python [`signatures.list()`](https://nextmail.sh/docs/python/reference/signatures#list), [`signatures.list_all()`](https://nextmail.sh/docs/python/reference/signatures#listAll), [`signatures.iterate()`](https://nextmail.sh/docs/python/reference/signatures#iterate); Ruby [`signatures.list`](https://nextmail.sh/docs/ruby/reference/signatures#list), [`signatures.list_all`](https://nextmail.sh/docs/ruby/reference/signatures#listAll), [`signatures.iterate`](https://nextmail.sh/docs/ruby/reference/signatures#iterate); PHP [`signatures->list`](https://nextmail.sh/docs/php/reference/signatures#list), [`signatures->listAll`](https://nextmail.sh/docs/php/reference/signatures#listAll), [`signatures->iterate`](https://nextmail.sh/docs/php/reference/signatures#iterate); Go [`Signatures.List`](https://nextmail.sh/docs/go/reference/signatures#list), [`Signatures.ListAll`](https://nextmail.sh/docs/go/reference/signatures#listAll), [`Signatures.Iterate`](https://nextmail.sh/docs/go/reference/signatures#iterate); Java [`signatures().list`](https://nextmail.sh/docs/java/reference/signatures#list), [`signatures().listAll`](https://nextmail.sh/docs/java/reference/signatures#listAll), [`signatures().iterate`](https://nextmail.sh/docs/java/reference/signatures#iterate); C# [`Signatures.ListAsync`](https://nextmail.sh/docs/csharp/reference/signatures#list), [`Signatures.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/signatures#listAll), [`Signatures.IterateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#iterate); CLI [`nextmail signatures list`](https://nextmail.sh/docs/cli/reference/signatures#signatures-list); MCP [`listSignatures`](https://nextmail.sh/docs/mcp/tools/workspace#listSignatures).

### `POST /signatures`

Create a signature

Adds a signature to one address, or to a catch-all with `*@example.com`. The HTML is sanitised on write, as outgoing mail is. The first signature of an address becomes its default for new mail and for replies unless `isDefault` or `isReplyDefault` says otherwise, and a later one becomes a default only when asked. Making one the default takes that place from the signature that held it. An address holds at most 50 signatures.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Request body**

- `address` (`string`, required, 3 to 320 characters): The address the signature is for, such as hello@example.com, or *@example.com for the catch-all of a domain.
- `name` (`string`, required, 1 to 80 characters): What the signature is called. Unique on its address, whatever the case.
- `html` (`string`, required, 1 to 150000 characters): The signature as HTML. It is sanitised on write and has to keep some text or an image.
- `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it.
- `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it.

**Returns**

- `201` `Signature`: The signature, read back as it is stored.

**Errors**

- `409`: `signature_name_taken`: the address already has a signature with that name.
- `422`: `invalid_parameter`: a field is missing or malformed, `address` is not an address of the workspace or names a whole domain, or the signature is empty once it is cleaned up. `signature_too_long`: it is too long before or after cleaning. `signature_limit_reached`: the address is full. `capability_unsupported`: the key or app does not hold that address.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.create()`](https://nextmail.sh/docs/sdk/reference/signatures#create); Python [`signatures.create()`](https://nextmail.sh/docs/python/reference/signatures#create); Ruby [`signatures.create`](https://nextmail.sh/docs/ruby/reference/signatures#create); PHP [`signatures->create`](https://nextmail.sh/docs/php/reference/signatures#create); Go [`Signatures.Create`](https://nextmail.sh/docs/go/reference/signatures#create); Java [`signatures().create`](https://nextmail.sh/docs/java/reference/signatures#create); C# [`Signatures.CreateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#create); CLI [`nextmail signatures create`](https://nextmail.sh/docs/cli/reference/signatures#signatures-create); MCP [`createSignature`](https://nextmail.sh/docs/mcp/tools/workspace#createSignature).

### `GET /signatures/{id}`

Read a signature

One signature by its id. A key or an app limited to particular addresses or domains reaches only the signatures of the addresses it holds, and those of a catch-all only when it holds the domain whole.

Requires the `settings:read` scope.

- Scopes: `settings:read`.

**Path parameters**

- `id` (`string`, required): The signature, as `GET /signatures` returns it.

**Returns**

- `200` `Signature`: The signature.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.get()`](https://nextmail.sh/docs/sdk/reference/signatures#get); Python [`signatures.get()`](https://nextmail.sh/docs/python/reference/signatures#get); Ruby [`signatures.get`](https://nextmail.sh/docs/ruby/reference/signatures#get); PHP [`signatures->get`](https://nextmail.sh/docs/php/reference/signatures#get); Go [`Signatures.Get`](https://nextmail.sh/docs/go/reference/signatures#get); Java [`signatures().get`](https://nextmail.sh/docs/java/reference/signatures#get); C# [`Signatures.GetAsync`](https://nextmail.sh/docs/csharp/reference/signatures#get); CLI [`nextmail signatures get`](https://nextmail.sh/docs/cli/reference/signatures#signatures-get); MCP [`listSignatures`](https://nextmail.sh/docs/mcp/tools/workspace#listSignatures).

### `PATCH /signatures/{id}`

Update a signature

Renames a signature, rewrites its HTML, or changes what it is the default for. Send only what changes. `isDefault: true` makes it the default for new mail in place of the one that was, and `isDefault: false` leaves new mail from the address with no signature when this one was the default. `isReplyDefault` does the same for replies and forwards. A message that is already scheduled picks up the new HTML when it goes out.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Path parameters**

- `id` (`string`, required): The signature, as `GET /signatures` returns it.

**Request body**

- `name` (`string`, 1 to 80 characters): What the signature is called. Unique on its address, whatever the case.
- `html` (`string`, 1 to 150000 characters): The signature as HTML. It is sanitised on write and has to keep some text or an image.
- `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it.
- `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it.

**Returns**

- `200` `Signature`: The signature after the change.

**Errors**

- `409`: `signature_name_taken`: the address already has a signature with that name.
- `422`: `invalid_parameter`: nothing to change was sent, a field is malformed, or the signature is empty once it is cleaned up. `signature_too_long`: it is too long before or after cleaning. `capability_unsupported`: the key or app does not hold the address the signature belongs to.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.update()`](https://nextmail.sh/docs/sdk/reference/signatures#update); Python [`signatures.update()`](https://nextmail.sh/docs/python/reference/signatures#update); Ruby [`signatures.update`](https://nextmail.sh/docs/ruby/reference/signatures#update); PHP [`signatures->update`](https://nextmail.sh/docs/php/reference/signatures#update); Go [`Signatures.Update`](https://nextmail.sh/docs/go/reference/signatures#update); Java [`signatures().update`](https://nextmail.sh/docs/java/reference/signatures#update); C# [`Signatures.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/signatures#update); CLI [`nextmail signatures update`](https://nextmail.sh/docs/cli/reference/signatures#signatures-update); MCP [`updateSignature`](https://nextmail.sh/docs/mcp/tools/workspace#updateSignature).

### `DELETE /signatures/{id}`

Delete a signature

Deletes a signature for good. When it was a default, that default is left empty, so mail it would have signed goes out with no signature until another one is chosen. A scheduled message that named it with `signatureId` carries the default of its address instead.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Path parameters**

- `id` (`string`, required): The signature, as `GET /signatures` returns it.

**Returns**

- `200` `DeletedSignature`: Deleted.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.delete()`](https://nextmail.sh/docs/sdk/reference/signatures#delete); Python [`signatures.delete()`](https://nextmail.sh/docs/python/reference/signatures#delete); Ruby [`signatures.delete`](https://nextmail.sh/docs/ruby/reference/signatures#delete); PHP [`signatures->delete`](https://nextmail.sh/docs/php/reference/signatures#delete); Go [`Signatures.Delete`](https://nextmail.sh/docs/go/reference/signatures#delete); Java [`signatures().delete`](https://nextmail.sh/docs/java/reference/signatures#delete); C# [`Signatures.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/signatures#delete); CLI [`nextmail signatures delete`](https://nextmail.sh/docs/cli/reference/signatures#signatures-delete); MCP [`deleteSignature`](https://nextmail.sh/docs/mcp/tools/workspace#deleteSignature).

### `POST /signatures/{id}/copy`

Copy a signature to other addresses

Puts a copy of a signature on up to 500 other addresses or catch-alls, as Copy to other addresses does in the app. An address that already has a signature with the same name gets its HTML replaced, so copying again after an edit brings every copy up to date, and any other address gets a new signature. A copy becomes a default where `isDefault` or `isReplyDefault` says so, and on an address that had no signature at all. The address the signature is already on is skipped. Each copy is its own signature from then on.

Requires the `settings:write` scope.

- Scopes: `settings:write`.

**Path parameters**

- `id` (`string`, required): The signature, as `GET /signatures` returns it.

**Request body**

- `addresses` (`string[]`, required, 1 to 500 items): The addresses to copy it to. Each is one address or *@example.com for a catch-all.
- `isDefault` (`boolean`): true makes it the signature of new mail from the address. false takes that away when it held it.
- `isReplyDefault` (`boolean`): true makes it the signature of replies and forwards from the address. false takes that away when it held it.

**Returns**

- `200` `SignatureCopyList`: The copies, one for each address.

**Errors**

- `422`: `invalid_parameter`: `addresses` is empty or too long, or one of them is not an address of the workspace or names a whole domain. `signature_limit_reached`: one of the addresses is full, and the addresses before it already have their copy. `capability_unsupported`: the key or app does not hold one of the addresses.
- The errors every operation can return: `400`, `401`, `403`, `404`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.signatures.copy()`](https://nextmail.sh/docs/sdk/reference/signatures#copy); Python [`signatures.copy()`](https://nextmail.sh/docs/python/reference/signatures#copy); Ruby [`signatures.copy`](https://nextmail.sh/docs/ruby/reference/signatures#copy); PHP [`signatures->copy`](https://nextmail.sh/docs/php/reference/signatures#copy); Go [`Signatures.Copy`](https://nextmail.sh/docs/go/reference/signatures#copy); Java [`signatures().copy`](https://nextmail.sh/docs/java/reference/signatures#copy); C# [`Signatures.CopyAsync`](https://nextmail.sh/docs/csharp/reference/signatures#copy); CLI [`nextmail signatures copy`](https://nextmail.sh/docs/cli/reference/signatures#signatures-copy); MCP [`copySignature`](https://nextmail.sh/docs/mcp/tools/workspace#copySignature).

### Objects

#### `Branding`

`object`

The brand of the workspace: its images, its fonts and the background of its sign-in page. The logo is what brands the web app address, `GET /app-host`, and, on a paid plan, the emails Nextmail sends for the workspace; without one both look like Nextmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, whether or not a logo is set. A personal space carries no brand, so every image and font is null there.

- `object` (`string`, one of `"branding"`)
- `editable` (`boolean`): Whether this key may change the brand: false in a personal space, without `settings:write`, or for a key limited to particular addresses or domains.
- `images` (`object`): A link to each brand image, or null when it is not set.
  - `mark` (`string`, nullable): The square mark, or null.
  - `wordmark` (`string`, nullable): The logo, or null.
  - `wordmarkDark` (`string`, nullable): The logo for dark mode, or null. Without it the logo shows in dark mode too.
  - `loginBackground` (`string`, nullable): The photo behind the sign-in page, or null.
- `fonts` (`object`): The two fonts of the brand, each a font id from the supported list or null for the default.
  - `primary` (`string`, nullable, one of `"system"`, `"arial"`, `"helvetica"`, `"verdana"`, `"tahoma"`, `"trebuchet-ms"`, `"georgia"`, `"times-new-roman"`, `"courier-new"`, `"dm-sans"`, `"inter"`, `"roboto"`, `"open-sans"`, `"lato"`, `"montserrat"`, `"poppins"`, `"nunito"`, `"work-sans"`, `"source-sans-3"`, `"ibm-plex-sans"`, `"merriweather"`, `"playfair-display"`, `"instrument-serif"`, `"jetbrains-mono"`, `"dm-mono"`, `"geist-mono"`): The primary font, or null for the default.
  - `secondary` (`string`, nullable, one of `"system"`, `"arial"`, `"helvetica"`, `"verdana"`, `"tahoma"`, `"trebuchet-ms"`, `"georgia"`, `"times-new-roman"`, `"courier-new"`, `"dm-sans"`, `"inter"`, `"roboto"`, `"open-sans"`, `"lato"`, `"montserrat"`, `"poppins"`, `"nunito"`, `"work-sans"`, `"source-sans-3"`, `"ibm-plex-sans"`, `"merriweather"`, `"playfair-display"`, `"instrument-serif"`, `"jetbrains-mono"`, `"dm-mono"`, `"geist-mono"`): The secondary font, or null for the default.
- `loginBackground` (`object`, nullable): What the sign-in page of the web app address shows behind the form, or null for the default. `kind` picks one of three: a `preset`, a `color` or the uploaded `image`. The value for the other kinds may be kept, so switching back restores it.
  - `kind` (`string`, required, one of `"preset"`, `"color"`, `"image"`): `preset` shows `preset`, `color` fills it with `color`, and `image` shows the image uploaded with `PUT /branding/images/login-background`. `image` is refused with 422 `invalid_parameter` until that image is uploaded, and once it is removed the background falls back to the `preset` or `color` kept with it, or to null.
  - `preset` (`string`, nullable, one of `"dusk"`, `"mist"`, `"sand"`, `"night"`, `"meadow"`, `"dots"`, `"brush"`, `"trail"`, `"ember"`, `"canvas"`, `"bloom"`, `"field"`, `"wanderer"`, `"gold"`): One of the built-in backgrounds. Required when `kind` is `preset`.
  - `color` (`string`, nullable, pattern `^#[0-9a-f]{6}$`): A colour as `#` and six hex digits, such as `#1f2937`, stored lowercased. Required when `kind` is `color`.
  - `logo` (`string`, nullable, one of `"dark"`, `"light"`): Which logo the sign-in page shows: `dark`, your logo, or `light`, your logo for dark mode (Nextmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.

#### `DeletedOutOfOffice`

`object`

- `object` (`string`, required, one of `"out_of_office"`)
- `address` (`string`, required)
- `deleted` (`boolean`, required, one of `true`)

#### `DeletedSignature`

`object`

- `object` (`string`, required, one of `"signature"`)
- `id` (`string`, required)
- `address` (`string`, required): The address the signature belonged to.
- `deleted` (`boolean`, required, one of `true`)

#### `OutOfOffice`

`object`

- `object` (`string`, required, one of `"out_of_office"`)
- `address` (`string`, required): The address the reply is for, or `*@example.com` for a catch-all.
- `enabled` (`boolean`, required): Whether the reply is switched on.
- `active` (`boolean`, required): Whether mail arriving now is answered: it is on, `startsAt` has passed and `endsAt` has not.
- `startsAt` (`string`, required, nullable, format `date-time`): When the reply starts. Null when none was ever saved.
- `endsAt` (`string`, required, nullable, format `date-time`): When it stops. Null keeps it on until it is switched off.
- `subject` (`string`, required, up to 255 characters): The subject of the reply. Empty answers with `Re:` and the subject received.
- `message` (`string`, required, up to 10000 characters): The reply, as plain text. Line breaks are kept.
- `contactsOnly` (`boolean`, required): Answer only contacts and people the workspace has written to.
- `updatedAt` (`string`, required, nullable, format `date-time`): The last save. Null when none was ever saved.

#### `OutOfOfficeList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`OutOfOffice[]`)

#### `Settings`

`object`

- `object` (`string`, required, one of `"settings"`)
- `address` (`string`, required, nullable): The scope the call named, lowercased: an address, `*@domain` for a catch-all or `@domain` for a whole domain. Null when the call named none.
- `timezone` (`string`, required)
- `timeFormat` (`string`, required, one of `"12h"`, `"24h"`, default `"24h"`)
- `dateFormat` (`string`, required, one of `"dmy"`, `"mdy"`, `"ymd"`, default `"dmy"`)
- `weekStart` (`string`, required, one of `"monday"`, `"sunday"`, default `"monday"`)
- `workspaceName` (`string`)
- `externalImages` (`boolean`, required, default `true`)
- `semanticSearch` (`boolean`, required, default `true`)
- `replySuggestions` (`boolean`, required, default `true`)
- `knowledgeLearning` (`boolean`, required, default `true`)
- `trustedSenders` (`string[]`)
- `colorTheme` (`string`, required, one of `"light"`, `"dark"`, `"system"`, default `"system"`)
- `openEmailSignature` (`boolean`, required, default `true`)
- `signature` (`string`, required, up to 150000 characters)
- `defaultEmailAlias` (`string`)
- `undoSendEnabled` (`boolean`, required, default `false`)
- `trackOpens` (`boolean`, required, default `false`)
- `trackClicks` (`boolean`, required, default `false`)
- `imageCompression` (`string`, required, one of `"low"`, `"medium"`, `"original"`, default `"medium"`)
- `attachmentDelivery` (`string`, required, one of `"mime"`, `"link"`, `"auto"`, default `"auto"`)
- `autoRead` (`boolean`, required, default `true`)
- `aiWrittenLabel` (`boolean`, required, default `true`)
- `animations` (`boolean`, required, default `true`)
- `desktopNewMail` (`boolean`, required, default `true`)
- `desktopOnlyWhenHidden` (`boolean`, required, default `false`)
- `phoneNewMail` (`boolean`, required, default `true`)
- `phoneReplies` (`boolean`, required, default `true`)
- `phoneScheduledSend` (`boolean`, required, default `false`)
- `phoneFollowUps` (`boolean`, required, default `true`)
- `inboxTabs` (`boolean`, required, default `false`)
- `primaryOnlyAlerts` (`boolean`, required, default `true`)
- `phoneSendFailures` (`boolean`, required, default `true`)
- `phonePreviews` (`boolean`, required, default `true`)
- `phoneSound` (`boolean`, required, default `true`)
- `phoneMutedWorkspaces` (`string[]`, required, up to 200 items, default `[]`)
- `soundNewMail` (`boolean`, required, default `true`)
- `soundAiDone` (`boolean`, required, default `true`)
- `soundSent` (`boolean`, required, default `true`)
- `blockedSenders` (`string[]`, required, default `[]`)
- `blockedDomains` (`string[]`, required, default `[]`)
- `blockedWords` (`string[]`, required, default `[]`)
- `useDefaultBlockedWords` (`boolean`, required, default `false`)
- `translateLanguage` (`string`, required, default `""`)
- `translateReplies` (`boolean`, required, default `true`)
- `showAvatarToContacts` (`boolean`, required, default `true`)
- `lookupContactPhotos` (`boolean`, required, default `true`)
- `marketingSenderName` (`string`, required, up to 120 characters, default `""`, pattern `^[^\u0000-\u001F\u007F]*$`)
- `marketingPostalAddress` (`string`, required, up to 500 characters, default `""`, pattern `^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$`)
- `overrides` (`object`, required): What the scope sets itself, the fields a PATCH to the same scope can send `null` for. Without `address` it is the workspace's own privacy fields, with an address or a catch-all its own signature, footer, tracking, `externalImages`, `trustedSenders` and blocklist, and with `@domain` its own `externalImages`, `trustedSenders` and blocklist. A field that is not here is inherited.
  - `signature` (`string`, up to 150000 characters)
  - `openEmailSignature` (`boolean`)
  - `trackOpens` (`boolean`)
  - `trackClicks` (`boolean`)
  - `externalImages` (`boolean`)
  - `trustedSenders` (`string[]`)
  - `blockedSenders` (`string[]`)
  - `blockedDomains` (`string[]`)
  - `blockedWords` (`string[]`)
  - `useDefaultBlockedWords` (`boolean`)
  - `semanticSearch` (`boolean`)
  - `replySuggestions` (`boolean`)
  - `knowledgeLearning` (`boolean`)
  - `marketingSenderName` (`string`, up to 120 characters, pattern `^[^\u0000-\u001F\u007F]*$`)
  - `marketingPostalAddress` (`string`, up to 500 characters, pattern `^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$`)

#### `Signature`

`object`

- `object` (`string`, required, one of `"signature"`)
- `id` (`string`, required): The id, which starts with `sig_`.
- `address` (`string`, required): The address the signature belongs to, or `*@example.com` for a catch-all.
- `name` (`string`, required, up to 80 characters): What the signature is called in the app. Unique on its address, whatever the case.
- `html` (`string`, required, up to 150000 characters): The signature as sanitised HTML, the way it is added under a message.
- `isDefault` (`boolean`, required): Whether new mail from the address carries this signature unless the send says otherwise.
- `isReplyDefault` (`boolean`, required): Whether replies and forwards from the address carry this signature unless the send says otherwise.
- `createdAt` (`string`, required, format `date-time`): When the signature was created.
- `updatedAt` (`string`, required, format `date-time`): When its name or HTML last changed.

#### `SignatureCopyList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`Signature[]`)

#### `SignatureList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`Signature[]`)
- `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it.
- `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.