---
title: "nextmail settings"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/settings"
area: "CLI"
category: "Reference"
---

# nextmail settings

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail settings get`

Read settings

```bash
nextmail settings get [flags]
```

Returns every setting with defaults filled in, so a field that was never saved still has a value and reading one never depends on which release introduced it. Every field is typed on `SettingsResource`.

Without `--address` it is your account and the workspace. The account fields (time zone and formats, theme, sounds, notifications and the rest) 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: one address, `*@domain` for a catch-all or `@domain` for a whole domain. For an 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 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, the fields `update` can send `null` for at the same scope, and everything not in it is inherited. `address` on the result is the scope you named, lowercased, or null.

- Scopes: `settings:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Flags**

- `--address <value>`: The scope to read: one address, `*@domain` for the catch-all of a domain, or `@domain` for a whole domain. 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 the call is a 422 `capability_unsupported`.

**Examples**

```bash
nextmail settings get
```

With optional flags

```bash
nextmail settings get --address sales@example.com
```

Print the raw JSON

```bash
nextmail settings get --json
```

Also available in: API [`GET /settings`](https://nextmail.sh/docs/api/reference/settings#get-settings); 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).

### `nextmail settings update`

Change settings

```bash
nextmail settings update [flags]
```

A partial update: fields you send are validated and saved, fields you leave out keep their values, a list replaces the old one, and the response is the full settings object read back after the write, in the same shape `get` returns for the same scope.

Without `--address` it 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. `--workspace-name` renames the workspace, and is a 422 `invalid_parameter` on a personal space, which has no name of its own. The privacy fields (`--external-images`, `--trusted-senders`, `--blocked-senders`, `--blocked-domains`, `--blocked-words`, `--use-default-blocked-words`, `--semantic-search`, `--reply-suggestions`, `--knowledge-learning`) and the marketing footer fields (`--marketing-sender-name`, `--marketing-postal-address`) 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 a 422 `capability_unsupported`. `signature`, `--open-email-signature`, `--track-opens` and `--track-clicks` are refused there with a 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 workspace: its mail stops going to the embedding model, what was stored is deleted at once, and `threads.list` with `semantic: true` runs a text search until it is turned back on. `replySuggestions: false` turns suggested replies off for the workspace: no thread goes to a model for them any more, what was stored is deleted at once, and `threads.replySuggestions` answers `none` until it is turned back on. `knowledgeLearning: false` stops the knowledge base learning for the workspace: no sent reply is read for facts to suggest, no question is noted from incoming mail, and no pair of items is checked for a conflict, while what was already suggested stays for review. Keys the settings schema does not know are dropped silently rather than refused, and a known key with the wrong type, or `null` for a field that cannot be cleared, is a 422 `invalid_parameter` naming it.

With `--address`, the patch gives that scope a choice of its own. One address or a catch-all (`*@domain`) takes `signature`, `--open-email-signature`, `--track-opens`, `--track-clicks`, `--external-images`, `--trusted-senders`, `--blocked-senders`, `--blocked-domains`, `--blocked-words` and `--use-default-blocked-words`, 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, and `overrides` on the result lists what the scope still sets itself. Any other field is a 422 `not_per_address` naming it, `--semantic-search`, `--reply-suggestions`, `--knowledge-learning` 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 the call is a 422 `invalid_parameter` on `address`. 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.

`signature` is HTML added to mail sent from the address, and is sanitised on write, so the value you get back is what will actually be sent. More than 150,000 characters is a 422 `signature_too_long`, checked before sanitising and again after it. Mail sent through this API carries it only when the send sets `signature: true`, and template sends and encrypted sends never do.

- Scopes: `settings:write`.
- Needs a sign-in.
- Aliases: `edit`.

**Flags**

- `--signature <value>`: HTML of the default signature of the address named by `--address`, the one new mail from it carries, at most 150,000 characters, sanitised on write. An address keeps a list of signatures, which `signatures.list` 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.
- `--open-email-signature`: Adds the Nextmail footer to mail from the address while its `signature` is empty. On by default. `null` removes the address's own value. Only with an address or a catch-all.
- `--track-opens`: Open tracking on mail from the address, for sends that do not set `tracking.opens`. Off by default. `null` removes the address's own value. Only with an address or a catch-all.
- `--track-clicks`: Link tracking on mail from the address, for sends that do not set `tracking.clicks`. Off by default. `null` removes the address's own value. Only with an address or a catch-all.
- `--external-images`: Loads pictures in mail automatically. Off means senders cannot tell you read it. On by default. The workspace's choice without `--address`, and that scope's own with it. `null` removes the scope's own value.
- `--trusted-senders <a,b>` (repeatable): Senders whose pictures always load while `--external-images` is off. Replaces the whole list. The workspace's list without `--address`, and that scope's own with it. `null` removes the scope's own list.
- `--blocked-senders <a,b>` (repeatable): Senders whose mail is refused on arrival, plus-tags included. Mail already delivered stays. Replaces the whole list. The workspace's list without `--address`, and that scope's own with it. `null` removes the scope's own list.
- `--blocked-domains <a,b>` (repeatable): Domains whose mail is refused on arrival, subdomains included. Replaces the whole list. The workspace's list without `--address`, and that scope's own with it. `null` removes the scope's own list.
- `--blocked-words <a,b>` (repeatable): Words that open matching mail behind a warning. Nothing is deleted. Replaces the whole list. The workspace's list without `--address`, and that scope's own with it. `null` removes the scope's own list.
- `--use-default-blocked-words`: Adds the built-in list of English profanities and slurs to `--blocked-words`. Off by default. The workspace's choice without `--address`, and that scope's own with it. `null` removes the scope's own value.
- `--semantic-search`: 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`.
- `--reply-suggestions`: 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`.
- `--knowledge-learning`: Knowledge base learning for the whole workspace: notes suggested from sent replies, questions noted from incoming mail and conflict checks. On by default, and `null` turns it back on. Not with `--address`.
- `--marketing-sender-name <value>`: Who the footer of broadcasts and automation emails names as the sender, one line of at most 120 characters. Empty, the default, uses the workspace name, and `null` empties it. Not with `--address`.
- `--marketing-postal-address <value>`: The postal address that footer shows, at most 500 characters on one line or several, which many countries require of marketing email. Empty, the default, shows none, and `null` empties it. Not with `--address`.
- `--workspace-name <value>`: Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `--address`.
- `--timezone <value>`: IANA zone name such as `Europe/Berlin`, saved as given without checking it. Saved on the account.
- `--time-format <value>`: `12h` or `24h`, how the app writes times. Saved on the account.
- `--date-format <value>`: `dmy`, `mdy` or `ymd`, the order the app writes dates in. Saved on the account.
- `--week-start <value>`: `monday` or `sunday`, the first day of the week in the calendar and date pickers. Saved on the account.
- `--color-theme <value>`: `light`, `dark` or `system`, the app's theme. Saved on the account.
- `--default-email-alias <value>`: Address the app composer preselects as From. Saved on the account.
- `--undo-send-enabled`: Holds each send from the app for 30 seconds so it can be cancelled. Off by default. Saved on the account.
- `--image-compression <value>`: `low`, `medium` or `original`, how far pictures attached in the app are compressed before they are sent. Saved on the account.
- `--attachment-delivery <value>`: How files go out on a send that does not set `--attachment-delivery` itself: `mime` attaches them, `link` sends download links, and `auto` links large files only, which needs a files address. Saved on the account.
- `--auto-read`: Marks mail read when you open it in the app. Saved on the account.
- `--ai-written-label`: 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`: Motion in the app. Off makes everything appear at once. Saved on the account.
- `--desktop-new-mail`: A desktop notification when a message reaches the inbox while the app is open in a browser that allows them. Saved on the account.
- `--desktop-only-when-hidden`: Desktop notifications only while the tab is hidden. Saved on the account.
- `--phone-new-mail`: A push to your phones when a message reaches the inbox. Saved on the account.
- `--phone-replies`: A push to your phones when someone answers your mail. Saved on the account.
- `--phone-scheduled-send`: A push to your phones when a scheduled message goes out. Saved on the account.
- `--phone-follow-ups`: A push to your phones when a message you asked to be reminded about has had no reply by then. Saved on the account.
- `--phone-send-failures`: A push to your phones when a message fails to send. Saved on the account.
- `--inbox-tabs`: 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.
- `--primary-only-alerts`: With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
- `--phone-previews`: Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
- `--phone-sound`: Plays a sound with each push. Off makes them silent. Saved on the account.
- `--phone-muted-workspaces <a,b>` (repeatable): Workspace ids whose mail sends no push to your phones. Replaces the whole list. `account.setPushMuted` changes one workspace at a time. Saved on the account.
- `--sound-new-mail`: Chimes when mail arrives while the app is open. Saved on the account.
- `--sound-ai-done`: Chimes when the assistant finishes a reply. Saved on the account.
- `--sound-sent`: Chimes when your message goes out. Saved on the account.
- `--translate-language <value>`: The language Translate offers first, a language code such as `de`. Empty means English. Saved on the account.
- `--translate-replies`: Opens replies on threads you translated already translated into your language. Saved on the account.
- `--show-avatar-to-contacts`: Shows your profile photo to Nextmail users on your address. Saved on the account.
- `--lookup-contact-photos`: Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
- `--address <value>`: The scope the patch gives a choice of its own: one address, `*@domain` for the catch-all of a domain, or `@domain` for a whole domain. 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 the call is a 422 `capability_unsupported`.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

With optional flags

```bash
nextmail settings update --signature '<p>Ada Lovelace<br>Analytical Engines Ltd</p>' --no-track-clicks --no-external-images
```

Print the raw JSON

```bash
nextmail settings update --signature '<p>Ada Lovelace<br>Analytical Engines Ltd</p>' --no-track-clicks --no-external-images --json
```

Also available in: API [`PATCH /settings`](https://nextmail.sh/docs/api/reference/settings#patch-settings); 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).