Get message data

Get message status

Get the data for one message

get

You can use this endpoint to get the data for one message. The data includes the status of the message. The status will vary depending on the type of message you have sent. You can only get the data for messages sent within the retention period. The default retention period is 7 days. You can omit any of these optional arguments to ignore these filters.

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"

Path parameters

notification_idstringRequired

The ID of the notification. You can find the notification ID in the response to the original notification method call.

Example: 740e5834-3a29-46b4-9a6f-16142fde533a

Responses

200

Success

application/json

The Send Email Response Payload

idstringOptional

Required - notification ID

Example: 740e5834-3a29-46b4-9a6f-16142fde533a

referencestring · nullableOptional

Optional

Example: STRING

email_addressstring · nullableOptional

Required for emails

Example: [email protected]

phone_numberstring · nullableOptional

Required for text messages

Example: [phone]

line_1string · nullableOptional

Required for letter

Example: ADDRESS LINE 1

line_2string · nullableOptional

Required for letter

Example: ADDRESS LINE 2

line_3string · nullableOptional

Required for letter

Example: ADDRESS LINE 3

line_4string · nullableOptional

Required for letter

Example: ADDRESS LINE 4

line_5string · nullableOptional

Required for letter

Example: ADDRESS LINE 5

line_6string · nullableOptional

Required for letter

Example: ADDRESS LINE 6

postcodestring · nullableOptional

Required for letter

Example: NW1 2TZ

postagestring · enum · nullableOptional

Required for letter

Example: first / second / economy / europe / rest-of-worldPossible values:

typestring · enumOptional

Required

Example: sms / letter / emailPossible values:

statusstringOptional

Required

Example: sending / delivered / permanent-failure / temporary-failure / technical-failure

bodystringOptional

Required - body of notification

Example: STRING

subjectstring · nullableOptional

Required for email- subject of email

Example: STRING

created_atstringOptional

Required - date and time notification created

Example: 2024-05-17T15:58:38.342838Z

created_by_namestring · nullableOptional

Optional - name of the person who sent the notification if sent manually

Example: STRING

sent_atstringOptional

Optional - date and time notification sent to provider

Example: 2024-05-17T15:58:30.143000Z

completed_atstringOptional

Optional - date and time notification delivered or failed

Example: 2024-05-17T15:59:10.321000Z

scheduled_forstring · nullableOptional

Optional - date and time notification has been scheduled to be sent at

Example: 2024-05-17T09:00:00.000000Z

one_click_unsubscribe_urlstring · nullableOptional

Optional - URL that you provided so your recipients can unsubscribe

Example: STRING

is_cost_data_readybooleanOptional

true if cost data is ready, and false if it isn't

Example: true

cost_in_poundsnumber · floatOptional

Optional - cost of the notification in pounds. The cost does not take free allowance into account

Example: 0.0027

cost_detailsone ofOptional

or

or

object · emailOptional

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

404

Result not found. Check the message in the response to find out why your request failed.

application/json

get

/v2/notifications/{notification_id}

HTTPcURLJavaScriptPython

GET /v2/notifications/{notification_id} HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "email_address": "[email protected]",
  "phone_number": "[phone]",
  "line_1": "ADDRESS LINE 1",
  "line_2": "ADDRESS LINE 2",
  "line_3": "ADDRESS LINE 3",
  "line_4": "ADDRESS LINE 4",
  "line_5": "ADDRESS LINE 5",
  "line_6": "ADDRESS LINE 6",
  "postcode": "NW1 2TZ",
  "postage": "first / second / economy / europe / rest-of-world",
  "type": "sms / letter / email",
  "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "/v2/template/{id}/{version}"
  },
  "body": "STRING",
  "subject": "STRING",
  "created_at": "2024-05-17T15:58:38.342838Z",
  "created_by_name": "STRING",
  "sent_at": "2024-05-17T15:58:30.143000Z",
  "completed_at": "2024-05-17T15:59:10.321000Z",
  "scheduled_for": "2024-05-17T09:00:00.000000Z",
  "one_click_unsubscribe_url": "STRING",
  "is_cost_data_ready": true,
  "cost_in_pounds": 0.0027,
  "cost_details": {
    "billable_sms_fragments": 1,
    "international_rate_multiplier": 1,
    "sms_rate": 0.0027
  }
}

Get the data for multiple messages

get

This API call returns one page with data for up to 250 messages. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the older_than argument. You can only get the data for messages that are 7 days old or newer. This will return all your messages with statuses. They will display in pages of up to 250 messages each. You can omit any of these arguments to ignore these filters.

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"

Query parameters

template_typestring · enumOptional

You can filter by email, sms or letter

Possible values:

statusstring · enumOptional

You can filter by message status.

Example: {"summary":"Emails Status","description":"| Status | Description |\n| --- | --- |\n| `created` | NotifyNL has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds. |\n| `sending` | NotifyNL has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. NotifyNL is waiting for delivery information. |\n| `delivered` | The message was successfully delivered. |\n| `permanent-failure` | The provider could not deliver the message because the email address was wrong. You should remove these email addresses from your database. |\n| `temporary-failure` | The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. [Check your content does not look like spam](https://www.gov.uk/service-manual/design/sending-emails-and-text-messages#protect-your-users-from-spam-and-phishing) before you try to send the message again. |\n| `technical-failure` | Your message was not sent because there was a problem between Notify and the provider. <br>You’ll have to try sending your messages again. |\n"}Possible values:

referencestringOptional

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

older_thanstringOptional

Input the ID of a notification into this argument. If you use this argument, the method returns the next 250 received notifications older than the given ID.If you leave out this argument, the method returns the most recent 250 notifications.The client only returns notifications that are 7 days old or newer. If the notification specified in this argument is older than 7 days, the client returns an empty response.

Example: 740e5834-3a29-46b4-9a6f-16142fde533a

include_jobsbooleanOptional

Includes notifications sent as part of a batch upload.If you leave out this argument, the method only returns notifications sent using the API.

Example: true

Responses

200

Success

application/json

The Send Text Message Response Payload

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

404

Result not found. Check the message in the response to find out why your request failed.

application/json

get

/v2/notifications

HTTPcURLJavaScriptPython

GET /v2/notifications HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "notifications": [
    {
      "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
      "reference": "STRING",
      "email_address": "[email protected]",
      "phone_number": "[phone]",
      "line_1": "ADDRESS LINE 1",
      "line_2": "ADDRESS LINE 2",
      "line_3": "ADDRESS LINE 3",
      "line_4": "ADDRESS LINE 4",
      "line_5": "ADDRESS LINE 5",
      "line_6": "ADDRESS LINE 6",
      "postcode": "NW1 2TZ",
      "postage": "first / second / economy / europe / rest-of-world",
      "type": "sms / letter / email",
      "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure",
      "template": {
        "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
        "version": 1,
        "uri": "/v2/template/{id}/{version}"
      },
      "body": "STRING",
      "subject": "STRING",
      "created_at": "2024-05-17T15:58:38.342838Z",
      "created_by_name": "STRING",
      "sent_at": "2024-05-17T15:58:30.143000Z",
      "completed_at": "2024-05-17T15:59:10.321000Z",
      "scheduled_for": "2024-05-17T09:00:00.000000Z",
      "one_click_unsubscribe_url": "STRING",
      "is_cost_data_ready": true,
      "cost_in_pounds": 0.0027,
      "cost_details": {
        "billable_sms_fragments": 1,
        "international_rate_multiplier": 1,
        "sms_rate": 0.0027
      }
    }
  ],
  "links": {
    "current": "https://api.notifynl.nl/v2/notifications?template_type=sms&status=delivered",
    "next": "https://api.notifynl.nl/v2/notifications?older_than=last_id_in_list&template_type=sms&status=delivered"
  }
}

Get the the PDF contents of a letter

get

You can use this endpoint to get PDF contents of a 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"

Path parameters

notification_idstringRequired

The ID of the notification. You can find the notification ID in the response to the original notification method call. You can also find it by signing in to NotifyNL and going to the API integration page.

Example: 740e5834-3a29-46b4-9a6f-16142fde533a

Responses

200

If the request to the client is successful, the client will return bytes representing the raw PDF data.

application/pdf

string · binaryOptional

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

404

Result not found. Check the message in the response to find out why your request failed.

application/json

get

/v2/notifications/{notification_id}/pdf

HTTPcURLJavaScriptPython

GET /v2/notifications/{notification_id}/pdf HTTP/1.1
Host: api.notifynl.nl
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

binary