--- title: "client.settings" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://nextmail.sh/docs/ruby/reference/settings" area: "Ruby" category: "Reference" --- # client.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. ### `settings.get` Read settings ```ruby get(address: nil, api_key: nil) -> Hash ``` 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 setting is a key of the returned Hash. 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 `nil` for at the same scope, and everything not in it is inherited. `address` on the result is the scope you named, lowercased, or nil. Scopes: `settings:read`. **Parameters** - `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`. - `api_key` (`String`): Overrides the client's API key for this call only. **Returns** A Hash with `object` set to `settings`, every setting and the scope's own `overrides`. **Example** ```ruby settings = client.settings.get puts settings[:timezone], settings[:timeFormat] sales = client.settings.get(address: "sales@example.com") p 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); TypeScript [`nextmail.settings.get()`](https://nextmail.sh/docs/sdk/reference/settings#get); Python [`settings.get()`](https://nextmail.sh/docs/python/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 ```ruby update(patch = nil, address: nil, api_key: nil, **fields) -> Hash ``` 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 Hash 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 `nil` 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 `nil` 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. `nil` 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** - `signature` (`String or nil`): 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 `nil` 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. - `openEmailSignature` (`Boolean or nil`): Adds the Nextmail footer to mail from the address while its `signature` is empty. On by default. `nil` removes the address's own value. Only with an address or a catch-all. - `trackOpens` (`Boolean or nil`): Open tracking on mail from the address, for sends that do not set `tracking.opens`. Off by default. `nil` removes the address's own value. Only with an address or a catch-all. - `trackClicks` (`Boolean or nil`): Link tracking on mail from the address, for sends that do not set `tracking.clicks`. Off by default. `nil` removes the address's own value. Only with an address or a catch-all. - `externalImages` (`Boolean or nil`): 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. `nil` removes the scope's own value. - `trustedSenders` (`Array or nil`): 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. `nil` removes the scope's own list. - `blockedSenders` (`Array or nil`): 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. `nil` removes the scope's own list. - `blockedDomains` (`Array or nil`): 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. `nil` removes the scope's own list. - `blockedWords` (`Array or nil`): 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. `nil` removes the scope's own list. - `useDefaultBlockedWords` (`Boolean or nil`): 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. `nil` removes the scope's own value. - `semanticSearch` (`Boolean or nil`): 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 `nil` turns it back on. Not with `address:`. - `replySuggestions` (`Boolean or nil`): 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 `nil` turns them back on. Not with `address:`. - `knowledgeLearning` (`Boolean or nil`): Knowledge base learning for the whole workspace: notes suggested from sent replies, questions noted from incoming mail and conflict checks. On by default, and `nil` turns it back on. Not with `address:`. - `marketingSenderName` (`String or nil`): 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 `nil` empties it. Not with `address:`. - `marketingPostalAddress` (`String or nil`): 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 `nil` empties it. Not with `address:`. - `workspaceName` (`String`): Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `address:`. - `timezone` (`String`): IANA zone name such as `Europe/Berlin`, saved as given without checking it. Saved on the account. - `timeFormat` (`String`): `12h` or `24h`, how the app writes times. Saved on the account. - `dateFormat` (`String`): `dmy`, `mdy` or `ymd`, the order the app writes dates in. Saved on the account. - `weekStart` (`String`): `monday` or `sunday`, the first day of the week in the calendar and date pickers. Saved on the account. - `colorTheme` (`String`): `light`, `dark` or `system`, the app's theme. Saved on the account. - `defaultEmailAlias` (`String`): Address the app composer preselects as From. 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. - `imageCompression` (`String`): `low`, `medium` or `original`, how far pictures attached in the app are compressed before they are sent. Saved on the account. - `attachmentDelivery` (`String`): 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. - `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. 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. - `phoneSendFailures` (`Boolean`): A push to your phones when a message fails to send. 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. - `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` (`Array`): 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. - `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. - `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. - `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`. - `api_key` (`String`): Overrides the client's API key for this call only. **Returns** A Hash, the full saved settings for the scope you named, in the same shape as `get` with the same `address:`. **Example** ```ruby client.settings.update(timezone: "Europe/London", timeFormat: "24h") saved = client.settings.update( signature: "

Ada Lovelace
Analytical Engines Ltd

", trackClicks: false, externalImages: false, address: "ada@example.com" ) p saved[:address], saved[:signature], saved[:overrides] client.settings.update(externalImages: nil, 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 patch 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); TypeScript [`nextmail.settings.update()`](https://nextmail.sh/docs/sdk/reference/settings#update); Python [`settings.update()`](https://nextmail.sh/docs/python/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).