GOV.UK Notify Python Client

Common errors

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

  cause 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)

  cause 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

  cause 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.

Warnings

• breaking GOV.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.
• breaking Version 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.
• gotcha By 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.

Install

• pip install notifications-python-client Install stable version

Imports

• NotificationsAPIClient

  from notifications_python_client.notifications import NotificationsAPIClient

Quickstart

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}")