---
title: "nextmail.settings"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/sdk/reference/settings"
area: "TypeScript"
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, and the signature and tracking of each address.

### `nextmail.settings.get()`

Read settings

```ts
get(options?: SettingsOptions): Promise<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. Every field is typed on `SettingsResource`.

Without `options.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 `options.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`.

**Parameters**

- `options.address` (`string`): 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`.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

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

**Example**

```ts
const settings = await nextmail.settings.get()

console.log(settings.timezone, settings.timeFormat)

const sales = await nextmail.settings.get({ address: 'sales@example.com' })

console.log(sales.signature, sales.externalImages, sales.overrides)
```

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

### `nextmail.settings.update()`

Change settings

```ts
update(patch: SettingsPatch, options?: SettingsOptions): Promise<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 object read back after the write, in the same shape `get` returns for the same scope.

Without `options.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 `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`, `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.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 `options.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. `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, `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` (`string | null`): HTML of the default signature of the address named by `options.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.
- `patch.openEmailSignature` (`boolean | null`): 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.
- `patch.trackOpens` (`boolean | null`): 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.
- `patch.trackClicks` (`boolean | null`): 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.
- `patch.externalImages` (`boolean | null`): Loads pictures in mail automatically. Off means senders cannot tell you read it. On by default. The workspace's choice without `options.address`, and that scope's own with it. `null` removes the scope's own value.
- `patch.trustedSenders` (`Array<string> | null`): Senders whose pictures always load while `externalImages` is off. Replaces the whole list. The workspace's list without `options.address`, and that scope's own with it. `null` removes the scope's own list.
- `patch.blockedSenders` (`Array<string> | null`): Senders whose mail is refused on arrival, plus-tags included. Mail already delivered stays. Replaces the whole list. The workspace's list without `options.address`, and that scope's own with it. `null` removes the scope's own list.
- `patch.blockedDomains` (`Array<string> | null`): Domains whose mail is refused on arrival, subdomains included. Replaces the whole list. The workspace's list without `options.address`, and that scope's own with it. `null` removes the scope's own list.
- `patch.blockedWords` (`Array<string> | null`): Words that open matching mail behind a warning. Nothing is deleted. Replaces the whole list. The workspace's list without `options.address`, and that scope's own with it. `null` removes the scope's own list.
- `patch.useDefaultBlockedWords` (`boolean | null`): Adds the built-in list of English profanities and slurs to `blockedWords`. Off by default. The workspace's choice without `options.address`, and that scope's own with it. `null` removes the scope's own value.
- `patch.semanticSearch` (`boolean | null`): 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 `options.address`.
- `patch.replySuggestions` (`boolean | null`): 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 `options.address`.
- `patch.knowledgeLearning` (`boolean | null`): 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 `options.address`.
- `patch.marketingSenderName` (`string | null`): 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 `options.address`.
- `patch.marketingPostalAddress` (`string | null`): 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 `options.address`.
- `patch.workspaceName` (`string`): Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `options.address`.
- `patch.timezone` (`string`): 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. Saved on the account.
- `patch.dateFormat` (`SettingsDateFormat`): `dmy`, `mdy` or `ymd`, the order the app writes dates in. Saved on the account.
- `patch.weekStart` (`SettingsWeekStart`): `monday` or `sunday`, the first day of the week in the calendar and date pickers. Saved on the account.
- `patch.colorTheme` (`SettingsColorTheme`): `light`, `dark` or `system`, the app's theme. Saved on the account.
- `patch.defaultEmailAlias` (`string`): Address the app composer preselects as From. Saved on the account.
- `patch.undoSendEnabled` (`boolean`): 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. 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` (`boolean`): Marks mail read when you open it in the app. Saved on the account.
- `patch.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.
- `patch.animations` (`boolean`): Motion in the app. Off makes everything appear at once. Saved on the account.
- `patch.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.
- `patch.desktopOnlyWhenHidden` (`boolean`): Desktop notifications only while the tab is hidden. Saved on the account.
- `patch.phoneNewMail` (`boolean`): A push to your phones when a message reaches the inbox. Saved on the account.
- `patch.phoneReplies` (`boolean`): A push to your phones when someone answers your mail. Saved on the account.
- `patch.phoneScheduledSend` (`boolean`): A push to your phones when a scheduled message goes out. Saved on the account.
- `patch.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.
- `patch.phoneSendFailures` (`boolean`): A push to your phones when a message fails to send. Saved on the account.
- `patch.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.
- `patch.primaryOnlyAlerts` (`boolean`): With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
- `patch.phonePreviews` (`boolean`): Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
- `patch.phoneSound` (`boolean`): Plays a sound with each push. Off makes them silent. Saved on the account.
- `patch.phoneMutedWorkspaces` (`Array<string>`): 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.
- `patch.soundNewMail` (`boolean`): Chimes when mail arrives while the app is open. Saved on the account.
- `patch.soundAiDone` (`boolean`): Chimes when the assistant finishes a reply. Saved on the account.
- `patch.soundSent` (`boolean`): Chimes when your message goes out. Saved on the account.
- `patch.translateLanguage` (`string`): The language Translate offers first, a language code such as `de`. Empty means English. Saved on the account.
- `patch.translateReplies` (`boolean`): Opens replies on threads you translated already translated into your language. Saved on the account.
- `patch.showAvatarToContacts` (`boolean`): Shows your profile photo to Nextmail users on your address. Saved on the account.
- `patch.lookupContactPhotos` (`boolean`): Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
- `options.address` (`string`): 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`.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

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

**Example**

```ts
await nextmail.settings.update({ timezone: 'Europe/London', timeFormat: '24h' })

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

console.log(saved.address, saved.signature, saved.overrides)

await nextmail.settings.update({ externalImages: null }, { address: 'ada@example.com' })
```

**Notes**

- The SDK retries this call after a network failure, which is safe because the same patch saves the same values.
- An empty object is accepted, changes nothing and returns the current settings.
- A misspelt zone is saved rather than refused, so validate it before sending.

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