---
title: "client.Settings"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/go/reference/settings"
area: "Go"
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

```go
Get(ctx context.Context, opts ...openemail.RequestOption) (openemail.Object, error)
```

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 a settings object.

Without `openemail.WithAddress` 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 `openemail.WithAddress`, 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**

- `openemail.WithAddress` (`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`.
- `openemail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An `openemail.Object` with `object: 'settings'`, every setting, `developerMode` and the scope's own `overrides`.

**Example**

```go
settings, err := client.Settings.Get(ctx)
if err != nil {
	return err
}

fmt.Println(settings.String("timezone"), settings.String("timeFormat"), settings.Bool("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); Java [`settings().get`](https://openemail.uk/docs/java/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

```go
Update(ctx context.Context, patch openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)
```

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 `openemail.WithAddress` 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 `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 `openemail.WithAddress`, 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**

- `signature` (`string | nil`): HTML signature of the address named by `openemail.WithAddress`, 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.
- `openEmailSignature` (`bool | nil`): 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.
- `trackOpens` (`bool | nil`): 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.
- `trackClicks` (`bool | nil`): 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.
- `externalImages` (`bool | nil`): Loads pictures in mail automatically. Off means senders cannot tell you read it. On by default. The workspace's choice without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own value.
- `trustedSenders` (`[]string | nil`): Senders whose pictures always load while `externalImages` is off. Replaces the whole list. The workspace's list without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own list.
- `blockedSenders` (`[]string | nil`): Senders whose mail is refused on arrival, plus-tags included. Mail already delivered stays. Replaces the whole list. The workspace's list without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own list.
- `blockedDomains` (`[]string | nil`): Domains whose mail is refused on arrival, subdomains included. Replaces the whole list. The workspace's list without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own list.
- `blockedWords` (`[]string | nil`): Words that open matching mail behind a warning. Nothing is deleted. Replaces the whole list. The workspace's list without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own list.
- `useDefaultBlockedWords` (`bool | nil`): Adds the built-in list of English profanities and slurs to `blockedWords`. Off by default. The workspace's choice without `openemail.WithAddress`, and that scope's own with it. `null` removes the scope's own value.
- `semanticSearch` (`bool | 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` run a text search, and `null` turns it back on. Not with `openemail.WithAddress`.
- `replySuggestions` (`bool | 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 `null` turns them back on. Not with `openemail.WithAddress`.
- `knowledgeLearning` (`bool | 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 `null` turns it back on. Not with `openemail.WithAddress`.
- `developerMode` (`bool | nil`): 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 `openemail.WithAddress`.
- `workspaceName` (`string`): Renames this workspace, 1 to 64 characters once trimmed. A 422 `invalid_parameter` on a personal space. Not with `openemail.WithAddress`.
- `language` (`string`): Interface language, a locale tag such as `en` or `de`, saved as given without checking it. Saved on the account.
- `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` (`bool`): 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` (`bool`): Marks mail read when you open it in the app. Saved on the account.
- `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.
- `animations` (`bool`): Motion in the app. Off makes everything appear at once. Saved on the account.
- `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.
- `desktopOnlyWhenHidden` (`bool`): Desktop notifications only while the tab is hidden. Saved on the account.
- `phoneNewMail` (`bool`): A push to your phones when a message reaches the inbox. Saved on the account.
- `phoneReplies` (`bool`): A push to your phones when someone answers your mail. Saved on the account.
- `phoneScheduledSend` (`bool`): A push to your phones when a scheduled message goes out. Saved on the account.
- `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.
- `phoneSendFailures` (`bool`): A push to your phones when a message fails to send. Saved on the account.
- `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.
- `primaryOnlyAlerts` (`bool`): With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
- `phonePreviews` (`bool`): Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
- `phoneSound` (`bool`): Plays a sound with each push. Off makes them silent. Saved on the account.
- `phoneMutedWorkspaces` (`[]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.
- `soundNewMail` (`bool`): Chimes when mail arrives while the app is open. Saved on the account.
- `soundAiDone` (`bool`): Chimes when the assistant finishes a reply. Saved on the account.
- `soundSent` (`bool`): 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 the interface language. Saved on the account.
- `translateReplies` (`bool`): Opens replies on threads you translated already translated into your language. Saved on the account.
- `showAvatarToContacts` (`bool`): Shows your profile photo to OpenEmail users on your address. Saved on the account.
- `lookupContactPhotos` (`bool`): Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
- `openemail.WithAddress` (`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`.
- `openemail.WithAPIKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An `openemail.Object`, the full saved settings for the scope you named, in the same shape as `Get` with the same `openemail.WithAddress`.

**Example**

```go
settings, err := client.Settings.Update(ctx, openemail.Body{"timezone": "Europe/London", "timeFormat": "24h", "developerMode": true})
if err != nil {
	return err
}

fmt.Println(settings.String("address"), settings.String("object"))
```

**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 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); Java [`settings().update`](https://openemail.uk/docs/java/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).