--- title: "client.settings()" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://openemail.uk/docs/java/reference/settings" area: "Java" 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 language, and the signature and tracking of each address. ### `settings().get` Read settings ```java Map get(RequestOptions options) ``` 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. Its keys are the fields `update` takes, plus `object`, `address` and `overrides`. Without `address` it is your account and the workspace. The account fields (language, 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, `developerMode` 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 OpenEmail 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`. **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.apiKey` (`String`): Overrides the client's API key for this call only. **Returns** A map with `object` set to `settings`, every setting, `developerMode` and `overrides`, a map of what the scope sets itself. **Example** ```java Map settings = client.settings().get(); System.out.println(settings.get("timezone") + " " + settings.get("timeFormat") + " " + settings.get("developerMode")); ``` **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://openemail.uk/docs/api/reference/settings#get-settings); TypeScript [`settings.get()`](https://openemail.uk/docs/sdk/reference/settings#get); Python [`settings.get()`](https://openemail.uk/docs/python/reference/settings#get); Ruby [`settings.get`](https://openemail.uk/docs/ruby/reference/settings#get); PHP [`settings->get`](https://openemail.uk/docs/php/reference/settings#get); Go [`Settings.Get`](https://openemail.uk/docs/go/reference/settings#get); C# [`Settings.GetAsync`](https://openemail.uk/docs/csharp/reference/settings#get); CLI [`openemail settings get`](https://openemail.uk/docs/cli/reference/settings#settings-get). ### `settings().update` Change settings ```java Map update(Map patch, RequestOptions options) ``` 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 map 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 (language, 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. `developerMode` and the privacy fields (`externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords`, `useDefaultBlockedWords`, `semanticSearch`, `replySuggestions`, `knowledgeLearning`) 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 `RequestOptions.of("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`, `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` and `knowledgeLearning` 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 or null`): HTML signature of the address named by `address`, at most 150,000 characters, sanitised on write. An empty string removes it, and null makes the address use the one it inherits again. Only with an address or a catch-all. - `patch.openEmailSignature` (`boolean`): Adds the OpenEmail 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`): 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`): 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`): 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. - `patch.trustedSenders` (`List or null`): 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. Null removes the scope's own list. - `patch.blockedSenders` (`List or null`): 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. - `patch.blockedDomains` (`List or null`): 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. - `patch.blockedWords` (`List or null`): 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. - `patch.useDefaultBlockedWords` (`boolean`): 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. Null removes the scope's own value. - `patch.semanticSearch` (`boolean`): 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 `RequestOptions.of("semantic", true)` run a text search, and null turns it back on. Not with `address`. - `patch.replySuggestions` (`boolean`): 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`. - `patch.knowledgeLearning` (`boolean`): 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`. - `patch.developerMode` (`boolean`): Developer mode for the whole workspace: on, the app shows API keys, webhooks and ids to everyone in it, and off hides those screens. Keys that exist keep working either way. Off by default, and null puts it back to off. Not with `address`. - `patch.workspaceName` (`String`): Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `address`. - `patch.language` (`String`): Interface language, a locale tag such as `en` or `de`, saved as given without checking it. Saved on the account. - `patch.timezone` (`String`): IANA zone name such as `Europe/Berlin`, saved as given without checking it. Saved on the account. - `patch.timeFormat` (`String`): `12h` or `24h`, also in `uk.openemail.constants.SettingsTimeFormats`, how the app writes times. Saved on the account. - `patch.dateFormat` (`String`): `dmy`, `mdy` or `ymd`, also in `uk.openemail.constants.SettingsDateFormats`, the order the app writes dates in. Saved on the account. - `patch.weekStart` (`String`): `monday` or `sunday`, also in `uk.openemail.constants.SettingsWeekStarts`, the first day of the week in the calendar and date pickers. Saved on the account. - `patch.colorTheme` (`String`): `light`, `dark` or `system`, also in `uk.openemail.constants.SettingsColorThemes`, 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` (`String`): `low`, `medium` or `original`, also in `uk.openemail.constants.SettingsImageCompressions`, how far pictures attached in the app are compressed before they are sent. Saved on the account. - `patch.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. - `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` (`List`): 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 the interface language. 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 OpenEmail 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.apiKey` (`String`): Overrides the client's API key for this call only. **Returns** A map, the full saved settings for the scope you named, in the same shape as `get` with the same `address`. **Example** ```java Map saved = client.settings().update(Body.of("timezone", "Europe/London", "timeFormat", "24h", "developerMode", true)); System.out.println(saved.get("address") + " " + saved.get("signature") + " " + saved.get("overrides")); ``` **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 or language code is saved rather than refused, so validate it before sending. Also available in: API [`PATCH /settings`](https://openemail.uk/docs/api/reference/settings#patch-settings); TypeScript [`settings.update()`](https://openemail.uk/docs/sdk/reference/settings#update); Python [`settings.update()`](https://openemail.uk/docs/python/reference/settings#update); Ruby [`settings.update`](https://openemail.uk/docs/ruby/reference/settings#update); PHP [`settings->update`](https://openemail.uk/docs/php/reference/settings#update); Go [`Settings.Update`](https://openemail.uk/docs/go/reference/settings#update); C# [`Settings.UpdateAsync`](https://openemail.uk/docs/csharp/reference/settings#update); CLI [`openemail settings update`](https://openemail.uk/docs/cli/reference/settings#settings-update).