API

الإعدادات

كل عملية في هذه المجموعة: ما تقبله وما تُرجعه والأخطاء التي قد تردّ بها.

العمليات

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

settings:readيقرأ

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.

يُرجع

200Branding

The brand of the workspace.

الأخطاء

الأخطاء التي يمكن أن تُرجعها أي عملية400401403404422500دليل الأخطاء

متاح أيضًا في

SDK: branding.get()
CLI: openemail branding get
MCP: getBranding

PATCH`/branding`

Change the fonts and the sign-in background

settings:writeيغيّر البيانات

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.

متن الطلب

fontsobject

The fonts to change. A font left out keeps its value, and null sets the default.

primarystring: The 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"
secondarystring: The 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"

loginBackgroundobject

The sign-in page background, replacing the one there was, or null for the default.

يمكن أن يكون null

kindstringمطلوب: preset shows preset, color fills it with color, and image shows the image uploaded with PUT /branding/images/login-background. image is refused with 422 invalid_parameter until that image is uploaded, and once it is removed the background falls back to the preset or color kept with it, or to null.
أحد"preset""color""image"
presetstring: One of the built-in backgrounds. Required when kind is preset.
يمكن أن يكون nullأحد"dusk""mist""sand""night"
colorstring: A colour as # and six hex digits, such as #1f2937, stored lowercased. Required when kind is color.
يمكن أن يكون nullالنمط^#[0-9a-f]{6}$
logostring: Which logo the sign-in page shows: dark, your logo, or light, 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"

يُرجع

200Branding

The brand as this call left it.

الأخطاء

400: malformed_json: the body is not valid JSON.
403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_parameter naming the field, such as fonts.primary for a font that is not on the list, loginBackground.preset when kind is preset and no preset is given, loginBackground.kind when kind is image and no sign-in photo is uploaded, or loginBackground.color for a colour that is not # and six hex digits. unknown_parameter for any other field, and capability_unsupported with param: "domainAllowlist" for a key or app limited to particular addresses or domains.

الأخطاء التي يمكن أن تُرجعها أي عملية401404500دليل الأخطاء

متاح أيضًا في

SDK: branding.update()
CLI: openemail branding update
MCP: updateBranding

PUT`/branding/images/{variant}`

Upload a brand image

settings:writeيغيّر البيانات

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, or login-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

binary

يُرجع

200Branding

The brand, with the new image.

الأخطاء

403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_image when the body is not an image of a type that variant accepts, is too large or cannot be read. invalid_parameter on variant for a name that is not one of the four, and capability_unsupported with param: "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دليل الأخطاء

متاح أيضًا في

SDK: branding.uploadImage()
CLI: openemail branding upload-image
MCP: setBrandImage

DELETE`/branding/images/{variant}`

Remove a brand image

settings:writeيحذف

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, or login-background, the photo behind the sign-in page.
أحد"mark""wordmark""wordmark-dark""login-background"

يُرجع

200Branding

The brand, without that image.

الأخطاء

403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_parameter on variant for a name that is not one of the four, and capability_unsupported with param: "domainAllowlist" for a key or app limited to particular addresses or domains.

الأخطاء التي يمكن أن تُرجعها أي عملية400401404500دليل الأخطاء

متاح أيضًا في

SDK: branding.removeImage()
CLI: openemail branding remove-image
MCP: removeBrandImage

GET`/settings`

Read mailbox settings

settings:readيقرأ

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.

معلمات الاستعلام

addressstring: The address whose signature, openEmailSignature, trackOpens and trackClicks to read or change, such as [email protected], or *@example.com for 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 422 capability_unsupported.
حتى 320 من الأحرف

يُرجع

200

Settings.

الأخطاء

422: invalid_parameter on address when it is not one address or *@domain, or capability_unsupported when a narrowed key names an address it does not hold.

الأخطاء التي يمكن أن تُرجعها أي عملية400401403404500دليل الأخطاء

متاح أيضًا في

SDK: settings.get()
CLI: openemail settings get
MCP: getSettings

PATCH`/settings`

Change mailbox settings

settings:writeيغيّر البيانات

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.

معلمات الاستعلام

addressstring: The address whose signature, openEmailSignature, trackOpens and trackClicks to read or change, such as [email protected], or *@example.com for 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 422 capability_unsupported.
حتى 320 من الأحرف

متن الطلب

signaturestring: HTML 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 with address.
openEmailSignatureboolean: Adds the OpenEmail footer to mail from the address named by address while it has no signature. On by default. Only with address.
timezonestring: IANA zone name, saved as given without checking it.
languagestring: Language code such as en, saved as given without checking it.
defaultEmailAliasstring: Address the app composer preselects as From.
trackOpensboolean: Open tracking on mail from the address named by address, for a send that does not set tracking.opens. On by default. Only with address.
trackClicksboolean: Link tracking on mail from the address named by address, for a send that does not set tracking.clicks. On by default. Only with address.

يُرجع

200

The saved settings.

الأخطاء

422: Rejected: address_required (a per-address field sent without address), not_per_address (a field other than the four sent with address), signature_too_long, invalid_parameter, or capability_unsupported when a narrowed key names an address it does not hold.

الأخطاء التي يمكن أن تُرجعها أي عملية400401403404500دليل الأخطاء

متاح أيضًا في

SDK: settings.update()
CLI: openemail settings update
MCP: updateSettings

الكائنات

`Branding`object

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"

editableboolean

Whether this key may change the brand: false in a personal space, without settings:write, or for a key limited to particular addresses or domains.

imagesobject

A link to each brand image, or null when it is not set.

markstring: The square mark, or null.
يمكن أن يكون null
wordmarkstring: The logo, or null.
يمكن أن يكون null
wordmarkDarkstring: The logo for dark mode, or null. Without it the logo shows in dark mode too.
يمكن أن يكون null
loginBackgroundstring: The photo behind the sign-in page, or null.
يمكن أن يكون null

fontsobject

The two fonts of the brand, each a font id from the supported list or null for the default.

primarystring: The 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"
secondarystring: The 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"

loginBackgroundobject

What the sign-in page of the web app address shows behind the form, or null for the default. kind picks one of three: a preset, a color or the uploaded image. The value for the other kinds may be kept, so switching back restores it.

يمكن أن يكون null

kindstringمطلوب: preset shows preset, color fills it with color, and image shows the image uploaded with PUT /branding/images/login-background. image is refused with 422 invalid_parameter until that image is uploaded, and once it is removed the background falls back to the preset or color kept with it, or to null.
أحد"preset""color""image"
presetstring: One of the built-in backgrounds. Required when kind is preset.
يمكن أن يكون nullأحد"dusk""mist""sand""night"
colorstring: A colour as # and six hex digits, such as #1f2937, stored lowercased. Required when kind is color.
يمكن أن يكون nullالنمط^#[0-9a-f]{6}$
logostring: Which logo the sign-in page shows: dark, your logo, or light, 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"

الإعدادات

العمليات

يُرجع

الأخطاء

متاح أيضًا في

متن الطلب

يُرجع

الأخطاء

متاح أيضًا في

معلمات المسار

متن الطلب

يُرجع

الأخطاء

متاح أيضًا في

معلمات المسار

يُرجع

الأخطاء

متاح أيضًا في

معلمات الاستعلام

يُرجع

الأخطاء

متاح أيضًا في

معلمات الاستعلام

متن الطلب

يُرجع

الأخطاء

متاح أيضًا في

الكائنات

Brandingobject

صندوق بريدك،بشروطك أنت.

`Branding`object

صندوق بريدك،
بشروطك أنت.