Skip to main content
POST
/
v2
/
notifications
/
email
Send Email Notification
curl --request POST \
  --url https://api.example.com/v2/notifications/email \
  --header 'Content-Type: application/json' \
  --data '
{
  "email_address": "<string>",
  "template_id": "<string>",
  "personalisation": {},
  "reference": "<string>",
  "email_reply_to_id": "<string>",
  "one_click_unsubscribe_url": "<string>",
  "scheduled_for": "<string>"
}
'
{
  "id": "<string>",
  "reference": "<string>",
  "content": {
    "content.from_email": "<string>",
    "content.body": "<string>",
    "content.subject": "<string>",
    "content.one_click_unsubscribe_url": "<string>"
  },
  "uri": "<string>",
  "template": {
    "template.id": "<string>",
    "template.version": 123,
    "template.uri": "<string>"
  },
  "scheduled_for": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alphagov/notifications-api/llms.txt

Use this file to discover all available pages before exploring further.

Send an email notification to an email address.

​
Request Body

​
email_address
string
required
The email address to send the notification to. Must be a valid email address.
​
template_id
string
required
The UUID of the email template to use.
​
personalisation
object
Key-value pairs to fill in placeholders in the template. Values can be strings or dictionaries for file uploads.For file uploads, provide an object with:
  • file: Base64 encoded file content (required)
  • is_csv: Boolean indicating if the file is a CSV (optional, mutually exclusive with filename)
  • filename: Custom filename to display (optional, mutually exclusive with is_csv)
  • confirm_email_before_download: Boolean to require email confirmation before download (optional, default: true)
  • retention_period: String specifying how long to retain the file, e.g., “26 weeks” (optional, default: “26 weeks”)
​
reference
string
A unique identifier for this notification that you can use to identify it later. Maximum 1,000 characters.
​
email_reply_to_id
string
The UUID of a specific email reply-to address to use. If not provided, the default reply-to address for the template will be used.
​
one_click_unsubscribe_url
string
An HTTPS URL for one-click unsubscribe. Must be a valid HTTPS URL.
​
scheduled_for
string
An ISO 8601 formatted datetime string to schedule the notification for sending. Must be within the next 24 hours. Set to null to send immediately.

​
Response

​
id
string
The unique identifier for this notification.
​
reference
string
The reference you provided, or null if you did not provide one.
​
content
object
The content of the email notification.
​
content.from_email
string
The email address the notification will be sent from.
​
content.body
string
The email body with placeholders filled in.
​
content.subject
string
The email subject with placeholders filled in.
​
content.one_click_unsubscribe_url
string
The one-click unsubscribe URL if provided.
​
uri
string
The URI to retrieve this notification.
​
template
object
Information about the template used.
​
template.id
string
The UUID of the template.
​
template.version
integer
The version number of the template.
​
template.uri
string
The URI to retrieve the template.
​
scheduled_for
string
The datetime the notification is scheduled for, or null if sending immediately.

​
Example Request

curl -X POST https://api.notifications.service.gov.uk/v2/notifications/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "user@example.gov.uk",
    "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "personalisation": {
      "name": "Jane Doe",
      "reference_number": "REF-12345"
    },
    "reference": "email-confirmation-456"
  }'

​
Example Request with File Upload

curl -X POST https://api.notifications.service.gov.uk/v2/notifications/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "user@example.gov.uk",
    "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "personalisation": {
      "name": "Jane Doe",
      "document": {
        "file": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQ=",
        "filename": "report.pdf",
        "confirm_email_before_download": true,
        "retention_period": "52 weeks"
      }
    }
  }'

​
Example Response

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "email-confirmation-456",
  "content": {
    "from_email": "noreply@notifications.service.gov.uk",
    "subject": "Confirmation for Jane Doe",
    "body": "Dear Jane Doe, your reference number is REF-12345.",
    "one_click_unsubscribe_url": null
  },
  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notifications.service.gov.uk/services/8b3aa916-e138-4d4b-8c96-da8b6ddfe9a2/templates/f33517ff-2a88-4f6e-b855-c550268ce08a"
  },
  "scheduled_for": null
}

​
Error Responses

​
400 Bad Request

Invalid email address 
{
  "status_code": 400,
  "errors": [
    {
      "error": "InvalidRecipientError",
      "message": "Not a valid email address"
    }
  ]
}
Missing required field 
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "email_address is a required property"
    }
  ]
}
Invalid file upload parameters 
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "Do not set a value for `is_csv` if `filename` is set."
    }
  ]
}

​
403 Forbidden

Service does not have permission to send emails 
{
  "status_code": 403,
  "errors": [
    {
      "error": "BadRequestError",
      "message": "Service is not allowed to send email"
    }
  ]
}

​
404 Not Found

Template not found 
{
  "status_code": 404,
  "errors": [
    {
      "error": "NoResultFound",
      "message": "No result found"
    }
  ]
}

​
429 Too Many Requests

Rate limit exceeded 
{
  "status_code": 429,
  "errors": [
    {
      "error": "RateLimitError",
      "message": "Exceeded rate limit for key type LIVE of 3000 requests per 60 seconds"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us