{"id":9984,"library":"notifications-python-client","title":"GOV.UK Notify Python Client","description":"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.","status":"active","version":"10.0.1","language":"en","source_language":"en","source_url":"https://github.com/alphagov/notifications-python-client","tags":["govuk","notify","email","sms","notifications","api-client","government"],"install":[{"cmd":"pip install notifications-python-client","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"NotificationsAPIClient","correct":"from notifications_python_client.notifications import NotificationsAPIClient"}],"quickstart":{"code":"import os\nfrom notifications_python_client.notifications import NotificationsAPIClient\n\n# Ensure these are set as environment variables or retrieve securely\n# NOTIFY_API_KEY should be your service's API key (UUID format)\napi_key = os.environ.get('NOTIFY_API_KEY')\n\nif not api_key:\n    raise ValueError(\"NOTIFY_API_KEY environment variable not set.\")\n\n# For staging/test environments, you MUST specify the base_url:\n# client = NotificationsAPIClient(api_key=api_key, base_url='https://api.staging.notifications.service.gov.uk')\n# For production (default):\nclient = NotificationsAPIClient(api_key=api_key)\n\ntry:\n    response = client.send_email_notification(\n        email_address='test@example.com',\n        template_id='YOUR_EMAIL_TEMPLATE_ID', # Replace with a valid template ID from your Notify account\n        personalisation={\n            'name': 'Test User',\n            'application_status': 'approved'\n        },\n        reference='my_app_ref_123' # Optional reference for your records\n    )\n    print(\"Email sent successfully:\")\n    print(response)\nexcept Exception as e:\n    print(f\"Error sending email: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions >= 6.0 when used with old API key formats."},{"fix":"Ensure your `base_url` is explicitly configured for non-production environments (e.g., staging). Review your `requests` dependency if you encounter version conflicts.","message":"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.","severity":"breaking","affected_versions":"10.0.0 and above."},{"fix":"Initialize the client with `client = NotificationsAPIClient(api_key=your_key, base_url='https://api.staging.notifications.service.gov.uk')` for non-production usage.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"Incorrect API key, a revoked key, or using an old-format key with a newer client version.","error":"403 Forbidden: Not a valid API key. Check the key you are using is valid."},{"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.","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.","error":"403 Forbidden: Not authorised to send to this recipient (email address, phone number)"},{"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.","cause":"The `template_id` provided does not exist or is not associated with the service using the provided API key.","error":"400 Bad Request: Template not found"}]}