openemail.branding
هر متد در این فضای نام: امضا، پارامترها، آنچه برمیگرداند و یک نمونه.
متدها
The brand of the workspace: its mark, its logo and its logo for dark mode, its primary and secondary fonts, and the background of the sign-in page of its web app address. Read it, change the fonts and the background, and upload or remove each image.
branding.get()
Read the brand of the workspace
def get(*, api_key: str | None = None, timeout: float | None = None) -> BrandingResourceReturns the brand of the workspace, as its Customisations page shows it: a link to each brand image in images, the primary and secondary fonts in fonts, and the background of the sign-in page in loginBackground.
The mark shows in the workspace switcher. The logo shows at the top of the sidebar, and it is what brands the web app address and, on a paid plan, the emails OpenEmail sends for the workspace, at their top and foot. Without a logo, 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, either way.
A personal space carries no brand, so every image and font reads as None there and editable is False.
پارامترها
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
BrandingResource, a dict with 'object': 'branding', editable, images, fonts and loginBackground. images holds mark, wordmark, wordmarkDark and loginBackground, each a URL or None. fonts holds primary and secondary, each a BrandFontId or None for the default. loginBackground is a dict with kind, preset, color and logo, or None for the default, where logo is 'dark', 'light' or None to match the background.
نمونه
from openemail import openemail branding = openemail.branding.get() logo = branding['images']['wordmark'] or 'no logo'font = branding['fonts']['primary'] or 'the default font' print(logo, font, branding['editable'])نکتهها
editablesays whether this key may change the brand. It isFalsein a personal space, for a key withoutsettings:write, and for a key limited to particular addresses or domains.A
loginBackgroundof kindimagenever reads back without its photo: once the photo is removed it reads as the preset or colour kept with it, or asNone.
همچنین در دسترس در
- API
GET /branding- TypeScript
branding.get()- Ruby
branding.get- CLI
openemail branding get
branding.update()
Change the fonts and the sign-in background of the brand
def update( body: BrandingUpdate, *, api_key: str | None = None, timeout: float | None = None,) -> BrandingResourceChanges the fonts, the sign-in page background or both, and returns the brand in the same shape as get. A field left out keeps its value, and so does a font left out of fonts. loginBackground replaces the background there was, and None sets the default.
With 'kind': 'image' the sign-in page shows the photo uploaded with upload_image('login-background', ...), so upload that first: without it the call is refused. Uploading one switches the page to it on its own, so most callers never send 'kind': 'image' themselves.
پارامترها
body['fonts']BrandingFontsUpdateThe fonts to change. Leave it out to keep both.
body['fonts']['primary']BrandFontId | NoneThe primary font: one of the ids in
BRAND_FONT_IDS, such as'inter'or'georgia', orNonefor the default. Left out, it keeps its value.body['fonts']['secondary']BrandFontId | NoneThe secondary font, an id from
BRAND_FONT_IDSorNonefor the default. Left out, it keeps its value.body['loginBackground']LoginBackgroundInput | NoneThe sign-in page background, replacing the one there was, or
Nonefor the default. Leave it out to keep it.body['loginBackground']['kind']LoginBackgroundKindالزامی'preset','color'or'image'. Required onceloginBackgroundis given.body['loginBackground']['preset']LoginBackgroundPreset | None'dusk','mist','sand'or'night'. Required whenkindis'preset', and kept for later otherwise.body['loginBackground']['color']str | NoneA colour as
#and six hex digits, such as'#1f2937', stored lowercased. Required whenkindis'color', and kept for later otherwise.body['loginBackground']['logo']LoginLogo | None'dark'shows your logo and'light'your logo for dark mode.None, the default, picks the one that stands out against the background.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
BrandingResource as the call left it.
نمونه
from openemail import openemail branding = openemail.branding.update( { 'fonts': {'primary': 'inter', 'secondary': 'georgia'}, 'loginBackground': {'kind': 'color', 'color': '#1f2937'}, }) print(branding['fonts'], branding['loginBackground'])نکتهها
A font that is not on the list, a
presetbackground with no preset, animagebackground while no sign-in photo is uploaded, or a colour that is not#and six hex digits is refused with 422invalid_parameter, and the error'sparamnames the field, such asfonts.primaryorloginBackground.kind. Any other field is 422unknown_parameter.A personal space carries no brand, so the call is refused there with 409
branding_unavailable.The brand applies to the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist. Such a key can still read it withget.Retried automatically on network failure and retryable statuses, since sending the same change twice leaves the same brand.
همچنین در دسترس در
- API
PATCH /branding- TypeScript
branding.update()- Ruby
branding.update- CLI
openemail branding update
branding.upload_image()
Upload one of the brand images
def upload_image( variant: BrandImageVariant, data: RawBody, *, content_type: BrandImageType | None = None, api_key: str | None = None, timeout: float | None = None,) -> BrandingResourceSends the image bytes as the request body, replacing the image there was, and returns the brand. variant names the 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 of the web app address.
Up to 5 MB goes in, and it is fitted and stored as WebP: the mark into 512 by 512 pixels, the two logos into 1024 by 256, and the sign-in photo into 2560 by 1600. The mark and the logos take SVG, PNG, JPEG or WebP, and the sign-in photo PNG, JPEG, WebP or GIF. An SVG is turned into a picture, and an animated image keeps its first frame.
Uploading the sign-in photo also switches the sign-in page to it. The server reads the type from content_type= alone. Bytes carry no type of their own, so without it they are sent as application/octet-stream and refused with 422 invalid_image: pass it on every call.
پارامترها
variantBrandImageVariantالزامی'mark','wordmark','wordmark-dark'or'login-background'.dataRawBodyالزامیThe image as
bytes, abytearrayor amemoryview, such asPath('logo.png').read_bytes().content_typeBrandImageType'image/svg+xml','image/png','image/jpeg','image/webp'or'image/gif'. Optional in the signature, but the server refuses an upload without it.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
BrandingResource with the new image in images.
نمونه
from pathlib import Path from openemail import openemail branding = openemail.branding.upload_image( 'wordmark', Path('logo.png').read_bytes(), content_type='image/png') print(branding['images']['wordmark'])نکتهها
An image of a type that variant does not take, one over 5 MB, or one that cannot be read is refused with 422
invalid_image, and a variant that is not one of the four with 422invalid_parameteronvariant.A personal space carries no brand, so the call is refused there with 409
branding_unavailable.The brand applies to the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist. Such a key can still read it withget.A busy image service answers 503
image_busyand a failed save 502image_not_stored, which the SDK retries like any other retryable status.
همچنین در دسترس در
branding.remove_image()
Remove one of the brand images
def remove_image( variant: BrandImageVariant, *, api_key: str | None = None, timeout: float | None = None,) -> BrandingResourceRemoves 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.
پارامترها
variantBrandImageVariantالزامی'mark','wordmark','wordmark-dark'or'login-background'.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
BrandingResource without that image.
نمونه
from openemail import openemail branding = openemail.branding.remove_image('login-background') print(branding['images']['loginBackground'], branding['loginBackground'])نکتهها
A personal space carries no brand, so the call is refused there with 409
branding_unavailable.The brand applies to the whole workspace, so a key or app limited to particular addresses or domains is refused with 422
capability_unsupportedondomainAllowlist. Such a key can still read it withget.Retried automatically on network failure and retryable statuses, since a second attempt after one that went through finds nothing to remove.