設定
このグループのすべてのオペレーションの、受け付ける内容、返す内容、返しうるエラー。
オペレーション
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.
戻り値
The brand of the workspace.
エラー
どのオペレーションも返しうるエラー400401403404422500エラー一覧
ほかの提供先
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.
リクエストボディ
fontsobjectThe fonts to change. A font left out keeps its value, and null sets the default.
primarystringThe primary font, or null for the default.
null も可次のいずれか"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.
null も可次のいずれか"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.
null も可kindstring必須presetshowspreset,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.次のいずれか"preset""color""image"presetstringOne of the built-in backgrounds. Required when
kindispreset.null も可次のいずれか"dusk""mist""sand""night"colorstringA colour as
#and six hex digits, such as#1f2937, stored lowercased. Required whenkindiscolor.null も可パターン^#[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.null も可次のいずれか"dark""light"
戻り値
The brand as this call left it.
エラー
- 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.
どのオペレーションも返しうるエラー401404500エラー一覧
ほかの提供先
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.
パスパラメーター
variantstring必須Which image:
mark, the square icon,wordmark, the logo,wordmark-dark, the logo for dark mode, orlogin-background, the photo behind the sign-in page.次のいずれか"mark""wordmark""wordmark-dark""login-background"
リクエストボディ
コンテンツタイプimage/webp, image/png, image/jpeg, image/gif, image/svg+xml
戻り値
The brand, with the new image.
エラー
- 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.
どのオペレーションも返しうるエラー400401404500エラー一覧
ほかの提供先
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.
パスパラメーター
variantstring必須Which image:
mark, the square icon,wordmark, the logo,wordmark-dark, the logo for dark mode, orlogin-background, the photo behind the sign-in page.次のいずれか"mark""wordmark""wordmark-dark""login-background"
戻り値
The brand, without that image.
エラー
- 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.
どのオペレーションも返しうるエラー400401404500エラー一覧
ほかの提供先
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.
クエリパラメーター
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.320文字まで
戻り値
Settings.
エラー
- 422
invalid_parameteronaddresswhen it is not one address or*@domain, orcapability_unsupportedwhen a narrowed key names an address it does not hold.
どのオペレーションも返しうるエラー400401403404500エラー一覧
ほかの提供先
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.
クエリパラメーター
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.320文字まで
リクエストボディ
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.
戻り値
The saved settings.
エラー
- 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.
どのオペレーションも返しうるエラー400401403404500エラー一覧
ほかの提供先
オブジェクト
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- 次のいずれか
"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.
null も可wordmarkstringThe logo, or null.
null も可wordmarkDarkstringThe logo for dark mode, or null. Without it the logo shows in dark mode too.
null も可loginBackgroundstringThe photo behind the sign-in page, or null.
null も可
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.
null も可次のいずれか"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.
null も可次のいずれか"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.null も可kindstring必須presetshowspreset,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.次のいずれか"preset""color""image"presetstringOne of the built-in backgrounds. Required when
kindispreset.null も可次のいずれか"dusk""mist""sand""night"colorstringA colour as
#and six hex digits, such as#1f2937, stored lowercased. Required whenkindiscolor.null も可パターン^#[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.null も可次のいずれか"dark""light"