Send Email Notification

POST /v2/notifications/email

Send Email Notification

cURL

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

200

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

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": "[e-mail]",
    "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": "[e-mail]",
    "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": "[e-mail]",
    "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"
    }
  ]
}