---
title: "$client->branding"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/php/reference/branding"
area: "PHP"
category: "Reference"
---

# $client->branding

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

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

```php
get(?string $apiKey = null): array
```

Returns 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 null there and `editable` is false.

Scopes: `settings:read`.

**Parameters**

- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

An array with `object` set to `branding`, `editable`, `images`, `fonts` and `loginBackground`. `images` holds `mark`, `wordmark`, `wordmarkDark` and `loginBackground`, each a URL or null. `fonts` holds `primary` and `secondary`, each a font id from `OpenEmail\Constants\BrandFontIds` or null for the default. `loginBackground` is an array with `kind`, `preset`, `color` and `logo`, or null for the default, where `logo` is `dark`, `light` or null to match the background.

**Example**

```php
$branding = $client->branding->get();

echo $branding['images']['wordmark'] ?? 'no logo', PHP_EOL;
echo $branding['fonts']['primary'] ?? 'the default font', PHP_EOL;
echo $branding['editable'] ? 'This key may change it' : 'Read only for this key', PHP_EOL;
```

**Notes**

- `editable` says whether this key may change the brand. It is false in a personal space, for a key without `settings:write`, and for a key limited to particular addresses or domains.
- A `loginBackground` of kind `image` never reads back without its photo: once the photo is removed it reads as the preset or colour kept with it, or as null.

Also available in: API [`GET /branding`](https://openemail.uk/docs/api/reference/settings#get-branding); TypeScript [`branding.get()`](https://openemail.uk/docs/sdk/reference/branding#get); Python [`branding.get()`](https://openemail.uk/docs/python/reference/branding#get); Ruby [`branding.get`](https://openemail.uk/docs/ruby/reference/branding#get); CLI [`openemail branding get`](https://openemail.uk/docs/cli/reference/branding#branding-get).

### `branding->update`

Change the fonts and the sign-in background of the brand

```php
update(array $body, ?string $apiKey = null): array
```

Changes 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 null sets the default.

With `'kind' => 'image'` the sign-in page shows the photo uploaded with `uploadImage('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.

Scopes: `settings:write`.

**Parameters**

- `fonts` (`array`): The fonts to change. Leave it out to keep both.
- `fonts.primary` (`?string`): The primary font: one of the ids in `OpenEmail\Constants\BrandFontIds`, such as `inter` or `georgia`, or null for the default. Left out, it keeps its value.
- `fonts.secondary` (`?string`): The secondary font, an id from `OpenEmail\Constants\BrandFontIds` or null for the default. Left out, it keeps its value.
- `loginBackground` (`?array`): The sign-in page background, replacing the one there was, or null for the default. Leave it out to keep it.
- `loginBackground.kind` (`string`): `preset`, `color` or `image`. Required once `loginBackground` is given.
- `loginBackground.preset` (`?string`): `dusk`, `mist`, `sand` or `night`. Required when `kind` is `preset`, and kept for later otherwise.
- `loginBackground.color` (`?string`): A colour as `#` and six hex digits, such as `#1f2937`, stored lowercased. Required when `kind` is `color`, and kept for later otherwise.
- `loginBackground.logo` (`?string`): `dark` shows your logo and `light` your logo for dark mode. Null, the default, picks the one that stands out against the background.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The same array as `branding->get`, as the call left it.

**Example**

```php
use OpenEmail\Constants\BrandFontIds;
use OpenEmail\Constants\LoginBackgroundKinds;

$branding = $client->branding->update([
    'fonts' => ['primary' => BrandFontIds::INTER, 'secondary' => BrandFontIds::GEORGIA],
    'loginBackground' => ['kind' => LoginBackgroundKinds::COLOR, 'color' => '#1f2937'],
]);

print_r($branding['fonts']);
print_r($branding['loginBackground']);
```

**Notes**

- A font that is not on the list, a `preset` background with no preset, an `image` background while no sign-in photo is uploaded, or a colour that is not `#` and six hex digits is refused with 422 `invalid_parameter`, and `param` names the field, such as `fonts.primary` or `loginBackground.kind`. Any other field is 422 `unknown_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_unsupported` on `domainAllowlist`. Such a key can still read it with `get`.
- Retried automatically on network failure and retryable statuses, since sending the same change twice leaves the same brand.

Also available in: API [`PATCH /branding`](https://openemail.uk/docs/api/reference/settings#patch-branding); TypeScript [`branding.update()`](https://openemail.uk/docs/sdk/reference/branding#update); Python [`branding.update()`](https://openemail.uk/docs/python/reference/branding#update); Ruby [`branding.update`](https://openemail.uk/docs/ruby/reference/branding#update); CLI [`openemail branding update`](https://openemail.uk/docs/cli/reference/branding#branding-update).

### `branding->uploadImage`

Upload one of the brand images

```php
uploadImage(
    string $variant,
    mixed $data,
    ?string $contentType = null,
    ?string $apiKey = null,
): array
```

Sends 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 type is read from `contentType:`, or when that is left out from the media type of a PSR-7 uploaded file or the extension of the file name of an `SplFileInfo`, an uploaded file or a stream opened with `fopen`, and without either the server refuses the bytes with 422 `invalid_image`.

Scopes: `settings:write`.

**Parameters**

- `variant` (`string`, required): `mark`, `wordmark`, `wordmark-dark` or `login-background`.
- `data` (`string|resource|SplFileInfo|StreamInterface`, required): The image: a string of bytes, a stream resource from `fopen`, an `SplFileInfo`, or a PSR-7 stream or uploaded file.
- `contentType` (`string`): `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Required unless `data` carries its type: a PSR-7 uploaded file with a media type, or a file or stream whose name ends in `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp` or `.gif`.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The same array as `branding->get`, with the new image in `images`.

**Example**

```php
use OpenEmail\Constants\BrandImageVariants;

$branding = $client->branding->uploadImage(BrandImageVariants::WORDMARK, fopen('logo.png', 'rb'));

echo $branding['images']['wordmark'], PHP_EOL;

$client->branding->uploadImage(
    BrandImageVariants::WORDMARK_DARK,
    file_get_contents('logo-dark.png'),
    contentType: 'image/png',
);
```

**Notes**

- 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 422 `invalid_parameter` on `variant`.
- 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_unsupported` on `domainAllowlist`. Such a key can still read it with `get`.
- A busy image service answers 503 `image_busy` and a failed save 502 `image_not_stored`, which the SDK retries like any other retryable status.

Also available in: API [`PUT /branding/images/{variant}`](https://openemail.uk/docs/api/reference/settings#put-branding-images-variant); TypeScript [`branding.uploadImage()`](https://openemail.uk/docs/sdk/reference/branding#uploadImage); Python [`branding.upload_image()`](https://openemail.uk/docs/python/reference/branding#uploadImage); Ruby [`branding.upload_image`](https://openemail.uk/docs/ruby/reference/branding#uploadImage); CLI [`openemail branding upload-image`](https://openemail.uk/docs/cli/reference/branding#branding-upload-image).

### `branding->removeImage`

Remove one of the brand images

```php
removeImage(string $variant, ?string $apiKey = null): array
```

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.

Scopes: `settings:write`.

**Parameters**

- `variant` (`string`, required): `mark`, `wordmark`, `wordmark-dark` or `login-background`.
- `apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

The same array as `branding->get`, without that image.

**Example**

```php
use OpenEmail\Constants\BrandImageVariants;

$branding = $client->branding->removeImage(BrandImageVariants::LOGIN_BACKGROUND);

echo $branding['loginBackground']['kind'] ?? 'the default background', PHP_EOL;
```

**Notes**

- 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_unsupported` on `domainAllowlist`. Such a key can still read it with `get`.
- Retried automatically on network failure and retryable statuses, since a second attempt after one that went through finds nothing to remove.

Also available in: API [`DELETE /branding/images/{variant}`](https://openemail.uk/docs/api/reference/settings#delete-branding-images-variant); TypeScript [`branding.removeImage()`](https://openemail.uk/docs/sdk/reference/branding#removeImage); Python [`branding.remove_image()`](https://openemail.uk/docs/python/reference/branding#removeImage); Ruby [`branding.remove_image`](https://openemail.uk/docs/ruby/reference/branding#removeImage); CLI [`openemail branding remove-image`](https://openemail.uk/docs/cli/reference/branding#branding-remove-image).