This documentation is for developers interested in using the GOV.UK Notify Java client to send emails, text messages or letters.

This documentation is for developers interested in using the GOV.UK Notify .NET client to send emails (including documents), text messages or letters. GOV.UK Notify supports .NET framework 4.6.2 and .NET Core 2.0.

This documentation is for developers interested in using the GOV.UK Notify Node.js client to send emails, text messages or letters.

This documentation is for developers interested in using the GOV.UK Notify PHP client to send emails, text messages or letters.

This documentation is for developers interested in using the GOV.UK Notify Python client to send emails, text messages or letters. Notify supports Python 3.7 and higher.

This documentation is for developers interested in using the GOV.UK Notify Ruby client to send emails, text messages or letters.

This documentation is for developers interested in using the GOV.UK Notify API to send emails, text messages or letters.

You can use it to integrate directly with the API if you cannot use one of our 6 client libraries.

The Notify PHP Client is based on a PSR-7 HTTP model [external link]. To install it, you must select your preferred PSR-7 compatible HTTP client. You can follow these instructions to use Guzzle v7[external link].

The notifications-java-client deploys to Maven Central.

Go to the GOV.UK Notify Java client page on Maven Central [external link]:

1. Select the most recent version.
2. Copy the dependency configuration snippet for your build tool.

Refer to the client changelog for the version number and the latest updates.

This documentation assumes you are using Microsoft Visual Studio [external link] with the NuGet Package Manager [external link].

Refer to the client changelog for the version number and the latest updates.

Run the following in the command line:

npm install --save notifications-node-client

1. Use Composer [external link] to install the GOV.UK Notify PHP client. Run the following in the command line:

   composer require php-http/guzzle7-adapter alphagov/notifications-php-client
   

   You can now use the autoloader [external link] to download the GOV.UK Notify PHP client.

2. Add the following code to your application to create a new instance of the client:

   $notifyClient = new \Alphagov\Notifications\Client([
       'apiKey' => '{your api key}',
       'httpClient' => new \Http\Adapter\Guzzle7\Client
   ]);
   

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

Run the following code in the command line:

pip install notifications-python-client

Refer to the client changelog for the client version number and the latest updates.

Run the following in the command line:

gem install 'notifications-ruby-client'

Refer to the client changelog for the version number and the latest updates.

Add this code to your application:

import uk.gov.service.notify.NotificationClient;
NotificationClient client = new NotificationClient(apiKey);

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

If you use a proxy you can pass it into the NotificationClient constructor.

import uk.gov.service.notify.NotificationClient;
NotificationClient client = new NotificationClient(apiKey, proxy);

The GOV.UK Notify client can be installed from Nuget.org [external link].

You can install the GOV.UK Notify client package using either the command line or Microsoft Visual Studio.

Add this code to your application:

var NotifyClient = require('notifications-node-client').NotifyClient

var notifyClient = new NotifyClient(apiKey)

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

Add this code to your application:

from notifications_python_client.notifications import NotificationsAPIClient

notifications_client = NotificationsAPIClient(api_key)

Add this code to your application:

require 'notifications/client'
client = Notifications::Client.new(api_key)

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

Go to your project directory and run the following in the command line to install the client package:

dotnet add package GovukNotify

Add this code to your application:

proxyConfig = {
  host: proxyHost,
  port: proxyPort
}

notifyClient.setProxy(proxyConfig)

where the proxyConfig should be an object supported by axios.

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

The default timeout is 30 seconds. For more information about timeouts see https://docs.python-requests.org/en/latest/user/advanced/#timeouts.

Use the NuGet Package Manager [external link] to install the GovukNotify client package in Visual Studio.

You can use either the console [external link] or the UI [external link].

You can provide your own Axios client to the Notify client. This is useful if you want to use a custom Axios client with specific settings, like custom interceptors.

Add this code to your application:

notifyClient.setClient(customAxiosClient)

where customAxiosClient is an instance of Axios.

Run the following in the NuGet package manager console to install the client package:

nuget install GovukNotify

Use the Package Manager UI to search for and install the client package [external link].

Add this code to your application:

using Notify.Client;
using Notify.Models;
using Notify.Models.Responses;

var client = new NotificationClient(apiKey);

To get an API key, sign in to GOV.UK Notify and go to the API integration page. You can find more information in the API keys section of this documentation.

If you use a proxy, you must set the proxy configuration in the web.config file. Refer to the Microsoft documentation on proxy configuration for more information.

using Notify.Client;
using Notify.Models;
using Notify.Models.Responses;
using System.Net.Http;

var httpClientWithProxy = new HttpClientWrapper(new HttpClient(...));
var client = new NotificationClient(httpClientWithProxy, apiKey);

You can use GOV.UK Notify to send emails, text messages and letters.

You can use GOV.UK Notify to send emails, text messages and letters.

You can use GOV.UK Notify to send emails, text messages and letters.

You can use GOV.UK Notify to send text messages, emails and letters.

You can use GOV.UK Notify to send emails, text messages and letters.

You can use GOV.UK Notify to send emails, text messages and letters.

The authorisation header is an API key that is encoded using JSON Web Tokens. You must include an authorisation header.

JSON Web Tokens have a standard header and a payload. The header consists of:

{
  "typ": "JWT",
  "alg": "HS256"
}

The payload consists of:

{
  "iss": "26785a09-ab16-4eb0-8407-a37497a57506",
  "iat": 1568818578
}

JSON Web Tokens are encoded using a secret key with the following format:

3d844edf-8d35-48ac-975b-e847b4f122b0

That secret key forms a part of your API key, which follows the format {key_name}-{iss-uuid}-{secret-key-uuid}.

For example, if your API key is my_test_key-26785a09-ab16-4eb0-8407-a37497a57506-3d844edf-8d35-48ac-975b-e847b4f122b0:

• your API key name is my_test_key
• your iss (your service id) is 26785a09-ab16-4eb0-8407-a37497a57506
• your secret key is 3d844edf-8d35-48ac-975b-e847b4f122b0

iat (issued at) is the current time in UTC in epoch seconds. The token expires within 30 seconds of the current time.

Refer to the JSON Web Tokens website for more information on encoding your authorisation header.

When you have an encoded and signed token, add that token to a header as follows:

"Authorization": "Bearer encoded_jwt_token"

notifyClient
  .sendSms(templateId, phoneNumber, {
    personalisation: personalisation,
    reference: reference,
    smsSenderId: smsSenderId
  })
  .then(response => console.log(response))
  .catch(err => console.error(err))

The method returns a promise [external link]. The promise will either:

• resolve with a response if successful
• fail with an err if unsuccessful

sendSms( $phoneNumber, $templateId, array $personalisation = array(), $reference = '', $smsSenderId = NULL  )

For example:

try {
    $response = $notifyClient->sendSms(
        '+447777111222',
        'df10a23e-2c6d-4ea5-87fb-82e520cbf93a', [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968'
        ],
        'unique_ref123',
        '862bfaaf-9f89-43dd-aafa-2868ce2926a9'
    );

} catch (ApiException $e){}

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

String templateId="f33517ff-2a88-4f6e-b855-c550268ce08a";

The phone number of the recipient of the text message. This can be a UK or international number.

string mobileNumber: "+447900900123";

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

'f33517ff-2a88-4f6e-b855-c550268ce08a'

The phone number of the recipient of the text message. This can be a UK or international number.

The phone number of the recipient of the text message. This can be a UK or international number.

The phone number of the text message recipient. This can be a UK or international number. For example:

phone_number:"+447900900123"

The phone number of the recipient of the text message. This number can be a UK or international number.

String phoneNumber="+447900900123";

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

string templateId: "f33517ff-2a88-4f6e-b855-c550268ce08a";

The phone number of the recipient of the text message. This number can be a UK or international number. For example:

'+447900900123'

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

template_id:"f33517ff-2a88-4f6e-b855-c550268ce08a"

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a map. For example:

Map<String, Object> personalisation = new HashMap<>();
personalisation.put("first_name", "Amala");
personalisation.put("application_date", "2018-01-01");
personalisation.put("list", listOfItems); // Will appear as a comma separated list in the message

If a template does not have any placeholder fields for personalised information, you must pass in an empty map or null.

If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a Dictionary. For example:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    {"first_name", "Amala"},
    {"application_date", "2018-01-01"}
};

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in an object. For example:

{
  'first_name': 'Amala',
  'reference_number': '300241'
}

If a template has placeholder fields for personalised information such as name or application date, you must provide their values in a dictionary with key value pairs. For example:

$personalisation = [
    'name' => 'Amala',
    'application_date'  => '2018-01-01'
];

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key value pairs. For example:

personalisation={
    'first_name': 'Amala',
    'application_date': '2018-01-01',
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a hash. For example:

personalisation: {
  name: "John Smith",
  ID: "300241",
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. If you do not have a reference, you must pass in an empty string or null.

String reference='STRING';

A unique identifier you can create if you need to. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:

string reference: "STRING";

You can leave out this argument if you do not have a reference.

A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. If you do not have a reference, you must pass in an empty string or null. For example:

'your_reference_here'

A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:

$reference = 'STRING';

You can leave out this argument if you do not have a reference.

A unique identifier you can create if necessary. This reference identifies a single unique message or a batch of messages. It must not contain any personal information such as name or postal address. For example:

reference='STRING', # optional string - identifies notification(s)

You can leave out this argument if you do not have a reference.

A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:

reference: "your_reference_string"

You can leave out this argument if you do not have a reference.

A unique identifier of the sender of the text message notification.

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

You can then either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service will use, and select Save

String smsSenderId='8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

A unique identifier of the sender of the text message notification.

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

You can then either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service uses, and select Save

For example:

string smsSenderId: "8e222534-7f05-4972-86e3-17c5d9f894e2";

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

A unique identifier of the sender of the text message notification. For example:

'8e222534-7f05-4972-86e3-17c5d9f894e2'

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

In this screen, you can either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service will use, and select Save

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

A unique identifier of the sender of the text message notification.

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

You can then either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service will use, and select Save

$smsSenderId='8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

A unique identifier of the sender of the text message.

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

You can then either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service will use, and select Save

sms_sender_id='8e222534-7f05-4972-86e3-17c5d9f894e2' # optional UUID string

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

A unique identifier of the sender of the text message notification.

To find the text message sender:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Text Messages section, select Manage on the Text Message sender row.

You can then either:

• copy the sender ID that you want to use and paste it into the method
• select Change to change the default sender that the service uses, and select Save

For example:

sms_sender_id: "8e222534-7f05-4972-86e3-17c5d9f894e2"

You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.

If the request to the client is successful, the client returns a SendSmsResponse:

UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
Optional<String> fromNumber;

If you are using the test API key, all your messages come back with a delivered status.

All messages sent using the team and guest list or live keys appear on your dashboard.

If the request to the client is successful, the client returns an SmsNotificationResponse:

public String id;
public String reference;
public String uri;
public Template template;
public SmsResponseContent;

public class Template {
    public String id;
    public String uri;
    public Int32 version;
}
public class SmsResponseContent{
    public string body;
    public string fromNumber;
}

If you use the test API key, all your messages come back with a delivered status.

All messages sent using the team and guest list or live keys appear on your dashboard.

If the request is successful, the promise resolves with a response object. For example, the response.data property will look like this:

{
  'id': 'bfb50d92-100d-4b8b-b559-14fa3b091cda',
  'reference': null,
  'content': {
    'body': 'Some words',
    'from_number': '40604'
  },
  'uri': 'https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd',
  'template': {
    'id': 'ceb50d92-100d-4b8b-b559-14fa3b091cda',
    'version': 1,
    'uri': 'https://api.notifications.service.gov.uk/v2/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda'
  }
}

If you are using the test API key, all your messages come back with a delivered status.

All messages sent using the team and guest list or live keys appear on your dashboard.

If the request to the client is successful, the client returns an array:

[
    "id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
    "reference" => None,
    "content" => [
        "body" => "Some words",
        "from_number" => "40604"
    ],
    "uri" => "https =>//api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
    "template" => [
        "id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
       "version" => 1,
       "uri" => "https://api.notifications.service.gov.uk/v2/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
    ]
];

If you are using the test API key, all your messages will come back with a delivered status.

All messages sent using the team and guest list or live keys will appear on your dashboard.

If the request to the client is successful, the client returns a dict:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "body": "MESSAGE TEXT",
    "from_number": "SENDER"
  },
  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": 'f33517ff-2a88-4f6e-b855-c550268ce08a',
    "version": INTEGER,
    "uri": "https://api.notifications.service.gov.uk/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
  }
}

If you are using the test API key, all your messages will come back with a delivered status.

All messages sent using the team and guest list or live keys will appear on your dashboard.

If the request to the client is successful, the client returns a Notifications::Client:ResponseNotification object. In the example shown in the Method section, the object is named smsresponse.

You can then call different methods on this object:

If you are using the test API key, all your messages come back with a delivered status.

All messages sent using the team and guest list or live keys appear on your GOV.UK Notify dashboard.

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

If the request is not successful, the client returns a Notify.Exceptions.NotifyClientException containing the relevant error code.

If the request is not successful, the promise fails with an err.

If the request is not successful, the client returns an Alphagov\Notifications\Exception\ApiException object containing the relevant error code.

If the request is not successful, the client returns an HTTPError containing the relevant error code.

If the request is not successful, the client raises a Notifications::Client::RequestError exception (or a subclass), which contains a code:

The content header is application/json:

"Content-type": "application/json"

notifyClient
  .sendEmail(templateId, emailAddress, {
    personalisation: personalisation,
    reference: reference,
    oneClickUnsubscribeURL: oneClickUnsubscribeURL,
    emailReplyToId: emailReplyToId
  })
  .then(response => console.log(response))
  .catch(err => console.error(err))

The method returns a promise [external link]. The promise will either:

• resolve with a response if successful
• fail with an err if unsuccessful

sendEmail( $emailAddress, $templateId, array $personalisation = array(), $reference = '', $emailReplyToId = NULL, $oneClickUnsubscribeURL = NULL )

For example:

try {

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c', [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968'
        ],
        'unique_ref123',
        '862bfaaf-9f89-43dd-aafa-2868ce2926a9',
        );

} catch (ApiException $e){}

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

String templateId="f33517ff-2a88-4f6e-b855-c550268ce08a";

The email address of the recipient. For example:

string emailAddress: "sender@something.com";

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

"f33517ff-2a88-4f6e-b855-c550268ce08a"

The email address of the recipient.

The email address of the recipient.

The email address of the recipient. For example:

email_address: "sender@something.com"

The email address of the recipient.

String emailAddress='sender@something.com';

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

string templateId: "f33517ff-2a88-4f6e-b855-c550268ce08a";

The email address of the recipient. For example:

"sender@something.com"

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

To find the template ID:

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant template.
3. Select Copy template ID to clipboard.

For example:

template_id: "f33517ff-2a88-4f6e-b855-c550268ce08a"

If a template has placeholder fields for personalised information such as name or application date, you must provide their values in a map. For example:

Map<String, Object> personalisation = new HashMap<>();
personalisation.put("first_name", "Amala");
personalisation.put("application_date", "2018-01-01");
// pass in a list and it will appear as bullet points in the message:
personalisation.put("list", listOfItems);

If a template does not have any placeholder fields for personalised information, you must pass in an empty map or null.

If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a Dictionary. For example:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    {"first_name", "Amala"},
    {"application_date", "2018-01-01"},
    // pass in a list and it will appear as bullet points in the message:
    {"required_documents", new List<string> {"passport", "utility bill", "other id"}}
};

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or application date, you must provide their values in an object. For example:

{
  personalisation: {
    'first_name': 'Amala',
    'application_number': '300241',
    // pass in an array and it will appear as bullet points in the message:
    'required_documents': ['passport', 'utility bill', 'other id']
  }
}

If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a dictionary with key value pairs. For example:

$personalisation = [
    'name' => 'Amala',
    'application_date'  => '2018-01-01',
    # pass in an array and it will appear as bullet points in the message:
    'required_documents' => ['passport', 'utility bill', 'other id']
];

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a dictionary with key value pairs. For example:

personalisation={
    "first_name": "Amala",
    "application_date": "2018-01-01",
    # pass in a list and it will appear as bullet points in the message:
    "required_documents": ["passport", "utility bill", "other id"],
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a hash. For example:

personalisation: {
  name: "John Smith",
  year: "2016",
  # pass in an array and it will appear as bullet points in the message:
  required_documents: ["passport", "utility bill", "other id"],
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. If you do not have a reference, you must pass in an empty string or null.

String reference='STRING';

A unique identifier you can create if you need to. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:

string reference: "STRING";

You can leave out this argument if you do not have a reference.

A unique identifier you create. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. If you do not have a reference, you must pass in an empty string or null. For example:

"your_reference_here"

A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address.

$reference = 'STRING';

You can leave out this argument if you do not have a reference.

A unique identifier you can create if necessary. This reference identifies a single unique email or a batch of emails. It must not contain any personal information such as name or postal address. For example:

reference='STRING', # optional string - identifies notification(s)

You can leave out this argument if you do not have a reference.

A unique identifier you can create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address. For example:

reference: "your_reference_string"

You can leave out this argument if you do not have a reference.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

URI oneClickUnsubscribeURL = 'https://example.com/unsubscribe.html?opaque=123456789'

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

You can leave out this argument if the email being sent is not a subscription email.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

string oneClickUnsubscribeURL : 'https://example.com/unsubscribe.html?opaque=123456789';

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

You can leave out this argument if the email being sent is not a subscription email.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

oneClickUnsubscribeURL = 'https://example.com/unsubscribe.html?opaque=123456789'

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

You can leave out this argument if the email being sent is not a subscription email.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

$one_click_unsubscribe_url = 'https://example.com/unsubscribe.html?opaque=123456789'

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

one_click_unsubscribe_url = 'https://example.com/unsubscribe.html?opaque=123456789'

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

You can leave out this argument if the email being sent is not a subscription email.

The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

Read our Using Notify page for more information about unsubscribe links.

one_click_unsubscribe_url: "https://example.com/unsubscribe.html?opaque=123456789"

The one-click unsubscribe URL must respond to an empty POST request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

Your unsubscribe URL and response must comply with the guidance specified in Section 3.1 of IETF RFC 8058.

You can leave out this argument if the email being sent is not a subscription email.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

String emailReplyToId='8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one reply-to email address, or you want to use the default email address.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

For example:

string emailReplyToId: "8e222534-7f05-4972-86e3-17c5d9f894e2";

You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

emailReplyToId='8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one reply-to email address, or you want to use the default email address.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

For example:

$emailReplyToId='8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

For example:

email_reply_to_id='8e222534-7f05-4972-86e3-17c5d9f894e2' # optional UUID string

You can leave out this argument if your service only has one reply-to email address, or you want to use the default email address.

This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

To add a reply-to email address:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Reply-to email addresses row.
4. Select Add reply-to address.
5. Enter the email address you want to use, and select Add.

For example:

email_reply_to_id: '8e222534-7f05-4972-86e3-17c5d9f894e2'

You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.

If the request to the client is successful, the client returns a SendEmailResponse:

UUID notificationId;
Optional<String> reference;
Optional<URI> oneClickUnsubscribeURL;
UUID templateId;
int templateVersion;
String templateUri;
String body;
String subject;
Optional<String> fromEmail;

If the request to the client is successful, the client returns an EmailNotificationResponse:

public String id;
public String reference;
public String oneClickUnsubscribeURL;
public String uri;
public Template template;
public EmailResponseContent content;

public class Template{
    public String id;
    public String uri;
    public Int32 version;
}
public class EmailResponseContent{
  public String fromEmail;
  public String body;
  public String subject;
}

If the request is successful, the promise resolves with a response object. For example, the response.data property will look like this:

{
  'id': 'bfb50d92-100d-4b8b-b559-14fa3b091cda',
  'reference': null,
  'oneClickUnsubscribeURL': null,
  'content': {
    'subject': 'Licence renewal',
    'body': 'Dear Bill, your licence is due for renewal on 3 January 2016.',
    'from_email': 'the_service@gov.uk'
  },
  'uri': 'https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd',
  'template': {
    'id': 'ceb50d92-100d-4b8b-b559-14fa3b091cda',
    'version': 1,
    'uri': 'https://api.notificaitons.service.gov.uk/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda'
  }
}

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

If the request is not successful, the client returns a Notify.Exceptions.NotifyClientException containing the relevant error code.

If the request is not successful, the promise fails with an err.

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

The links are unique and unguessable. GOV.UK Notify cannot access or decrypt your file.

Your file will be available to download for a default period of 26 weeks (6 months).

To help protect your files you can also:

• ask recipients to confirm their email address before downloading
• choose the length of time that a file is available to download

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Email section, select Manage on the Send files by email row.
4. Enter the contact details you want to use, and select Save.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

1. Sign in to GOV.UK Notify.
2. Go to the Templates page and select the relevant email template.
3. Select Edit.
4. Add a placeholder to the email template using double brackets. For example: “Download your file at: ((link_to_file))”

Your email should also tell recipients how long the file will be available to download.

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. Contact the GOV.UK Notify team if you need to send other file types.

1. Convert the PDF to a byte[].
2. Pass the byte[] to the personalisation argument.
3. Call the sendEmail method.

For example:

ClassLoader classLoader = getClass().getClassLoader();
File file = new File(classLoader.getResource("document_to_upload.pdf").getFile());
byte [] fileContents = FileUtils.readFileToByteArray(file);

HashMap<String, Object> personalisation = new HashMap();
personalisation.put("link_to_file", client.prepareUpload(fileContents));
client.sendEmail(templateId,
                 emailAddress,
                 personalisation,
                 reference,
                 emailReplyToId);

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. Contact the GOV.UK Notify team if you need to send other file types.

1. Convert the PDF to a byte[].
2. Pass the byte[] to the personalisation argument.
3. Call the sendEmail method.

For example:

byte[] documentContents = File.ReadAllBytes("<file path>");

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" },
    { "link_to_file", NotificationClient.PrepareUpload(documentContents)}
};

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. Contact the GOV.UK Notify team if you need to send other file types.

Pass the file object as a value into the personalisation argument. For example:

var fs = require('fs')

fs.readFile('path/to/document.pdf', function (err, pdfFile) {
  console.log(err)
  notifyClient.sendEmail(templateId, emailAddress, {
    personalisation: {
      first_name: 'Amala',
      application_date: '2018-01-01',
      link_to_file: notifyClient.prepareUpload(pdfFile)
    }
  }).then(response => console.log(response)).catch(err => console.error(err))
})

The method returns a promise [external link]. The promise will either:

• resolve with a response if successful
• fail with an err if unsuccessful

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB.. Contact the GOV.UK Notify team if you need to send other file types.

Pass the file object as a value into the personalisation argument. For example:

try {
    $file_data = file_get_contents('/path/to/my/file.pdf');

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968',
            'link_to_file' => $notifyClient->prepareUpload( $file_data )
        ]
    );
}
catch (ApiException $e){}
catch (InvalidArgumentException $e){}

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. Contact the GOV.UK Notify team if you need to send other file types.

Pass the file object as a value into the personalisation argument. For example:

from notifications_python_client import prepare_upload

with open('file.pdf', 'rb') as f:
    ...
    personalisation={
      'first_name': 'Amala',
      'application_date': '2018-01-01',
      'link_to_file': prepare_upload(f),
    }

You can upload PDF, CSV, JSON, .odt, .txt, .rtf, .xlsx and MS Word Document files. Your file must be smaller than 2MB. Contact the GOV.UK Notify team if you need to send other file types.

1. Pass the file object as an argument to the Notifications.prepare_upload helper method.
2. Pass the result into the personalisation argument.

For example:

File.open("file.pdf", "rb") do |f|
    ...
    personalisation: {
      first_name: "Amala",
      application_date: "2018-01-01",
      link_to_file: Notifications.prepare_upload(f),
    }
end

To do this you will need version 5.0.0-RELEASE of the Java client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

ClassLoader classLoader = getClass().getClassLoader();
File file = new File(classLoader.getResource("document_to_upload.pdf").getFile());
byte [] fileContents = FileUtils.readFileToByteArray(file);

HashMap<String, Object> personalisation = new HashMap();
personalisation.put("link_to_file", client.prepareUpload(fileContents, "report.csv"));
client.sendEmail(templateId,
                 emailAddress,
                 personalisation,
                 reference,
                 emailReplyToId);

To do this you will need version 7.0.0 of the .NET client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

byte[] documentContents = File.ReadAllBytes("<file path>");

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" },
    { "link_to_file", NotificationClient.PrepareUpload(documentContents, filename = "2023-12-25-daily-report.csv")}
};

To do this you will need version 8.0.0 of the Node client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

var fs = require('fs')
fs.readFile('path/to/document.csv', function (err, csvFile) {
  console.log(err)
  notifyClient.sendEmail(templateId, emailAddress, {
    personalisation: {
      first_name: 'Amala',
      application_date: '2018-01-01',
      link_to_file: notifyClient.prepareUpload(csvFile, { filename: '2023-12-25-daily-report.csv' })
    }
  }).then(response => console.log(response)).catch(err => console.error(err))
})

To do this you will need version 6.0.0 of the PHP client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

try {
    $file_data = file_get_contents('/path/to/my/file.csv');

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968',
            'link_to_file' => $notifyClient->prepareUpload( $file_data, "report.csv" )
        ]
    );
}
catch (ApiException $e){}
catch (InvalidArgumentException $e){}

To do this you will need version 9.0.0 of the Python client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

from notifications_python_client import prepare_upload

with open('file.csv', 'rb') as f:
    ...
    personalisation={
      'first_name': 'Amala',
      'application_date': '2018-01-01',
      'link_to_file': prepare_upload(f, filename='2023-12-25-daily-report.csv'),
    }

To do this you will need version 6.0.0 of the Ruby client library, or a more recent version.

You should provide a filename when you upload your file.

The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

The filename must end with a file extension. For example, .csv for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

If you do not provide a filename for your file, Notify will:

• generate a random filename
• try to add the correct file extension

If Notify cannot add the correct file extension, recipients may not be able to open your file.

File.open("file.csv", "rb") do |f|
    ...
    personalisation: {
      first_name: "Amala",
      application_date: "2018-01-01",
      link_to_file: Notifications.prepare_upload(f, filename="2023-12-25-daily-report.csv"),
    }
end

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

This security feature is turned on by default.

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 3.19.0-RELEASE of the Java client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirmEmailBeforeDownload flag to false.

ClassLoader classLoader = getClass().getClassLoader();
File file = new File(classLoader.getResource("document_to_upload.pdf").getFile());
byte [] fileContents = FileUtils.readFileToByteArray(file);

HashMap<String, Object> personalisation = new HashMap();
personalisation.put("link_to_file", client.prepareUpload(fileContents, false, false, "52 weeks"));
client.sendEmail(templateId,
                 emailAddress,
                 personalisation,
                 reference,
                 emailReplyToId);

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 6.1.0 of the .NET client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirmEmailBeforeDownload flag to false.

byte[] documentContents = File.ReadAllBytes("<file path>");

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" },
    { "link_to_file", NotificationClient.PrepareUpload(documentContents, false, false)}
};

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 5.2.0 of the Node.js client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirmEmailBeforeDownload option to false.

var fs = require('fs')

fs.readFile('path/to/document.pdf', function (err, pdfFile) {
  console.log(err)
  notifyClient.sendEmail(templateId, emailAddress, {
    personalisation: {
      first_name: 'Amala',
      application_date: '2018-01-01',
      link_to_file: notifyClient.prepareUpload(pdfFile, { confirmEmailBeforeDownload: false })
    }
  }).then(response => console.log(response)).catch(err => console.error(err))
})

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 4.2.0 of the PHP client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirm_email_before_download flag to false.

try {
    $file_data = file_get_contents('/path/to/my/file.pdf');

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968',
            'link_to_file' => $notifyClient->prepareUpload( $file_data, false, false )
        ]
    );
}
catch (ApiException $e){}
catch (InvalidArgumentException $e){}

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 6.4.0 of the Python client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirm_email_before_download flag to False.

from notifications_python_client import prepare_upload

with open('file.pdf', 'rb') as f:
    ...
    personalisation={
      'first_name': 'Amala',
      'application_date': '2018-01-01',
      'link_to_file': prepare_upload(f, confirm_email_before_download=False),
    }

If you do not want to use this feature, you can turn it off on a file-by-file basis.

To do this you will need version 5.4.0 of the Ruby client library, or a more recent version.

You should not turn this feature off if you send files that contain:

• personally identifiable information
• commercially sensitive information
• information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the Government Security Classifications policy

To let the recipient download the file without confirming their email address, set the confirm_email_before_download flag to false.

File.open("file.pdf", "rb") do |f|
    ...
    personalisation: {
      first_name: "Amala",
      application_date: "2018-01-01",
      link_to_file: Notifications.prepare_upload(f, confirm_email_before_download: false),
    }
end

Set the number of weeks you want the file to be available using the retention_period parameter.

To use this feature you will need 3.19.0-RELEASE of the Java client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

ClassLoader classLoader = getClass().getClassLoader();
File file = new File(classLoader.getResource("document_to_upload.pdf").getFile());
byte [] fileContents = FileUtils.readFileToByteArray(file);

HashMap<String, Object> personalisation = new HashMap();
personalisation.put("link_to_file",
                    client.prepareUpload(
                            fileContents,
                            false,
                            false,
                            new RetentionPeriodDuration(52, ChronoUnit.WEEKS)
                    ));
client.sendEmail(templateId,
                 emailAddress,
                 personalisation,
                 reference,
                 emailReplyToId);

Set the number of weeks you want the file to be available using the retentionPeriod parameter.

To use this feature will need version 6.1.0 of the .NET client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

byte[] documentContents = File.ReadAllBytes("<file path>");

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" },
    { "link_to_file", NotificationClient.PrepareUpload(documentContents, false, true, "52 weeks")}
};

Set the number of weeks you want the file to be available using the retentionPeriod option.

To use this feature will need version 5.2.0 of the Node.js client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

var fs = require('fs')

fs.readFile('path/to/document.pdf', function (err, pdfFile) {
  console.log(err)
  notifyClient.sendEmail(templateId, emailAddress, {
    personalisation: {
      first_name: 'Amala',
      application_date: '2018-01-01',
      link_to_file: notifyClient.prepareUpload(pdfFile, { retentionPeriod: '52 weeks' })
    }
  }).then(response => console.log(response)).catch(err => console.error(err))
})

Set the number of weeks you want the file to be available using the retentionPeriod key.

To use this feature will need version 4.2.0 of the PHP client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

try {
    $file_data = file_get_contents('/path/to/my/file.pdf');

    $response = $notifyClient->sendEmail(
        'betty@example.com',
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name' => 'Betty Smith',
            'dob'  => '12 July 1968',
            'link_to_file' => $notifyClient->prepareUpload( $file_data, false, null, "52 weeks" )
        ]
    );
}
catch (ApiException $e){}
catch (InvalidArgumentException $e){}

Set the number of weeks you want the file to be available using the retention_period key.

To use this feature will need version 6.4.0 of the Python client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

from notifications_python_client import prepare_upload

with open('file.pdf', 'rb') as f:
    ...
    personalisation={
      'first_name': 'Amala',
      'application_date': '2018-01-01',
      'link_to_file': prepare_upload(f, retention_period='4 weeks'),
    }

Set the number of weeks you want the file to be available using the retention_period key.

To use this feature will need version 5.4.0 of the Ruby client library, or a more recent version.

You can choose any value between 1 week and 78 weeks. When deciding this, you should consider:

• the need to protect the recipient’s personal information
• whether the recipient will need to download the file again later

If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).

File.open("file.pdf", "rb") do |f|
    ...
    personalisation: {
      first_name: "Amala",
      application_date: "2018-01-01",
      link_to_file: Notifications.prepare_upload(f, retention_period: '52 weeks'),
    }
end

If the request is not successful, the client returns an HTTPError containing the relevant error code.

If the request is not successful, the client returns a Notify.Exceptions.NotifyClientException containing the relevant error code.

If the request is successful, the promise resolves with a response object. For example, the response.data property will look like this:

{
  'id': '740e5834-3a29-46b4-9a6f-16142fde533a',
  'reference': 'your_reference_here',
  'content': {
    'subject': 'SUBJECT TEXT',
    'body': 'MESSAGE TEXT',
    'from_email': 'SENDER EMAIL'
  },
  'uri': 'https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a',
  'template': {
    'id': 'f33517ff-2a88-4f6e-b855-c550268ce08a',
    'version': INTEGER,
    'uri': 'https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a'
  }
}

If the request to the client is successful, the client returns an array:

[
    "id" => "bfb50d92-100d-4b8b-b559-14fa3b091cda",
    "reference" => None,
    "content" => [
        "subject" => "SUBJECT TEXT",
        "body" => "MESSAGE TEXT",
        "from_email" => "SENDER EMAIL
    ],
    "uri" => "https://api.notifications.service.gov.uk/v2/notifications/ceb50d92-100d-4b8b-b559-14fa3b091cd",
    "template" => [
        "id" => "ceb50d92-100d-4b8b-b559-14fa3b091cda",
        "version" => 1,
        "uri" => "https://api.notificaitons.service.gov.uk/service/your_service_id/templates/bfb50d92-100d-4b8b-b559-14fa3b091cda"
    ]
];

If the request to the client is successful, the client returns a dict:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "MESSAGE TEXT",
    "from_email": "SENDER EMAIL"
  },
  "uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": INTEGER,
    "uri": "https://api.notifications.service.gov.uk/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

If the request to the client is successful, the client returns a Notifications::Client:ResponseNotification object. In the example shown in the Method section, the object is named emailresponse.

You can then call different methods on this object to return the requested information.

If the request is not successful, the promise fails with an err.

If the request is not successful, the client returns an Alphagov\Notifications\Exception\ApiException object containing the relevant error code.

If the request is not successful, the client returns an HTTPError containing the relevant error code.

If the request is not successful, the client raises a Notifications::Client::RequestError exception (or a subclass), which contains a code:

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

When you add a new service it will start in trial mode. You can only send letters when your service is live.

To send Notify a request to go live:

1. Sign in to GOV.UK Notify.
2. Go to the Settings page.
3. In the Your service is in trial mode section, select request to go live.

notifyClient
  .sendLetter(templateId, {
    personalisation: personalisation,
    reference: reference
  })
  .then(response => console.log(response))
  .catch(err => console.error(err))

The method returns a promise [external link]. The promise will either:

• resolve with a response if successful
• fail with an err if unsuccessful

sendLetter( $templateId, array $personalisation = array(), $reference = '' )

For example:

try {

    $response = $notifyClient->sendEmail(
        'df10a23e-2c0d-4ea5-87fb-82e520cbf93c',
        [
            'name'=>'Fred',
            'address_line_1' => 'Foo',
            'address_line_2' => 'Bar',
            'address_line_3' => 'SW1 1AA'
        ],
        'unique_ref123'
    );

} catch (ApiException $e){}