---
title: "openemail settings"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://openemail.uk/docs/cli/reference/settings"
area: "CLI"
category: "Reference"
---

# openemail settings

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `openemail settings get`

Read the workspace settings

```bash
openemail settings get [flags]
```

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` types `address`, `signature`, `openEmailSignature`, `timezone`, `language`, `defaultEmailAlias`, `trackOpens` and `trackClicks`, and the rest of the stored settings arrive as extra keys, such as `timeFormat`, `weekStart`, `undoSendEnabled`, `blockedSenders` and `blockedDomains`.

`signature`, `openEmailSignature`, `trackOpens` and `trackClicks` belong to each address. There is no value for them across the workspace or the account. Pass `--address` to read them the way a send from that address resolves them: 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. A plus address with no settings of its own reads its base address's. Without `--address` the four read as the built-in defaults: no signature, the OpenEmail footer on, and open and link tracking on. `address` on the result is the address the four were resolved for, lowercased, or null.

Every other field is the workspace's and reads the same with or without `--address`: the workspace owner's account settings with the workspace's own overrides applied on top, whoever created the key. The privacy fields (`externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords` and `useDefaultBlockedWords`) no longer live on an account at all: a workspace holds them, a domain can answer differently, and one address can answer differently again in the app.

`signature` is the HTML added to mail sent from the address, and `openEmailSignature` adds the OpenEmail footer only while `signature` is empty. `trackOpens` and `trackClicks` apply to a send from the address that does not set `tracking` itself.

- Scopes: `settings:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Flags**

- `--address <value>`: An address, or `*@domain` for the catch-all of a domain, to resolve `signature`, `openEmailSignature`, `trackOpens` and `trackClicks` for. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all only on a domain it holds whole, or the call is a 422 `capability_unsupported`.

**Examples**

```bash
openemail settings get
```

With optional flags

```bash
openemail settings get --address sales@example.com
```

Print the raw JSON

```bash
openemail settings get --json
```

Also available in: API [`GET /settings`](https://openemail.uk/docs/api/reference/settings#get-settings); SDK [`settings.get()`](https://openemail.uk/docs/sdk/reference/settings#get).

### `openemail settings update`

Change workspace settings

```bash
openemail settings update [flags]
```

A partial update: fields you send are validated and saved, fields you leave out keep their values, and the response is the full settings object read back after the write, in the same shape `get` returns.

Without `--address` it changes the workspace's settings. `signature`, `--open-email-signature`, `--track-opens` and `--track-clicks` are refused there with a 422 `address_required` naming the field, because they are set on each address and there is no value for them across the workspace or the account, and nothing is written. The privacy fields (`externalImages`, `trustedSenders`, `blockedSenders`, `blockedDomains`, `blockedWords`, `useDefaultBlockedWords`) are written to the workspace's own overrides, and the rest to the workspace owner's account settings. The response applies the workspace's overrides, so when the workspace overrides a field you changed, the response keeps showing the override and your value only takes effect once that override is gone. Keys the settings schema does not know are dropped silently rather than refused, and a known key with the wrong type is a 422 `invalid_parameter` naming it.

With `--address` the patch may carry those four fields only, and any other field is a 422 `not_per_address` naming it. The address has to be one in this workspace, or `*@domain` for a verified domain here with its catch-all on, or the call is a 422 `invalid_parameter` on `address`. The values are saved on that address alone and the response is `get({ address })` for it. 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`.
- Needs a sign-in.
- Aliases: `edit`.

**Flags**

- `--signature <value>`: HTML signature of the address named by `--address`, at most 150,000 characters, sanitised on write. An empty string removes it. Only with `--address`.
- `--open-email-signature`: Adds the OpenEmail footer to mail from the address while its `signature` is empty. On by default. Only with `--address`.
- `--timezone <value>`: IANA zone name, saved as given without checking it.
- `--language <value>`: Language code such as `en`, saved as given without checking it.
- `--default-email-alias <value>`: Address the app composer preselects as From.
- `--track-opens`: Open tracking on mail from the address, for sends that do not set `tracking.opens`. Off by default. Only with `--address`.
- `--track-clicks`: Link tracking on mail from the address, for sends that do not set `tracking.clicks`. Off by default. Only with `--address`.
- `--address <value>`: The address, or `*@domain` for the catch-all of a domain, whose `signature`, `--open-email-signature`, `--track-opens` and `--track-clicks` the patch sets. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all only on a domain it holds whole, or the call is a 422 `capability_unsupported`.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

With optional flags

```bash
openemail settings update --signature '<p>Ada Lovelace<br>Analytical Engines Ltd</p>' --timezone Europe/London --no-track-clicks
```

Print the raw JSON

```bash
openemail settings update --signature '<p>Ada Lovelace<br>Analytical Engines Ltd</p>' --timezone Europe/London --no-track-clicks --json
```

Also available in: API [`PATCH /settings`](https://openemail.uk/docs/api/reference/settings#patch-settings); SDK [`settings.update()`](https://openemail.uk/docs/sdk/reference/settings#update).