The notifications-java-client is deployed to Bintray. Add this snippet to your Maven settings.xml file.
<?xml version='1.0' encoding='UTF-8'?>
<settings xsi:schemaLocation='http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd' xmlns='http://maven.apache.org/SETTINGS/1.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
<profiles>
<profile>
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>bintray-gov-uk-notify-maven</id>
<name>bintray</name>
<url>http://dl.bintray.com/gov-uk-notify/maven</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>bintray-gov-uk-notify-maven</id>
<name>bintray-plugins</name>
<url>http://dl.bintray.com/gov-uk-notify/maven</url>
</pluginRepository>
</pluginRepositories>
<id>bintray</id>
</profile>
</profiles>
<activeProfiles>
<activeProfile>bintray</activeProfile>
</activeProfiles>
</settings>Then add the Maven dependency to your project.
<dependency>
<groupId>uk.gov.service.notify</groupId>
<artifactId>notifications-java-client</artifactId>
<version>3.3.0-RELEASE</version>
</dependency>
repositories {
mavenCentral()
maven {
url "http://dl.bintray.com/gov-uk-notify/maven"
}
}
dependencies {
compile('uk.gov.service.notify:notifications-java-client:3.3.0-RELEASE')
}
Click 'set me up!' on https://bintray.com/gov-uk-notify/maven/notifications-java-client for instructions.
import uk.gov.service.notify.NotificationClient;
import uk.gov.service.notify.Notification;
import uk.gov.service.notify.NotificationList;
import uk.gov.service.notify.SendEmailResponse;
import uk.gov.service.notify.SendSmsResponse;
NotificationClient client = new NotificationClient(apiKey);Generate an API key by signing in to GOV.UK Notify and going to the API integration page.
Map<String, String> personalisation = new HashMap<>();
personalisation.put("name", "Jo");
personalisation.put("reference_number", "13566");
SendSmsResponse response = client.sendSms(templateId, mobileNumber, personalisation, "yourReferenceString");SendSmsResponse
If the request is successful, the SendSmsResponse is returned from the client. Attributes of the SendSmsResponse are listed below.
UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
Optional<String> fromNumber;Otherwise the client will raise a NotificationClientException:
| message |
|---|
Status code: 429 {
"errors":
[{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
}
|
Status code: 429 {
"errors":
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
}
|
Status code 400: {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
}
|
Status code: 400 {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
}
|
HashMap<String, String> personalisation = new HashMap<>();
personalisation.put("name", "Jo");
personalisation.put("reference_number", "13566");
SendEmailResponse response = client.sendEmail(templateId, mobileNumber, personalisation, "yourReferenceString");SendEmailResponse
If the request is successful, the SendEmailResponse is returned from the client. Attributes of the SendEmailResponse are listed below.
UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
String subject;
Optional<String> fromEmail;Otherwise the client will raise a NotificationClientException:
| message |
|---|
Status code: 429 {
"errors":
[{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
}
|
Status code: 429 {
"errors":
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
}
|
Status code 400: {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
}
|
Status code: 400 {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
}
|
HashMap<String, String> personalisation = new HashMap<>();
personalisation.put("address_line_1", "Her Majesty The Queen"); // required
personalisation.put("address_line_2", "Buckingham Palace"); // required
personalisation.put("address_line_3", "London");
personalisation.put("postcode", "SW1 1AA"); // required
// add any other personalisation found in your template
SendLetterResponse response = client.sendLetter(templateId, personalisation, "yourReferenceString");SendLetterResponse
If the request is successful, the SendLetterResponse is returned from the client. Attributes of the SendLetterResponse are listed below.
UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
String subject;Otherwise the client will raise a NotificationClientException:
| message |
|---|
Status code: 429 {
"errors":
[{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"
}]
}
|
Status code: 429 {
"errors":
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
}
|
Status code 400: {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
}
|
Status code: 400 {
"errors":
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
}
|
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "personalisation address_line_1 is a required property"
}]
}
|
Status code: 400 {
"errors":
[{
"error": "BadRequestError",
"message": "Cannot send letters with a team api key"
}]
}
|
The mobile number the SMS notification is sent to.
The email address the email notification is sent to.
The template id is visible on the template page in the application.
If a template has placeholders, you need to provide their values. personalisation can be an empty or null in which case no placeholders are provided for the notification.
If you are sending a letter, you will need to provide the address fields in the format "address_line_#", numbered from 1 to 6, and also the "postcode" field
The fields "address_line_1", "address_line_2" and "postcode" are required.
An optional unique identifier for the notification or an identifier for a batch of notifications. reference can be an empty string or null.
Notification notification = client.getNotificationById(notificationId);Notification
If successful a notification is returned. Below is a list of attributes in a notification.
UUID id;
Optional<String> reference;
Optional<String> emailAddress;
Optional<String> phoneNumber;
Optional<String> line1;
Optional<String> line2;
Optional<String> line3;
Optional<String> line4;
Optional<String> line5;
Optional<String> line6;
Optional<String> postcode;
String notificationType;
String status;
UUID templateId;
int templateVersion;
String templateUri;
String body;
Optional<String subject;
DateTime createdAt;
Optional<DateTime> sentAt;
Optional<DateTime> completedAt;Otherwise the client will raise a NotificationClientException.
| message |
|---|
Status code: 404 {
"errors":
[{
"error": "NoResultFound",
"message": "No result found"
}]
}
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
}
|
NotificationList notification = client.getNotifications(status, notificationType, reference, olderThanId);NotificationList
If successful a NotificationList is returned. Below is a list of attributes in aNotificationList.
List<Notification> notifications;
String currentPageLink;
Optional<String> nextPageLink;Otherwise the client will raise a NotificationClientException.
| message |
|---|
Status code: 404 {
"errors":
[{
'error': 'ValidationError',
'message': 'bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]'
}]
}
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "Apple is not one of [sms, email, letter]"
}]
}
|
You can filter the notifications by the following options:
sending- the message is queued to be sent by the provider.delivered- the message was successfully delivered.failed- this will return all failure statusespermanent-failure,temporary-failureandtechnical-failure.permanent-failure- the provider was unable to deliver message, email or phone number does not exist; remove this recipient from your list.temporary-failure- the provider was unable to deliver message, email box was full or the phone was turned off; you can try to send the message again.technical-failure- Notify had a technical failure; you can try to send the message again.
You can pass an empty string or null to ignore the filter.
You can filter the notifications by the following options:
emailsmsletterYou can also pass in an empty string or null to ignore the filter.
This is the reference you gave at the time of sending the notification. The reference can be a unique identifier for the notification or an identifier for a batch of notifications.
You can pass an empty string or null to ignore the filter.
You can get the notifications older than a given Notification.notificationId.
You can pass an empty string or null to ignore the filter
This will return the latest version of the template. Use getTemplateVersion to retrieve a specific template version.
Template template = client.getTemplateById(templateId);Response
UUID id;
String templateType;
DateTime createdAt;
Optional<DateTime> updatedAt;
String createdBy;
int version;
String body;
Optional<String> subject;Otherwise the client will raise a NotificationClientException.
| message |
|---|
Status code: 404 {
"errors":
[{
"error": "NoResultFound",
"message": "No result found"
}]
}
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
}
|
The template id is visible on the template page in the application.
This will return the template for the given id and version.
Template template = client.getTemplateVersion(templateId, version);Response
UUID id;
String templateType;
DateTime createdAt;
Optional<DateTime> updatedAt;
String createdBy;
int version;
String body;
Optional<String> subject;Otherwise the client will raise a NotificationClientException.
| message |
|---|
Status code: 404 {
"errors":
[{
"error": "NoResultFound",
"message": "No result found"
}]
}
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
}
|
The template id is visible on the template page in the application.
A history of the template is kept. There is a link to See previous versions on the template page in the application.
This will return the latest version of each template for your service.
TemplateList templates = client.getAllTemplates(templateType);Response
List<Template> templates;If the response is successful, a TemplateList is returned.
If no templates exist for a template type or there no templates for a service, the templates list will be empty.
Otherwise the client will raise a NotificationClientException.
You can filter the templates by the following options:
emailsmsletterYou can also pass in an empty string or null to ignore the filter.
This will return the contents of a template with the placeholders replaced with the given personalisation.
TemplatePreview templatePreview = client.getTemplatePreview(templateId, personalisation)Response
UUID id;
String templateType;
int version;
String body;
Optional<String> subject;Otherwise a NotificationClientException is thrown.
| message |
|---|
Status code: 404 {
"errors":
[{
"error": "NoResultFound",
"message": "No result found"
}]
}
Status code: 400 {
"errors":
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
}
|
The template id is visible on the template page in the application.
If a template has placeholders, you need to provide their values. personalisation can be an empty or null in which case no placeholders are provided for the notification.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent