Send a message

Send a message.

Send a text message

post

You can use this endpoint to send text message. You can configure callbacks that provide delivery receipts by following the instructions in our documentation.

Authorizations

BearerAuth

AuthorizationstringRequired

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:

{
   "type":"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"

Body

application/json

The Send Text Message Request Payload

phone_numberstring · min: 7 · max: 15Required

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

Example: [phone]

template_idstringRequired

To find the template ID:

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

Example: f33517ff-2a88-4f6e-b855-c550268ce08a

referencestringOptional

You can leave out this argument if you do not have a reference. An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.

Example: STRING

sms_sender_idstringOptional

A unique identifier of the sender of the text message notification. To find the text message sender:

1. Sign in to NotifyNL.
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

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

Example: 8e222534-7f05-4972-86e3-17c5d9f894e2

Responses

201

Created

application/json

400

Bad request. Check the message in the response to find out why your request failed.

application/json

403

Auth error. Check the message in the response to find out why your request failed.

application/json

429

Rate or service limit error. Check the message in the response to find out why your request failed.

application/json

500

Internal server error. Check the message in the response to find out why your request failed.

application/json

post

/v2/notifications/sms

HTTPcURLJavaScriptPython

POST /v2/notifications/sms HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 234

{
  "phone_number": "[phone]",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "personalisation": {
    "first_name": "Amala",
    "application_date": "2018-01-01"
  },
  "reference": "STRING",
  "sms_sender_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"
}

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

Send an email

post

You can use this endpoint to send email. You can configure callbacks that provide delivery receipts by following the instructions in our documentation.

Authorizations

BearerAuth

AuthorizationstringRequired

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:

{
   "type":"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"

Body

application/json

The Send Email Request Payload

email_addressstring · min: 5 · max: 250Required

The email address of the recipient.

Example: [email protected]

template_idstringRequired

To find the template ID:

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

Example: f33517ff-2a88-4f6e-b855-c550268ce08a

one_click_unsubscribe_urlstringOptional

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

If you send subscription emails you must let recipients opt out of receiving them. Read our Using Notify page for more information about unsubscribe links.

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

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.

Unsubscribe link at the bottom of the email (recommended)

To add an unsubscribe link at the bottom of your email, use square brackets around the link text and round brackets around the URL. Make sure there are no spaces between the brackets or the link will not work.

Use this example if you have a webpage for users to manage their email subscriptions:

[Unsubscribe](https://www.example.gov.uk/unsubscribe)

Your webpage should ask the recipients to confirm that they want to unsubscribe.

If you do not have your own webpage, you can add a ‘mailto’ link to let users send an email to your team instead. For example:

[Unsubscribe](mailto:[email protected]?subject=unsubscribe)

The email address should be a shared inbox managed by your team, not your own email address.

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

referencestringOptional

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

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

Example: STRING

email_reply_to_idstringOptional

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 NotifyNL.
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.

Example: STRING

Responses

201

Created

application/json

400

Bad request. Check the message in the response to find out why your request failed.

application/json

403

Auth error. Check the message in the response to find out why your request failed.

application/json

429

Rate or service limit error. Check the message in the response to find out why your request failed.

application/json

500

Internal server error. Check the message in the response to find out why your request failed.

application/json

post

/v2/notifications/email

HTTPcURLJavaScriptPython

POST /v2/notifications/email HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 507

{
  "email_address": "[email protected]",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "one_click_unsubscribe_url": "https://example.com/unsubscribe.html?opaque=123456789",
  "personalisation": {
    "first_name": "Amala",
    "application_date": "2018-01-01",
    "required_documents": [
      "passport",
      "utility bill",
      "other id"
    ],
    "link_to_file": {
      "file": "file as base64 encoded string",
      "filename": "report.csv",
      "confirm_email_before_download": false,
      "retention_period": "4 weeks"
    }
  },
  "reference": "STRING",
  "email_reply_to_id": "STRING"
}

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "scheduled_for": null,
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "MESSAGE TEXT",
    "from_email": "SENDER EMAIL",
    "one_click_unsubscribe_url": "https://example.com/unsubscribe.html?opaque=123456789"
  },
  "uri": "https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notifynl.nl/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

Send a letter

post

You can use this endpoint to send letter.

Authorizations

BearerAuth

AuthorizationstringRequired

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:

{
   "type":"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"

Body

application/json

or

Responses

201

Created

application/json

400

Bad request. Check the message in the response to find out why your request failed.

application/json

403

Auth error. Check the message in the response to find out why your request failed.

application/json

429

Rate or service limit error. Check the message in the response to find out why your request failed.

application/json

post

/v2/notifications/letter

HTTPcURLJavaScriptPython

POST /v2/notifications/letter HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 418

{
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
  "personalisation": {
    "address_line_1": "The Occupier",
    "address_line_2": "123 High Street",
    "address_line_3": "Richmond upon Thames",
    "address_line_4": "Middlesex",
    "address_line_5": "SW14 6BF",
    "address_line_6": "string",
    "address_line_7": "string",
    "name": "John Smith",
    "application_id": "4134325",
    "required_documents": [
      "passport",
      "utility bill",
      "other id"
    ]
  },
  "reference": "STRING"
}

LetterPrecompiled Letter

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "LETTER TEXT"
  },
  "uri": "https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notifynl.nl/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  },
  "scheduled_for": null
}