What is notifications-node-client?
The notifications-node-client is an npm package designed to interact with the GOV.UK Notify service, which allows you to send emails, text messages, and letters. This package provides a simple interface to integrate these notification services into your Node.js applications.
What are notifications-node-client's main functionalities?
Send Email
This feature allows you to send an email using a predefined template. You need to provide the template ID, recipient's email address, and any personalisation fields required by the template.
const NotifyClient = require('notifications-node-client').NotifyClient;
const notifyClient = new NotifyClient('your-api-key');
notifyClient.sendEmail('template-id', 'recipient@example.com', {
personalisation: {
name: 'John Doe',
reference: '12345'
},
reference: 'your-reference'
}).then(response => console.log(response)).catch(err => console.error(err));
Send SMS
This feature allows you to send an SMS using a predefined template. You need to provide the template ID, recipient's phone number, and any personalisation fields required by the template.
const NotifyClient = require('notifications-node-client').NotifyClient;
const notifyClient = new NotifyClient('your-api-key');
notifyClient.sendSms('template-id', '07123456789', {
personalisation: {
name: 'John Doe',
reference: '12345'
},
reference: 'your-reference'
}).then(response => console.log(response)).catch(err => console.error(err));
Send Letter
This feature allows you to send a letter using a predefined template. You need to provide the template ID and the recipient's address details.
const NotifyClient = require('notifications-node-client').NotifyClient;
const notifyClient = new NotifyClient('your-api-key');
notifyClient.sendLetter('template-id', {
personalisation: {
address_line_1: 'John Doe',
address_line_2: '123 Main Street',
postcode: 'AB1 2CD'
},
reference: 'your-reference'
}).then(response => console.log(response)).catch(err => console.error(err));
Other packages similar to notifications-node-client
nodemailer
Nodemailer is a module for Node.js applications to allow easy email sending. Unlike notifications-node-client, which is specific to the GOV.UK Notify service, Nodemailer is a more general-purpose email sending library that supports various transport methods including SMTP, AWS SES, and more.
twilio
Twilio is a comprehensive communication API that allows you to send SMS, make voice calls, and perform other communication tasks. It is more versatile compared to notifications-node-client, which is focused on the GOV.UK Notify service. Twilio supports a wide range of communication channels and is used globally.
sendgrid
SendGrid is a cloud-based service that provides email delivery and marketing campaigns. It offers a robust API for sending emails, managing lists, and tracking email performance. Unlike notifications-node-client, which is limited to the GOV.UK Notify service, SendGrid provides a broader range of email-related functionalities.
GOV.UK Notify Node.js client
Installation
npm install notifications-node-client
Getting started
var NotifyClient = require('notifications-node-client').NotifyClient,
notifyClient = new NotifyClient(apiKey);
Generate an API key by logging in to
GOV.UK Notify and going to
the API integration page.
Send messages
Text message
notifyClient.sendSms(templateId, phoneNumber, personalisation, reference);
Response
If the request is successful, response
will be an Object
:
{
"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"
}
}
Otherwise the client will raise a StatusCodeError
:
`error.status_code` | `error.message` |
---|
429
|
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
|
400
|
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
|
400
|
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
|
Email
notifyClient.sendEmail(templateId, emailAddress);
Response
If the request is successful, response
will be an Object
:
{
"id": "bfb50d92-100d-4b8b-b559-14fa3b091cda",
"reference": None,
"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"
}
}
Otherwise the client will raise a StatusCodeError
:
`error.status_code` | `error.message` |
---|
429
|
[{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (50) for today"
}]
|
400
|
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient using a team-only API key"
]}
|
400
|
[{
"error": "BadRequestError",
"message": "Can"t send to this recipient when service is in trial mode
- see https://www.notifications.service.gov.uk/trial-mode"
}]
|
Arguments
templateId
Find by clicking API info for the template you want to send.
personalisation
If a template has placeholders you need to provide their values. For example:
personalisation={
'first_name': 'Amala',
'reference_number': '300241',
}
Otherwise the parameter can be omitted or undefined
can be passed in its place.
reference
An optional identifier you generate if you don’t want to use Notify’s id
. It can be used to identify a single notification or a batch of notifications.
Get the status of one message
notifyClient.getNotificationById(notificationId)
Response
If the request is successful, response
will be an Object
:
{
"id": "notify_id",
"body": "Hello Foo",
"subject": "null|email_subject",
"reference": "client reference",
"email_address": "email address",
"phone_number": "phone number",
"line_1": "full name of a person or company",
"line_2": "123 The Street",
"line_3": "Some Area",
"line_4": "Some Town",
"line_5": "Some county",
"line_6": "Something else",
"postcode": "postcode",
"type": "sms|letter|email",
"status": "current status",
"template": {
"version": 1,
"id": 1,
"uri": "/template/{id}/{version}"
},
"created_at": "created at",
"sent_at": "sent to provider at",
}
Otherwise the client will raise a StatusCodeError
:
`error.status_code` | `error.message` |
---|
404
|
[{
"error": "NoResultFound",
"message": "No result found"
}]
|
400
|
[{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
|
Get the status of all messages
notifyClient.getNotifications(templateType, status, reference, olderThan)
Response
If the request is successful, response
will be an Object
:
{ "notifications":
[{
"id": "notify_id",
"reference": "client reference",
"email_address": "email address",
"phone_number": "phone number",
"line_1": "full name of a person or company",
"line_2": "123 The Street",
"line_3": "Some Area",
"line_4": "Some Town",
"line_5": "Some county",
"line_6": "Something else",
"postcode": "postcode",
"type": "sms | letter | email",
"status": sending | delivered | permanent-failure | temporary-failure | technical-failure
"template": {
"version": 1,
"id": 1,
"uri": "/template/{id}/{version}"
},
"created_at": "created at",
"sent_at": "sent to provider at",
},
…
],
"links": {
"current": "/notifications?template_type=sms&status=delivered",
"next": "/notifications?other_than=last_id_in_list&template_type=sms&status=delivered"
}
}
Otherwise the client will raise a StatusCodeError
:
`error.status_code` | `error.message` |
---|
400
|
[{
'error': 'ValidationError',
'message': 'bad status is not one of [created, sending, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure]'
}]
|
400
|
[{
"error": "ValidationError",
"message": "Apple is not one of [sms, email, letter]"
}]
|
Arguments
templateType
If omitted all messages are returned. Otherwise you can filter by:
status
If omitted all messages are returned. Otherwise you can filter by:
sending
- the message is queued to be sent by the provider.delivered
- the message was successfully delivered.failed
- this will return all failure statuses permanent-failure
, temporary-failure
and technical-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.
reference
This is the reference
you gave at the time of sending the notification. This can be omitted to ignore the filter.
olderThan
If omitted all messages are returned. Otherwise you can filter to retrieve all notifications older than the given notification id
.
[3.0.0] - 2016-12-16
Changed
notifyClient.sendSms(templateId, phoneNumber, personalisation, reference);
* Where `personalisation` and `reference` can be `undefined`.
- Update to
notifyClient.sendEmail()
:
- Added
reference
: an optional identifier you generate if you don’t want to use Notify’s id
. It can be used to identify a single notification or a batch of notifications. - Updated method signature:
notifyClient.sendEmail(templateId, emailAddress, personalisation, reference);
* Where `personalisation` and `reference` can be `undefined`.
NotificationClient.getAllNotifications()
- Notifications can now be filtered by
reference
and olderThanId
, see the README for details. - Updated method signature:
notifyClient.getNotifications(templateType, status, reference, olderThanId);
* Each one of these parameters can be `undefined`
Changelog not recorded - please see pull requests on github.