Send an email notification to an email address.
Request Body
The email address to send the notification to. Must be a valid email address.
The UUID of the email template to use.
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”)
A unique identifier for this notification that you can use to identify it later. Maximum 1,000 characters.
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
An HTTPS URL for one-click unsubscribe. Must be a valid HTTPS URL.
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
The unique identifier for this notification.
The reference you provided, or null if you did not provide one.
The content of the email notification.The email address the notification will be sent from.
The email body with placeholders filled in.
The email subject with placeholders filled in.
content.one_click_unsubscribe_url
The one-click unsubscribe URL if provided.
The URI to retrieve this notification.
Information about the template used.The UUID of the template.
The version number of the template.
The URI to retrieve the template.
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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"
}
]
}
{
"status_code": 400,
"errors": [
{
"error": "ValidationError",
"message": "email_address is a required property"
}
]
}
{
"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"
}
]
}