Registry / communication / notifications-python-client

notifications-python-client

library12.1.0pypypi✓ verified 85d ago

The `notifications-python-client` is the official Python API client for GOV.UK Notify, a service that allows government departments to send emails, SMS messages, and letters to their users. It is actively maintained by the Government Digital Service (GDS), with version 10.0.1 being the latest stable release, reflecting ongoing development and adherence to GOV.UK standards.

communication

pip install notifications-python-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NOTIFICATIONS-PYTH

notifications-python-client

communicationpythonv12.1.0

Install

3.2s avg

Import

635ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v12.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.668s · 23.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.2s · import 0.601s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NotificationsAPIClient

✓ from notifications_python_client.notifications import NotificationsAPIClient

Demonstrates sending an email notification using the GOV.UK Notify client, including how to handle API keys from environment variables and basic error handling. Remember to replace `YOUR_EMAIL_TEMPLATE_ID` with a valid ID from your Notify service.

import os from notifications_python_client.notifications import NotificationsAPIClient # Ensure these are set as environment variables or retrieve securely # NOTIFY_API_KEY should be your service's API key (UUID format) api_key = os.environ.get('NOTIFY_API_KEY') if not api_key: raise ValueError("NOTIFY_API_KEY environment variable not set.") # For staging/test environments, you MUST specify the base_url: # client = NotificationsAPIClient(api_key=api_key, base_url='https://api.staging.notifications.service.gov.uk') # For production (default): client = NotificationsAPIClient(api_key=api_key) try: response = client.send_email_notification( email_address='test@example.com', template_id='YOUR_EMAIL_TEMPLATE_ID', # Replace with a valid template ID from your Notify account personalisation={ 'name': 'Test User', 'application_status': 'approved' }, reference='my_app_ref_123' # Optional reference for your records ) print("Email sent successfully:") print(response) except Exception as e: print(f"Error sending email: {e}")

Debug

Known issues

breakingGOV.UK Notify API keys issued after May 2018 use a simpler format (UUID only). Older keys (prefixed with service ID) require `notifications-python-client` versions older than `6.0` or conversion to the new format. Using an old-format key with recent client versions will result in authentication failures.

fix

Generate a new API key from the GOV.UK Notify admin interface. If this is not possible, ensure your client version matches the key format or adjust your API key implementation.

affects: All versions >= 6.0 when used with old API key formats.

breakingVersion 10.0.0 removed the explicit `requests` dependency pinning and made changes to how `base_url` is handled, especially regarding default values. This might impact environments where `requests` versions are tightly controlled or custom `base_url` configurations were subtly relied upon.

fix

Ensure your `base_url` is explicitly configured for non-production environments (e.g., staging). Review your `requests` dependency if you encounter version conflicts.

affects: 10.0.0 and above.

gotchaBy default, the client points to the production GOV.UK Notify API. For testing or staging environments, you must explicitly set the `base_url` parameter during client initialization.

fix

Initialize the client with `client = NotificationsAPIClient(api_key=your_key, base_url='https://api.staging.notifications.service.gov.uk')` for non-production usage.

affects: All versions.

Errors

Common errors & fixes

403 Forbidden: Not a valid API key. Check the key you are using is valid.

Incorrect API key, a revoked key, or using an old-format key with a newer client version.

fix

Verify the API key is correct and active in the GOV.UK Notify admin interface. If your key is old, generate a new one. Ensure no whitespace or typos.

403 Forbidden: Not authorised to send to this recipient (email address, phone number)

Attempting to send to an email/phone number not pre-approved on the service (e.g., not a team member) when using a 'team-only' API key, or your service is in trial mode and hasn't been approved for live sending to arbitrary recipients.

fix

Use a 'live' API key (if your service is approved) or ensure the recipient is added to your team members in GOV.UK Notify for testing with a 'team-only' key. Verify your service status in Notify admin.

400 Bad Request: Template not found

The `template_id` provided does not exist or is not associated with the service using the provided API key.

fix

Double-check the `template_id` in your GOV.UK Notify account and ensure it belongs to the correct service that the API key is linked to.

Upgrade

Version history

12.1.0latest on PyPI · released May 26, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alphagov/notifications-python-client ↗

packagehttps://pypi.org/project/notifications-python-client/ ↗

homepagehttps://www.notifications.service.gov.uk ↗