GOV.UK Notify .NET client

This documentation is for developers interested in using this .NET client to integrate their government service with GOV.UK Notify.

Installation

Nuget Package Manager

The notifications-net-client is deployed to Bintray.

Click here to expand for more information.

Navigate to your project directory and install Notify with the following command:

nuget install Notify -Source https://api.bintray.com/nuget/gov-uk-notify/notifications-net-client

Alternatively if you are using the Nuget Package Manager in Visual Studio, add the source below to install:

https://api.bintray.com/nuget/gov-uk-notify/nuget

Visual Studio (Windows)

To execute the NUnit tests you will need to install the NUnit3 Test Adapter extension to Visual Studio.

Click here to expand for more information.

Setting Windows Environment variables

SETX NOTIFY_API_URL "https://example.notify-api.url"
SETX API_KEY "example_API_test_key"
SETX FUNCTIONAL_TEST_NUMBER "valid mobile number"
SETX FUNCTIONAL_TEST_EMAIL "valid email address"
SETX EMAIL_TEMPLATE_ID "valid email_template_id"
SETX SMS_TEMPLATE_ID "valid sms_template_id"
SETX LETTER_TEMPLATE_ID "valid letter_template_id"
SETX SMS_SENDER_ID "valid sms_sender_id - to test sending to a receiving number, so needs to be a real number"
SETX API_SENDING_KEY "API_whitelist_key for sending an SMS to a receiving number"
SETX INBOUND_SMS_QUERY_KEY "API_test_key to get received text messages"

Visual Studio (Mac OS)

In order to get the .Net client running in Visual Studio the target .Net Framework needs to be set to 4.6.2 and the application needs to be run from the terminal.

Click here to expand for more information.

open -n /Applications/"Visual Studio.app"

Setting Mac OS Environment variables (these must be sourced before opening the Visual Application using the command above)

export NOTIFY_API_URL=https://example.notify-api.url
export API_KEY=example_API_test_key
export FUNCTIONAL_TEST_NUMBER=valid mobile number
export FUNCTIONAL_TEST_EMAIL=valid email address
export EMAIL_TEMPLATE_ID=valid email_template_id
export SMS_TEMPLATE_ID=valid sms_template_id
export LETTER_TEMPLATE_ID=valid letter_template_id

Getting started

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

NotificationClient client = new NotificationClient(apiKey);

Generate an API key by signing in to GOV.UK Notify and going to the API integration page.

Send messages

Text message

Method

If the request is successful, response will be a SmsNotificationResponse .

Click here to expand for more information.

SmsNotificationResponse response = client.SendSms(mobileNumber, templateId, personalisation, reference, smsSenderId);

Response

Click here to expand for more information.

public String fromNumber;
public String body;
public String id;
public String reference;
public String uri;
public Template template;

public class Template {
    public String id;
    public String uri;
    public Int32 version;
}

Otherwise the client will raise a Notify.Exceptions.NotifyClientException:

`error.status_code`	`error.message`
`429`	`[{` `"error": "RateLimitError",` `"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"` `}]`
`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

Click here to expand for more information.

`mobileNumber`

The phone number of the recipient, only required for sms notifications.

`templateId`

Find by clicking API info for the template you want to send.

`reference`

An optional identifier you generate. The reference can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.

You can omit this argument if you do not require a reference for the notification.

`personalisation`

If a template has placeholders, you need to provide their values, for example:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" }
};

`sms_sender_id`

Optional. Specifies the identifier of the sms sender to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Text message sender'.

If you omit this argument your default sms sender will be set for the notification.

Email

Method

Click here to expand for more information.

EmailNotificationResponse response = client.SendEmail(emailAddress, templateId, personalisation, reference, emailReplyToId);

Response

If the request is successful, response will be an EmailNotificationResponse .

Click here to expand for more information.

public String fromEmail;
public String body;
public String subject;
public String id;
public String reference;
public String uri;
public Template template;

public class Template
{
    public String id;
    public String uri;
    public Int32 version;
}

Otherwise the client will raise a Notify.Exceptions.NotifyClientException.

`error.status_code`	`error.message`
`429`	`[{` `"error": "RateLimitError",` `"message": "Exceeded rate limit for key type TEAM of 10 requests per 10 seconds"` `}]`
`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

Click here to expand for more information.

`emailAddress`

The email address of the recipient, only required for email notifications.

`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:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "Foo" }
};

Otherwise the parameter can be omitted or null can be passed in its place.

`reference`

An optional identifier you generate. The reference can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.

You can omit this argument if you do not require a reference for the notification.

`emailReplyToId`

Optional. Specifies the identifier of the email reply-to address to set for the notification. The identifiers are found in your service Settings, when you 'Manage' your 'Email reply to addresses'.

If you omit this argument your default email reply-to address will be set for the notification.

Letter

Method

Click here to expand for more information.

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "address_line_1", "23 Foo Road" },  # required
    { "address_line_2", "Bar Town" }, # required
    { "address_line_3", "London" },
    { "postcode", "BAX S1P" } # required
      ... # any other optional address lines, or personalisation fields found in your template
};

LetterNotificationResponse response = client.SendLetter(templateId, personalisation, reference);

Response

If the request is successful, response will be an LetterNotificationResponse.

Click here to expand for more information.

public String id;
public String body;
public String subject;
public String reference;
public String uri;
public Template template;

public class Template
{
    public String id;
    public String uri;
    public Int32 version;
}

Otherwise the client will raise a Notify.Exceptions.NotifyClientException.

`error.status_code`	`error.message`
`429`	`[{` `"error": "RateLimitError",` `"message": "Exceeded rate limit for key type TEAM of 10 requests per 20 seconds"` `}]`
`429`	`[{` `"error": "TooManyRequestsError",` `"message": "Exceeded send limits (50) for today"` `}]`
`400`	`[{` `"error": "BadRequestError",` `"message": "Cannot send letters with a team api key"` `}]`
`400`	`[{` `"error": "BadRequestError",` `"message": "Cannot send letters when service is in trial mode"` `}]`
`400`	`[{` `"error": "ValidationError",` `"message": "personalisation address_line_1 is a required property"` `}]`

Arguments

Click here to expand for more information.

`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:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
{ "address_line_1", "23 Foo Road" }, # required
{ "address_line_2", "Bar Town" }, # required
{ "address_line_3", "London" },
{ "postcode", "BAX S1P" } # required
... # any other optional address lines, or personalisation fields found in your template
};

Otherwise the parameter can be omitted or null can be passed in its place.

`reference`

An optional identifier you generate. The reference can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.

You can omit this argument if you do not require a reference for the notification.

Get the status of one message

Method

Click here to expand for more information.

Notification notification = client.GetNotificationById(notificationId);

Response

If the request is successful, response will be a Notification.

Click here to expand for more information.

public String id;
public String completedAt;
public String createdAt;
public String emailAddress;
public String body;
public String subject;
public String line1;
public String line2;
public String line3;
public String line4;
public String line5;
public String line6;
public String phoneNumber;
public String postcode;
public String reference;
public String sentAt;
public String status;
public Template template;
public String type;

Otherwise the client will raise a Notify.Exceptions.NotifyClientException.

`error.status_code`	`error.message`
`404`	`[{` `"error": "NoResultFound",` `"message": "No result found"` `}]`
`400`	`[{` `"error": "ValidationError",` `"message": "id is not a valid UUID"` `}]`

Arguments

Click here to expand for more information.

`notificationId`

The ID of the notification.

Get the status of all messages

Method

Click here to expand for more information.

NotificationList notifications = client.GetNotifications(templateType, status, reference, olderThanId);

Response

If the request is successful, response will be a NotificationList.

Click here to expand for more information.

public List<Notification> notifications;
public Link links;

public class Link {
	public String current;
	public String next;
}

Otherwise the client will raise a Notify.Exceptions.NotifyClientException:

`status_code`	`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

Click here to expand for more information.

`templateType`

If omitted all messages are returned. Otherwise you can filter by:

email
sms
letter

`status`

If omitted all messages are returned. Otherwise you can filter by:

email

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 does not exist; remove this recipient from your list.
temporary-failure - the provider was unable to deliver message, email box was full; 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 omit this argument to ignore this filter.

text message

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, phone number does not exist; remove this recipient from your list.
temporary-failure - the provider was unable to deliver message, 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 omit this argument to ignore this filter.

letter

You can filter by:

accepted - the letter has been generated.
technical-failure - Notify had an unexpected error while sending to our printing provider

You can omit this argument to ignore this filter.

`reference`

An optional identifier you generate. The reference can be used as a unique reference for the notification. Because Notify does not require this reference to be unique you could also use this reference to identify a batch or group of notifications.

You can omit this argument if you do not require a reference for the notification.

`olderThanId`

If omitted all messages are returned. Otherwise you can filter to retrieve all notifications older than the given notification id.

Get a template by ID

Method

This will return the latest version of the template. Use get_template_version to retrieve a specific template version.

Click here to expand for more information.

TemplateResponse response = client.GetTemplateById(
    "templateId"
)

Response

If the request is successful, response will be a TemplateResponse.

Click here to expand for more information.

public String id;
public String name;
public String type;
public DateTime created_at;
public DateTime? updated_at;
public String created_by;
public int version;
public String body;
public String subject; // null if an sms message

Otherwise the client will raise a Notify.Exceptions.NotifyClientException.

`status_code`	`message`
`404`	`[{` `"error": "NoResultFound",` `"message": "No result found"` `}]`

Arguments

Click here to expand for more information.

`templateId`

Find by clicking API info for the template you want to send.

Get a template by ID and version

Method

Click here to expand for more information.

TemplateResponse response = client.GetTemplateByIdAndVersion(
    'templateId',
    1   // integer required for version number
)

Response

If the request is successful, response will be a TemplateResponse.

Click here to expand for more information.

public String id;
public String name;
public String type;
public DateTime created_at;
public DateTime? updated_at;
public String created_by;
public int version;
public String body;
public String subject; // null if an sms message

Otherwise the client will raise a Notify.Exceptions.NotifyClientException:

`error["status_code"]`	`error["message"]`
`404`	`[{` `"error": "NoResultFound",` `"message": "No result found"` `}]`

Arguments

Click here to expand for more information.

`templateId`

Find by clicking API info for the template you want to send.

`version`

The version number of the template

Get all templates

Method

Click here to expand for more information.

TemplateList response = client.GetAllTemplates(
    "sms" | "email" | "letter" // optional
)

This will return the latest version for each template.

See available template types

Response

If the request is successful, response will be a TemplateList.

Click here to expand for more information.

List<TemplateResponse> templates;

If no templates exist for a template type or there no templates for a service, the response will be a TemplateList with an empty templates list element:

List<TemplateResponse> templates; // empty list of templates

Arguments

Click here to expand for more information.

`templateType`

If omitted all messages are returned. Otherwise you can filter by:

email
sms
letter

Generate a preview template

Method

Click here to expand for more information.

TemplatePreviewResponse response = client.GenerateTemplatePreview(
    'templateId',
    personalisation
)

Response

If the request is successful, response will be a TemplatePreviewResponse.

Click here to expand for more information.

public String id;
public String type;
public int version;
public String body;
public String subject; // null if a sms message

Otherwise the client will raise a Notify.Exceptions.NotifyClientException:

`error["status_code"]`	`error["message"]`
`400`	`[{` `"error": "BadRequestError",` `"message": "Missing personalisation: [name]"` `}]`
`404`	`[{` `"error": "NoResultFound",` `"message": "No result found"` `}]`

Arguments

Click here to expand for more information.

`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:

Dictionary<String, dynamic> personalisation = new Dictionary<String, dynamic>
{
    { "name", "someone" }
};

Get all received text messages

ReceivedTextListResponse response = client.GetReceivedTexts(olderThanId);

Response

Click here to expand for more information.

If the request is successful, response will be a ReceivedTextListResponse:

public List<ReceivedText> receivedTextList;
public Link links;

public class Link {
	public String current;
	public String next;
}

A ReceivedText will have the following properties -

public String id;
public String userNumber;
public String createdAt;
public String serviceId;
public String notifyNumber;
public String content;

Arguments

Click here to expand for more information.

`olderThanId`

If omitted all messages are returned. Otherwise you can filter to retrieve all received text messages older than the given id.

Name		Name	Last commit message	Last commit date
Latest commit History 141 Commits
.github		.github
NotifyTests		NotifyTests
src/Notify		src/Notify
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
Notify.sln		Notify.sln
README.md		README.md
appveyor.txt		appveyor.txt

dougajmcdonald/notifications-net-client

Folders and files

Latest commit

History

Repository files navigation

GOV.UK Notify .NET client

Table of Contents

Installation

Nuget Package Manager

Visual Studio (Windows)

Visual Studio (Mac OS)

Getting started

Send messages

Text message

Method

Response

Arguments

mobileNumber

templateId

reference

personalisation

sms_sender_id

Email

Method

Response

Arguments

emailAddress

templateId

personalisation

reference

emailReplyToId

Letter

Method

Response

Arguments

templateId

personalisation

reference

Get the status of one message

Method

Response

Arguments

notificationId

Get the status of all messages

Method

Response

Arguments

templateType

status

reference

olderThanId

Get a template by ID

Method

Response

Arguments

templateId

Get a template by ID and version

Method

Response

Arguments

templateId

version

Get all templates

Method

Response

Arguments

templateType

Generate a preview template

Method

Response

Arguments

templateId

personalisation

Get all received text messages

Response

Arguments

olderThanId

About

Resources

Stars

`mobileNumber`

`templateId`

`reference`

`personalisation`

`sms_sender_id`

`emailAddress`

`templateId`

`personalisation`

`reference`

`emailReplyToId`

`templateId`

`personalisation`

`reference`

`notificationId`

`templateType`

`status`

`reference`

`olderThanId`

`templateId`

`templateId`

`version`

`templateType`

`templateId`

`personalisation`

`olderThanId`