Registry /
communication / notifications-node-client
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NotifyClient
✓ import { NotifyClient } from 'notifications-node-client';
✗ const { NotifyClient } = require('notifications-node-client');
While CommonJS `require` still works, ESM `import` is the recommended standard for modern Node.js applications. The library is primarily CommonJS but provides type definitions for TypeScript.
NotifyClient
✓ const { NotifyClient } = require('notifications-node-client');
✗ import NotifyClient from 'notifications-node-client';
For CommonJS environments, use destructuring assignment from `require`. Importing as a default import without destructuring is incorrect as `NotifyClient` is a named export.
NotificationClientOptions
✓ import type { NotificationClientOptions } from 'notifications-node-client';
✗ import { NotificationClientOptions } from 'notifications-node-client';
When using TypeScript, prefer `import type` for type-only imports to ensure they are stripped from the JavaScript output, avoiding potential runtime issues or bundle size increases.
This quickstart demonstrates how to initialize the `NotifyClient` and send both an email and an SMS message using predefined templates and personalisation data. It highlights secure API key handling via environment variables and includes robust error handling for API responses.
import { NotifyClient } from 'notifications-node-client';
// Ensure you set your GOV.UK Notify API key in an environment variable
const API_KEY = process.env.GOVUK_NOTIFY_API_KEY ?? 'your-api-key';
// Instantiate the client
const notifyClient = new NotifyClient(API_KEY);
// Example: Sending an email
async function sendExampleEmail() {
const emailAddress = 'test@example.com';
const templateId = 'your-email-template-id'; // Replace with your actual template ID
const personalisation = {
name: 'John Doe',
application_status: 'approved',
};
const reference = 'my-email-ref-123'; // Optional unique reference
try {
console.log(`Attempting to send email to ${emailAddress} using template ${templateId}...`);
const response = await notifyClient.sendEmail(
templateId,
emailAddress,
personalisation,
reference
);
console.log('Email sent successfully!');
console.log('Response:', JSON.stringify(response.data, null, 2));
} catch (error: any) {
console.error('Failed to send email:');
// GOV.UK Notify errors often have a 'response.data.errors' structure
if (error.response && error.response.data && error.response.data.errors) {
console.error('API Error Details:', JSON.stringify(error.response.data.errors, null, 2));
} else {
console.error(error.message || error);
}
process.exit(1);
}
}
// Example: Sending an SMS
async function sendExampleSms() {
const phoneNumber = '+447900900123'; // Replace with a valid UK phone number
const templateId = 'your-sms-template-id'; // Replace with your actual template ID
const personalisation = {
verification_code: '123456',
};
const reference = 'my-sms-ref-456'; // Optional unique reference
try {
console.log(`Attempting to send SMS to ${phoneNumber} using template ${templateId}...`);
const response = await notifyClient.sendSms(
templateId,
phoneNumber,
personalisation,
reference
);
console.log('SMS sent successfully!');
console.log('Response:', JSON.stringify(response.data, null, 2));
} catch (error: any) {
console.error('Failed to send SMS:');
if (error.response && error.response.data && error.response.data.errors) {
console.error('API Error Details:', JSON.stringify(error.response.data.errors, null, 2));
} else {
console.error(error.message || error);
}
process.exit(1);
}
}
// Run the examples (uncomment to execute)
// sendExampleEmail();
// sendExampleSms();
Errors
Common errors & fixes
Error: Invalid API key: not a valid UUID
The provided API key is either missing, malformed, or does not conform to the UUID format expected by GOV.UK Notify.
fixDouble-check your API key for typos and ensure it's correctly copied from your GOV.UK Notify account. Verify that the environment variable holding the key is correctly loaded.
Error: Missing template ID
The `templateId` parameter was not provided to `sendEmail`, `sendSms`, or `sendLetter` methods, or it was `null`/`undefined`.
fixEnsure that a valid template ID string is passed as the first argument to the `sendEmail`, `sendSms`, or `sendLetter` method. These IDs are found in your GOV.UK Notify account.
Error: Can't send to this recipient using a team-only API key
You are attempting to send a notification to a recipient that is not on your team when using an API key that is restricted to 'team members only' (often a test key or development key).
fixFor production or sending to external recipients, ensure you are using an API key with appropriate permissions (usually a 'live' or 'production' key). For testing, add the recipient's email/phone number to your team in the GOV.UK Notify admin interface.
TypeError: notifyClient.sendEmail is not a function
This usually indicates that `notifyClient` was not correctly instantiated as a `NotifyClient` instance, or the import/require statement was incorrect, leading to `notifyClient` being `undefined` or a malformed object.
fixVerify that `new NotifyClient(API_KEY)` is called correctly. If using CommonJS, ensure `const { NotifyClient } = require('notifications-node-client');`. If using ESM, ensure `import { NotifyClient } from 'notifications-node-client';`. Audit
Dependencies
axiosrequiredUsed for HTTP requests, replaced 'request-promise' in v8.x.x. The client explicitly upgraded axios version from 0.19.2 to 0.21.1 and allows any compatible version (0.21.1 to <1.0.0).
jsonwebtokenrequiredUsed for JWT authentication with the Notify API. Updated to mitigate CVE-2022-23529, though the client authors noted it likely didn't affect use cases directly.