---
title: "nextmail.settings"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/python/reference/settings"
area: "Python"
category: "Reference"
---

# nextmail.settings

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

Mailbox preferences such as timezone and time format, the workspace's privacy, and the signature, tracking and privacy of each address or domain.

### `settings.get()`

Read settings

```python
def get(
    *,
    address: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SettingsResource
```

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. `SettingsResource` is a plain `dict[str, Any]` with every setting under its own key and the scope's own `overrides`.

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 `None` for at the same scope, and everything not in it is inherited. `address` on the result is the scope you named, lowercased, or `None`.

Scopes: `settings:read`.

**Parameters**

- `address` (`str`): 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`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SettingsResource`, a dict with `'object': 'settings'`, every setting and the scope's own `overrides`.

**Example**

```python
from nextmail import nextmail

workspace = nextmail.settings.get()

print(workspace.get('timezone'), workspace.get('timeFormat'))

sales = nextmail.settings.get(address='sales@example.com')

print(sales.get('signature'), sales.get('trackOpens'), sales.get('trackClicks'))
```

**Notes**

- A stored `signature` longer than 150,000 characters reads back as an empty string instead of failing the request.
- `defaultEmailAlias` only preselects the From address in the app composer. The API never uses it to choose a sender.

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); 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).

### `settings.update()`

Change settings

```python
def update(
    patch: SettingsPatch,
    *,
    address: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SettingsResource
```

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 dict 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. `workspaceName` renames the workspace, and is a 422 `invalid_parameter` on a personal space, which has no name of its own. 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 `None` 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`, `openEmailSignature`, `trackOpens` and `trackClicks` 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.reply_suggestions` 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 `None` 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`, `openEmailSignature`, `trackOpens`, `trackClicks`, `externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords` and `useDefaultBlockedWords`, and a whole domain (`@domain`) the last six only. `None` 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, `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 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`.

**Parameters**

- `patch['signature']` (`str | None`): 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 `None` 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.
- `patch['openEmailSignature']` (`bool | None`): Adds the Nextmail footer to mail from the address while its `signature` is empty. On by default. `None` removes the address's own value. Only with an address or a catch-all.
- `patch['trackOpens']` (`bool | None`): Open tracking on mail from the address, for sends whose `tracking` does not set `opens`. Off by default. `None` removes the address's own value. Only with an address or a catch-all.
- `patch['trackClicks']` (`bool | None`): Link tracking on mail from the address, for sends whose `tracking` does not set `clicks`. Off by default. `None` removes the address's own value. Only with an address or a catch-all.
- `patch['externalImages']` (`bool | None`): 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. `None` removes the scope's own value.
- `patch['trustedSenders']` (`list[str] | None`): Senders whose pictures always load while `externalImages` is off. Replaces the whole list. The workspace's list without `address=`, and that scope's own with it. `None` removes the scope's own list.
- `patch['blockedSenders']` (`list[str] | None`): 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. `None` removes the scope's own list.
- `patch['blockedDomains']` (`list[str] | None`): 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. `None` removes the scope's own list.
- `patch['blockedWords']` (`list[str] | None`): 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. `None` removes the scope's own list.
- `patch['useDefaultBlockedWords']` (`bool | None`): Adds the built-in list of English profanities and slurs to `blockedWords`. Off by default. The workspace's choice without `address=`, and that scope's own with it. `None` removes the scope's own value.
- `patch['semanticSearch']` (`bool | None`): 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=True` run a text search, and `None` turns it back on. Not with `address=`.
- `patch['replySuggestions']` (`bool | None`): 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 `None` turns them back on. Not with `address=`.
- `patch['knowledgeLearning']` (`bool | None`): Knowledge base learning for the whole workspace: notes suggested from sent replies, questions noted from incoming mail and conflict checks. On by default, and `None` turns it back on. Not with `address=`.
- `patch['marketingSenderName']` (`str | None`): 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 `None` empties it. Not with `address=`.
- `patch['marketingPostalAddress']` (`str | None`): 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 `None` empties it. Not with `address=`.
- `patch['workspaceName']` (`str`): Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `address=`.
- `patch['timezone']` (`str`): IANA zone name such as `Europe/Berlin`, saved as given without checking it. Saved on the account.
- `patch['timeFormat']` (`SettingsTimeFormat`): `'12h'` or `'24h'`, how the app writes times, one of `SETTINGS_TIME_FORMATS`. Saved on the account.
- `patch['dateFormat']` (`SettingsDateFormat`): `'dmy'`, `'mdy'` or `'ymd'`, the order the app writes dates in, one of `SETTINGS_DATE_FORMATS`. Saved on the account.
- `patch['weekStart']` (`SettingsWeekStart`): `'monday'` or `'sunday'`, the first day of the week in the calendar and date pickers, one of `SETTINGS_WEEK_STARTS`. Saved on the account.
- `patch['colorTheme']` (`SettingsColorTheme`): `'light'`, `'dark'` or `'system'`, the app's theme, one of `SETTINGS_COLOR_THEMES`. Saved on the account.
- `patch['defaultEmailAlias']` (`str`): Address the app composer preselects as From. Saved on the account.
- `patch['undoSendEnabled']` (`bool`): Holds each send from the app for 30 seconds so it can be cancelled. Off by default. Saved on the account.
- `patch['imageCompression']` (`SettingsImageCompression`): `'low'`, `'medium'` or `'original'`, how far pictures attached in the app are compressed before they are sent, one of `SETTINGS_IMAGE_COMPRESSIONS`. Saved on the account.
- `patch['attachmentDelivery']` (`AttachmentDeliveryMode`): How files go out on a send that does not set `attachmentDelivery` itself: `'mime'` attaches them, `'link'` sends download links, and `'auto'` links large files only, which needs a files address. Saved on the account.
- `patch['autoRead']` (`bool`): Marks mail read when you open it in the app. Saved on the account.
- `patch['aiWrittenLabel']` (`bool`): 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.
- `patch['animations']` (`bool`): Motion in the app. Off makes everything appear at once. Saved on the account.
- `patch['desktopNewMail']` (`bool`): A desktop notification when a message reaches the inbox while the app is open in a browser that allows them. Saved on the account.
- `patch['desktopOnlyWhenHidden']` (`bool`): Desktop notifications only while the tab is hidden. Saved on the account.
- `patch['phoneNewMail']` (`bool`): A push to your phones when a message reaches the inbox. Saved on the account.
- `patch['phoneReplies']` (`bool`): A push to your phones when someone answers your mail. Saved on the account.
- `patch['phoneScheduledSend']` (`bool`): A push to your phones when a scheduled message goes out. Saved on the account.
- `patch['phoneFollowUps']` (`bool`): A push to your phones when a message you asked to be reminded about has had no reply by then. Saved on the account.
- `patch['phoneSendFailures']` (`bool`): A push to your phones when a message fails to send. Saved on the account.
- `patch['inboxTabs']` (`bool`): 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.
- `patch['primaryOnlyAlerts']` (`bool`): With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
- `patch['phonePreviews']` (`bool`): Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
- `patch['phoneSound']` (`bool`): Plays a sound with each push. Off makes them silent. Saved on the account.
- `patch['phoneMutedWorkspaces']` (`list[str]`): Workspace ids whose mail sends no push to your phones. Replaces the whole list. `account.set_push_muted` changes one workspace at a time. Saved on the account.
- `patch['soundNewMail']` (`bool`): Chimes when mail arrives while the app is open. Saved on the account.
- `patch['soundAiDone']` (`bool`): Chimes when the assistant finishes a reply. Saved on the account.
- `patch['soundSent']` (`bool`): Chimes when your message goes out. Saved on the account.
- `patch['translateLanguage']` (`str`): The language Translate offers first, a language code such as `de`. Empty means English. Saved on the account.
- `patch['translateReplies']` (`bool`): Opens replies on threads you translated already translated into your language. Saved on the account.
- `patch['showAvatarToContacts']` (`bool`): Shows your profile photo to Nextmail users on your address. Saved on the account.
- `patch['lookupContactPhotos']` (`bool`): Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
- `address` (`str`): 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`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SettingsResource`, the full saved settings for the scope you named, in the same shape as `get` with the same `address=`.

**Example**

```python
from nextmail import nextmail

nextmail.settings.update({'timezone': 'Europe/London'})

saved = nextmail.settings.update(
    {
        'signature': '<p>Ada Lovelace<br>Analytical Engines Ltd</p>',
        'trackClicks': False,
    },
    address='ada@example.com',
)

print(saved.get('address'), saved.get('signature'), saved.get('trackClicks'))
```

**Notes**

- The SDK retries this call after a network failure or a retryable status, which is safe because the same patch saves the same values.
- An empty dict is accepted, changes nothing and returns the current settings.
- A misspelt zone is saved rather than refused, so check it before sending, for example with `zoneinfo.ZoneInfo`.

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); 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).