Email Branding

Overview

The Email Branding API allows you to create, update, retrieve, and archive email branding configurations. Email branding controls the visual appearance of emails sent through GOV.UK Notify, including logos, colours, and text. Base URL: /email-branding

Email Branding Object

Properties

Property	Type	Description
`id`	UUID	Unique identifier for the email branding
`name`	string	Name of the email branding (must be unique)
`colour`	string	Hex colour code (e.g., `#1d70b8`), nullable
`logo`	string	URL or path to logo image (max 255 chars), nullable
`text`	string	Text to display instead of logo (max 255 chars), nullable
`alt_text`	string	Alternative text for logo (max 255 chars), nullable
`brand_type`	string	Type of branding: `org`, `both`, or `org_banner`
`created_at`	datetime	Timestamp when branding was created
`created_by`	UUID	ID of user who created the branding, nullable
`updated_at`	datetime	Timestamp of last update, nullable
`updated_by`	UUID	ID of user who last updated, nullable
`active`	boolean	Whether the branding is active (archived if false)

Constraint: Exactly one of text or alt_text must be provided (not both, not neither).

Brand Types

org - Organization branding only
both - GOV.UK and organization branding
org_banner - Organization banner style

Endpoints

List Email Branding

Retrieve all available email branding options.

GET /email-branding

Response

{
  "email_branding": [
    {
      "id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
      "name": "Cabinet Office",
      "colour": "#005ea5",
      "logo": "cabinet-office-logo.png",
      "text": null,
      "alt_text": "Cabinet Office",
      "brand_type": "org",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "updated_at": "2024-02-20T14:45:00.000000Z"
    }
  ]
}

Get Email Branding by ID

Retrieve a specific email branding configuration.

GET /email-branding/{email_branding_id}

Path Parameters

Parameter	Type	Description
`email_branding_id`	UUID	The ID of the email branding

Response

{
  "email_branding": {
    "id": "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c",
    "name": "Cabinet Office",
    "colour": "#005ea5",
    "logo": "cabinet-office-logo.png",
    "text": null,
    "alt_text": "Cabinet Office",
    "brand_type": "org",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "updated_at": null
  }
}

Create Email Branding

Create a new email branding configuration.

POST /email-branding

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique name for the branding
`colour`	string	No	Hex colour code (e.g., `#1d70b8`)
`logo`	string	No	Logo file path or URL
`text`	string	No*	Text to display (mutually exclusive with `alt_text`)
`alt_text`	string	No*	Alternative text for logo (mutually exclusive with `text`)
`brand_type`	string	Yes	One of: `org`, `both`, `org_banner`
`created_by`	UUID	No	ID of user creating the branding

*Either text OR alt_text must be provided (exactly one, not both).

Example Request

{
  "name": "Department for Education",
  "colour": "#003a69",
  "logo": "dfe-logo.png",
  "alt_text": "Department for Education",
  "brand_type": "org",
  "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Response

Status: 201 Created

{
  "data": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Department for Education",
    "colour": "#003a69",
    "logo": "dfe-logo.png",
    "text": null,
    "alt_text": "Department for Education",
    "brand_type": "org",
    "created_at": "2024-03-03T09:15:00.000000Z",
    "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "updated_at": null
  }
}

Error Responses

Status: 400 Bad Request

{
  "result": "error",
  "message": {
    "name": ["An email branding with that name already exists."]
  }
}

{
  "result": "error",
  "message": "Email branding must have exactly one of alt_text and text."
}

Update Email Branding

Update an existing email branding configuration.

POST /email-branding/{email_branding_id}

Path Parameters

Parameter	Type	Description
`email_branding_id`	UUID	The ID of the email branding to update

Request Body

Field	Type	Required	Description
`name`	string	No	Updated name
`colour`	string	No	Updated hex colour code
`logo`	string	No	Updated logo file path or URL
`text`	string	No	Updated text
`alt_text`	string	No	Updated alternative text
`brand_type`	string	No	Updated brand type
`updated_by`	UUID	No	ID of user updating the branding

Example Request

{
  "colour": "#004c8c",
  "updated_by": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e"
}

Response

Status: 200 OK

{
  "data": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Department for Education",
    "colour": "#004c8c",
    "logo": "dfe-logo.png",
    "text": null,
    "alt_text": "Department for Education",
    "brand_type": "org",
    "created_at": "2024-03-03T09:15:00.000000Z",
    "created_by": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "updated_at": "2024-03-03T11:30:00.000000Z"
  }
}

Get Unique Name for Alt Text

Generate a unique branding name based on alt text. If the name already exists, returns an alternate name with a counter (e.g., “Name (alternate 1)”).

POST /email-branding/get-name-for-alt-text/

Request Body

Field	Type	Required	Description
`alt_text`	string	Yes	The alt text to generate a name from

Example Request

{
  "alt_text": "Home Office"
}

Response

Status: 200 OK

{
  "name": "Home Office (alternate 2)"
}

The endpoint checks for existing brandings with the same name and automatically increments the alternate counter up to 99.

Get Organizations and Services Using Branding

Retrieve all organizations and services associated with a specific email branding.

GET /email-branding/{email_branding_id}/orgs_and_services

Path Parameters

Parameter	Type	Description
`email_branding_id`	UUID	The ID of the email branding

Response

Status: 200 OK

{
  "data": {
    "organisations": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "name": "Cabinet Office",
        "active": true
      }
    ],
    "services": [
      {
        "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
        "name": "Internal Communications",
        "active": true,
        "restricted": false
      }
    ]
  }
}

Archive Email Branding

Archive an email branding configuration. The branding must not be in use by any organizations or services, and will be removed from all organization branding pools.

POST /email-branding/{email_branding_id}/archive

Path Parameters

Parameter	Type	Description
`email_branding_id`	UUID	The ID of the email branding to archive

Response

Status: 204 No Content

Error Response

Status: 400 Bad Request

{
  "result": "error",
  "message": "Email branding is in use and so it can't be archived."
}

Prerequisites for archiving:

The branding must not be assigned to any services
The branding must not be set as default for any organizations
The branding will be automatically removed from all organization branding pools
Archived brandings are renamed and marked as inactive

Code Examples

Python

import requests

base_url = "https://api.notifications.service.gov.uk"
headers = {"Authorization": f"Bearer {api_key}"}

# Create email branding
response = requests.post(
    f"{base_url}/email-branding",
    headers=headers,
    json={
        "name": "Ministry of Justice",
        "colour": "#231f20",
        "logo": "moj-logo.png",
        "alt_text": "Ministry of Justice",
        "brand_type": "org"
    }
)
branding = response.json()["data"]
print(f"Created branding: {branding['id']}")

# List all email brandings
response = requests.get(f"{base_url}/email-branding", headers=headers)
brandings = response.json()["email_branding"]

# Get specific branding
branding_id = "3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c"
response = requests.get(
    f"{base_url}/email-branding/{branding_id}",
    headers=headers
)
branding = response.json()["email_branding"]

# Update branding
response = requests.post(
    f"{base_url}/email-branding/{branding_id}",
    headers=headers,
    json={"colour": "#003078"}
)
updated = response.json()["data"]

cURL

# Create email branding
curl -X POST "https://api.notifications.service.gov.uk/email-branding" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ministry of Justice",
    "colour": "#231f20",
    "logo": "moj-logo.png",
    "alt_text": "Ministry of Justice",
    "brand_type": "org"
  }'

# List all email brandings
curl "https://api.notifications.service.gov.uk/email-branding" \
  -H "Authorization: Bearer $API_KEY"

# Get specific branding
curl "https://api.notifications.service.gov.uk/email-branding/3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c" \
  -H "Authorization: Bearer $API_KEY"

# Archive branding
curl -X POST "https://api.notifications.service.gov.uk/email-branding/3f5e7c9a-1b2d-4e8f-9a3c-7d6e4b2f1a8c/archive" \
  -H "Authorization: Bearer $API_KEY"

Letter Branding - Manage letter branding configurations
Organisations - Manage organization branding pools

Service Management

Billing & Stats

Branding & Organisation

Callbacks & Events

Overview

Email Branding Object

Properties

Brand Types

Endpoints

List Email Branding

Response

Get Email Branding by ID

Path Parameters

Response

Create Email Branding

Request Body

Example Request

Response

Error Responses

Update Email Branding

Path Parameters

Request Body

Example Request

Response

Get Unique Name for Alt Text

Request Body

Example Request

Response

Get Organizations and Services Using Branding

Path Parameters

Response

Archive Email Branding

Path Parameters

Response

Error Response

Code Examples

Python

cURL

Build docs developers (and LLMs) love

Service Management

Billing & Stats

Branding & Organisation

Callbacks & Events

​Overview

​Email Branding Object

​Properties

​Brand Types

​Endpoints

​List Email Branding

​Response

​Get Email Branding by ID

​Path Parameters

​Response

​Create Email Branding

​Request Body

​Example Request

​Response

​Error Responses

​Update Email Branding

​Path Parameters

​Request Body

​Example Request

​Response

​Get Unique Name for Alt Text

​Request Body

​Example Request

​Response

​Get Organizations and Services Using Branding

​Path Parameters

​Response

​Archive Email Branding

​Path Parameters

​Response

​Error Response

​Code Examples

​Python

​cURL

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Email Branding Object

Properties

Brand Types

Endpoints

List Email Branding

Response

Get Email Branding by ID

Path Parameters

Response

Create Email Branding

Request Body

Example Request

Response

Error Responses

Update Email Branding

Path Parameters

Request Body

Example Request

Response

Get Unique Name for Alt Text

Request Body

Example Request

Response

Get Organizations and Services Using Branding

Path Parameters

Response

Archive Email Branding

Path Parameters

Response

Error Response

Code Examples

Python

cURL

Related Endpoints