Einstellungen
Jede Operation in dieser Gruppe: was sie annimmt, was sie zurückgibt und mit welchen Fehlern sie antworten kann.
Operationen
Mailbox preferences, the signature and tracking of each address, and the brand of the workspace: its images, fonts and sign-in background.
GET/branding
Retrieve the brand
The brand of the workspace, as its Customisations page shows it: a link to each brand image, the primary and secondary fonts, and the background of the sign-in page.
The mark shows in the app's workspace switcher. The logo shows at the top of the sidebar, and it is what brands the web app address, GET /app-host, and, on a paid plan, the emails OpenEmail sends for the workspace, which carry it at the top and the foot. Without a logo, the web app address and the emails look like OpenEmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, either way.
A personal space carries no brand, so its images and fonts read as null and editable is false.
Requires the settings:read scope.
Rückgabe
The brand of the workspace.
Fehler
Die Fehler, die jede Operation zurückgeben kann400401403404422500Fehlerkatalog
Auch verfügbar über
PATCH/branding
Change the fonts and the sign-in background
Changes the fonts, the sign-in page background or both, and returns the brand in the same shape as GET /branding. A field left out keeps its value, and so does a font left out of fonts. loginBackground replaces the background there was, and null sets the default.
With kind: "image" the sign-in page shows the photo uploaded with PUT /branding/images/login-background, so upload that first: without it the call is refused. Uploading one switches the page to it on its own.
The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.
Requires the settings:write scope.
Request-Body
fontsobjectThe fonts to change. A font left out keeps its value, and null sets the default.
primarystringThe primary font, or null for the default.
Kann null seinEiner von"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"secondarystringThe secondary font, or null for the default.
Kann null seinEiner von"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"
loginBackgroundobjectThe sign-in page background, replacing the one there was, or null for the default.
Kann null seinkindstringErforderlichpresetshowspreset,colorfills it withcolor, andimageshows the image uploaded withPUT /branding/images/login-background.imageis refused with 422invalid_parameteruntil that image is uploaded, and once it is removed the background falls back to thepresetorcolorkept with it, or to null.Einer von"preset""color""image"presetstringOne of the built-in backgrounds. Required when
kindispreset.Kann null seinEiner von"dusk""mist""sand""night"colorstringA colour as
#and six hex digits, such as#1f2937, stored lowercased. Required whenkindiscolor.Kann null seinMuster^#[0-9a-f]{6}$logostringWhich logo the sign-in page shows:
dark, your logo, orlight, your logo for dark mode (OpenEmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.Kann null seinEiner von"dark""light"
Rückgabe
The brand as this call left it.
Fehler
- 400
malformed_json: the body is not valid JSON.- 403
insufficient_scope: the key lackssettings:write.- 409
branding_unavailable: the workspace is a personal space, which carries no brand.- 422
invalid_parameternaming the field, such asfonts.primaryfor a font that is not on the list,loginBackground.presetwhenkindispresetand no preset is given,loginBackground.kindwhenkindisimageand no sign-in photo is uploaded, orloginBackground.colorfor a colour that is not#and six hex digits.unknown_parameterfor any other field, andcapability_unsupportedwithparam: "domainAllowlist"for a key or app limited to particular addresses or domains.
Die Fehler, die jede Operation zurückgeben kann401404500Fehlerkatalog
Auch verfügbar über
PUT/branding/images/{variant}
Upload a brand image
Uploads one brand image, replacing the one there was, and returns the brand. Send the image itself as the body, not JSON, with its type in Content-Type. Up to 5 MB goes in. variant names the image:
- mark: the square mark. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 512 by 512 pixels and stored as WebP.
- wordmark: the logo. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 1024 by 256 pixels and stored as WebP.
- wordmark-dark: the logo for dark mode, shown in place of the logo when the app is dark. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 1024 by 256 pixels and stored as WebP.
- login-background: the photo behind the sign-in page of the web app address. image/png, image/jpeg, image/webp, image/gif, fitted into 2560 by 1600 pixels and stored as WebP. Uploading it also switches the sign-in page to it.
An SVG is turned into a picture, and an animated image keeps its first frame.
The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.
Requires the settings:write scope.
Pfadparameter
variantstringErforderlichWhich image:
mark, the square icon,wordmark, the logo,wordmark-dark, the logo for dark mode, orlogin-background, the photo behind the sign-in page.Einer von"mark""wordmark""wordmark-dark""login-background"
Request-Body
Inhaltstypimage/webp, image/png, image/jpeg, image/gif, image/svg+xml
Rückgabe
The brand, with the new image.
Fehler
- 403
insufficient_scope: the key lackssettings:write.- 409
branding_unavailable: the workspace is a personal space, which carries no brand.- 422
invalid_imagewhen the body is not an image of a type that variant accepts, is too large or cannot be read.invalid_parameteronvariantfor a name that is not one of the four, andcapability_unsupportedwithparam: "domainAllowlist"for a key or app limited to particular addresses or domains.- 502
image_not_stored: the image was read but could not be stored. Try again.- 503
image_busy: the image service is saturated. Try again shortly.
Die Fehler, die jede Operation zurückgeben kann400401404500Fehlerkatalog
Auch verfügbar über
DELETE/branding/images/{variant}
Remove a brand image
Removes one brand image, deletes the stored file and returns the brand, so the default shows in its place. Removing the sign-in photo while the sign-in page shows it switches the page back to the preset or colour chosen before it, or to the default. Removing an image that is not set changes nothing, so a repeated call is safe.
The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.
Requires the settings:write scope.
Pfadparameter
variantstringErforderlichWhich image:
mark, the square icon,wordmark, the logo,wordmark-dark, the logo for dark mode, orlogin-background, the photo behind the sign-in page.Einer von"mark""wordmark""wordmark-dark""login-background"
Rückgabe
The brand, without that image.
Fehler
- 403
insufficient_scope: the key lackssettings:write.- 409
branding_unavailable: the workspace is a personal space, which carries no brand.- 422
invalid_parameteronvariantfor a name that is not one of the four, andcapability_unsupportedwithparam: "domainAllowlist"for a key or app limited to particular addresses or domains.
Die Fehler, die jede Operation zurückgeben kann400401404500Fehlerkatalog
Auch verfügbar über
GET/settings
Read mailbox settings
Every field with defaults filled in, so reading a setting never requires knowing which release introduced it.
signature, openEmailSignature, trackOpens and trackClicks belong to each address. There is no workspace-wide or account value for them. 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. Every other field is the workspace's and reads the same either way. address in the response is the address the four were resolved for, lowercased, or null.
Requires the settings:read scope.
Query-Parameter
addressstringThe address whose
signature,openEmailSignature,trackOpensandtrackClicksto read or change, such as[email protected], or*@example.comfor the catch-all of that domain. On a read any address resolves the way a send from it would. On a write it has to be an address in this workspace, or a catch-all on a verified domain here with its catch-all on. 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 it is 422capability_unsupported.Bis zu 320 Zeichen
Rückgabe
Settings.
Fehler
- 422
invalid_parameteronaddresswhen it is not one address or*@domain, orcapability_unsupportedwhen a narrowed key names an address it does not hold.
Die Fehler, die jede Operation zurückgeben kann400401403404500Fehlerkatalog
Auch verfügbar über
PATCH/settings
Change mailbox settings
A partial update: a field you omit keeps its value.
Without address, this changes the workspace's settings. signature, openEmailSignature, trackOpens and trackClicks are refused there with 422 address_required naming the field, because they are set on each address, and nothing is written. The privacy fields (externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords, useDefaultBlockedWords) are saved on the workspace and the rest on the workspace owner's account.
With address, the body may carry those four fields only, and any other field is 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 it is 422 invalid_parameter on address. The values are saved on that address alone and the response is what GET /settings?address= returns 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.
Returns the SAVED state, so the signature you get back is the sanitised one that will actually be sent rather than what you asked for.
Requires the settings:write scope.
Query-Parameter
addressstringThe address whose
signature,openEmailSignature,trackOpensandtrackClicksto read or change, such as[email protected], or*@example.comfor the catch-all of that domain. On a read any address resolves the way a send from it would. On a write it has to be an address in this workspace, or a catch-all on a verified domain here with its catch-all on. 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 it is 422capability_unsupported.Bis zu 320 Zeichen
Request-Body
signaturestringHTML signature of the address named by
address, at most 150,000 characters before and after sanitising. Sanitised on write. An empty string removes it. Only withaddress.openEmailSignaturebooleanAdds the OpenEmail footer to mail from the address named by
addresswhile it has no signature. On by default. Only withaddress.timezonestringIANA zone name, saved as given without checking it.
languagestringLanguage code such as
en, saved as given without checking it.defaultEmailAliasstringAddress the app composer preselects as From.
trackOpensbooleanOpen tracking on mail from the address named by
address, for a send that does not settracking.opens. On by default. Only withaddress.trackClicksbooleanLink tracking on mail from the address named by
address, for a send that does not settracking.clicks. On by default. Only withaddress.
Rückgabe
The saved settings.
Fehler
- 422
Rejected:
address_required(a per-address field sent withoutaddress),not_per_address(a field other than the four sent withaddress),signature_too_long,invalid_parameter, orcapability_unsupportedwhen a narrowed key names an address it does not hold.
Die Fehler, die jede Operation zurückgeben kann400401403404500Fehlerkatalog
Auch verfügbar über
Objekte
Brandingobject
The brand of the workspace: its images, its fonts and the background of its sign-in page. The logo is what brands the web app address, GET /app-host, and, on a paid plan, the emails OpenEmail sends for the workspace; without one both look like OpenEmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, whether or not a logo is set. A personal space carries no brand, so every image and font is null there.
objectstring- Einer von
"branding" editablebooleanWhether this key may change the brand: false in a personal space, without
settings:write, or for a key limited to particular addresses or domains.imagesobjectA link to each brand image, or null when it is not set.
markstringThe square mark, or null.
Kann null seinwordmarkstringThe logo, or null.
Kann null seinwordmarkDarkstringThe logo for dark mode, or null. Without it the logo shows in dark mode too.
Kann null seinloginBackgroundstringThe photo behind the sign-in page, or null.
Kann null sein
fontsobjectThe two fonts of the brand, each a font id from the supported list or null for the default.
primarystringThe primary font, or null for the default.
Kann null seinEiner von"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"secondarystringThe secondary font, or null for the default.
Kann null seinEiner von"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"
loginBackgroundobjectWhat the sign-in page of the web app address shows behind the form, or null for the default.
kindpicks one of three: apreset, acoloror the uploadedimage. The value for the other kinds may be kept, so switching back restores it.Kann null seinkindstringErforderlichpresetshowspreset,colorfills it withcolor, andimageshows the image uploaded withPUT /branding/images/login-background.imageis refused with 422invalid_parameteruntil that image is uploaded, and once it is removed the background falls back to thepresetorcolorkept with it, or to null.Einer von"preset""color""image"presetstringOne of the built-in backgrounds. Required when
kindispreset.Kann null seinEiner von"dusk""mist""sand""night"colorstringA colour as
#and six hex digits, such as#1f2937, stored lowercased. Required whenkindiscolor.Kann null seinMuster^#[0-9a-f]{6}$logostringWhich logo the sign-in page shows:
dark, your logo, orlight, your logo for dark mode (OpenEmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.Kann null seinEiner von"dark""light"