Skip to main content

​
Overview

This guide will walk you through sending your first notification using the GOV.UK Notify API. You’ll learn how to authenticate, install a client library, send a test SMS or email, and check the notification status.
Before you begin, you’ll need a GOV.UK Notify service account and an API key. If you don’t have these yet, contact your Notify administrator or visit the admin portal.

​
Prerequisites

  • A GOV.UK Notify service ID
  • An API key (team, live, or test key)
  • Python 3.7+ (or another supported language runtime)
  • Your service must have the appropriate permissions (SMS, email, or letter)
1

Get Your API Credentials

​
Retrieve Your API Key

API keys are created in the GOV.UK Notify admin interface. Each key has a specific type:
  • Test key - For development, doesn’t send real notifications
  • Team key - Sends only to team members (cannot send letters)
  • Live key - Sends to anyone (production use)
Your API key will look like this:
your_service_id-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Keep your API keys secure. Never commit them to version control or share them publicly.

​
Note Your Service ID

You’ll need your service ID (UUID format) for making API calls. This is part of your API key before the first hyphen, or you can find it in the admin interface.
2

Install a Client Library

GOV.UK Notify provides official client libraries for multiple languages. We’ll use Python for this guide.
pip install notifications-python-client
Client libraries handle JWT authentication, request signing, and error handling automatically.

​
Direct API Access (cURL)

If you prefer to use the REST API directly without a client library, you’ll need to generate JWT tokens for authentication. See the Authentication Guide for details.
3

Send Your First SMS Notification

​
Create a Template

First, create a template in the Notify admin interface with a unique ID. For this example, we’ll assume you have a template that looks like:
Hello ((name)), your verification code is ((code)).

​
Send the SMS

from notifications_python_client.notifications import NotificationsAPIClient

# Initialize the client
api_key = "your_service_id-api-key-secret"
notifications_client = NotificationsAPIClient(api_key)

# Send an SMS
response = notifications_client.send_sms_notification(
    phone_number="+447700900123",
    template_id="your-template-id-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    personalisation={
        "name": "Alice",
        "code": "12345"
    },
    reference="user-123-verification"  # Optional client reference
)

print(f"Notification ID: {response['id']}")
print(f"Status: {response['content']['body']}")

​
Response Format

The API returns a JSON response with notification details:
{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "user-123-verification",
  "content": {
    "body": "Hello Alice, your verification code is 12345.",
    "from_number": "GOVUK"
  },
  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "your-template-id",
    "version": 1,
    "uri": "https://api.notifications.service.gov.uk/v2/template/your-template-id"
  }
}
The reference field is optional but recommended for tracking notifications in your own system.
4

Send an Email Notification

Sending emails works similarly to SMS, but with an email address and optional reply-to address.
response = notifications_client.send_email_notification(
    email_address="[email protected]",
    template_id="your-email-template-id",
    personalisation={
        "name": "Alice",
        "application_number": "APP-12345"
    },
    email_reply_to_id="your-reply-to-id"  # Optional
)

print(f"Email notification ID: {response['id']}")

​
Email-Specific Features

  • File attachments - Send PDFs or CSV files (requires service permission)
  • Reply-to addresses - Configure custom reply-to email addresses
  • Unsubscribe links - Include one-click unsubscribe URLs (optional)
5

Check Notification Status

After sending a notification, you can check its delivery status using the notification ID.
# Get notification by ID
notification = notifications_client.get_notification_by_id(
    notification_id="740e5834-3a29-46b4-9a6f-16142fde533a"
)

print(f"Status: {notification['status']}")
print(f"Created: {notification['created_at']}")
print(f"Sent: {notification['sent_at']}")
print(f"Completed: {notification['completed_at']}")

​
Notification Statuses

StatusDescription
createdNotification created, queued for sending
sendingCurrently being sent to the provider
pendingSent to provider, awaiting confirmation
deliveredSuccessfully delivered to recipient
permanent-failureCould not be delivered (invalid number/email)
temporary-failureDelivery failed, will retry
technical-failureTechnical error, will not retry
Poll the status endpoint or use webhooks to track delivery. Most notifications reach delivered status within seconds.
6

List All Notifications (Optional)

You can retrieve all notifications sent by your service with optional filtering.
Python
# Get all notifications
notifications = notifications_client.get_all_notifications()

# Filter by status
notifications = notifications_client.get_all_notifications(
    status="delivered",
    template_type="sms"
)

# Filter by reference
notifications = notifications_client.get_all_notifications(
    reference="user-123-verification"
)

for notification in notifications['notifications']:
    print(f"{notification['id']}: {notification['status']}")
The API returns paginated results with 250 notifications per page. Use the older_than parameter to fetch additional pages.

​
What’s Next?

Authentication Deep Dive

Learn how JWT token authentication works in detail

Template Guide

Master template creation and personalisation

Rate Limits

Understand rate limiting and daily message caps

API Reference

Explore the complete API documentation

​
Troubleshooting

Error: “Invalid token: API key not found”
  • Verify your API key is correct and hasn’t been revoked
  • Check that your service is active (not archived)
  • Ensure you’re using the correct service ID in the token’s iss claim
Error: “Error: Your system clock must be accurate to within 30 seconds”
  • JWT tokens include an iat (issued at) timestamp
  • Ensure your server’s clock is synchronized with NTP
  • Tokens expire after 30 seconds by default
Error: “phone_number is a required property”
  • Ensure you’re including all required fields in your request
  • Phone numbers must be in international format (+44…)
  • Email addresses must be valid format
Error: “Cannot send letters with a team api key”
  • Team API keys cannot send letters for security reasons
  • Use a test or live API key for letter sending
Error: “Cannot send letters when service is in trial mode”
  • Services in trial mode cannot send letters (except with test keys)
  • Contact your administrator to upgrade your service
Error: “Exceeded send limits”
  • Services have daily message limits
  • Check your service settings for current limits
  • Limits reset at midnight UTC
For more detailed error handling, see the API Error Reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us