openemail.settings

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

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 options.address it changes the workspace's settings. signature, openEmailSignature, trackOpens and trackClicks 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 options.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.