Get a notification by ID

You can filter the returned messages by including the following optional arguments in the URL:

• template_type
• status
• reference
• older_than

Arguments

You can omit any of these arguments to ignore these filters.

template_type (optional)

You can filter by:

• email
• sms
• letter

status (optional)

reference (optional)

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. For example:

"reference": "STRING"

older_than (optional)

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.

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

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.

Response

If the request is successful, the response body is json and the status code is 200.

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a", # required string - notification ID
  "reference": "STRING", # optional string - client reference
  "email_address": "sender@something.com",  # required string for emails
  "phone_number": "+447900900123",  # required string for text messages
  "type": "sms / email", # required string
  "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure", # required string
  "template": {
    "version": 1
    "id": 'f33517ff-2a88-4f6e-b855-c550268ce08a' # required string - template ID
    "uri": "/v2/template/{id}/{version}", # required
  },
  "body": "STRING", # required string - body of notification
  "subject": "STRING" # required string for email - subject of email
  "created_at": "STRING", # required string - date and time notification created
  "created_by_name": "STRING", # optional string - name of the person who sent the notification if sent manually
  "sent_at": " STRING", # optional string - date and time notification sent to provider
  "completed_at": "STRING" # optional string - date and time notification delivered or failed
}

Get a batch of notifications

This will return all your messages with statuses. They will display in pages of up to 250 messages each.

You can only get the status of messages that are 7 days old or newer.

You can filter the returned messages by including the following optional arguments in the URL:

• template_type
• status
• reference
• older_than

Arguments

You can omit any of these arguments to ignore these filters.

template_type (optional)

You can filter by:

• email
• sms
• letter

status (optional)

reference (optional)

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. For example:

"reference": "STRING"

older_than (optional)

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.

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

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.

Response

If the request is successful, the response body is json and the status code is 200.

{
  "notifications": [
    {
      "id": "740e5834-3a29-46b4-9a6f-16142fde533a", # required string - notification ID
      "reference": "STRING", # optional string - client reference
      "email_address": "sender@something.com",  # required string for emails
      "phone_number": "+447900900123",  # required string for text messages
      "type": "sms / email", # required string
      "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure", # required string
      "template": {
        "version": 1
        "id": 'f33517ff-2a88-4f6e-b855-c550268ce08a' # required string - template ID
        "uri": "/v2/template/{id}/{version}", # required
      },
      "body": "STRING", # required string - body of notification
      "subject": "STRING" # required string for email - subject of email
      "created_at": "STRING", # required string - date and time notification created
      "created_by_name": "STRING", # optional string - name of the person who sent the notification if sent manually
      "sent_at": " STRING", # optional string - date and time notification sent to provider
      "completed_at": "STRING" # optional string - date and time notification delivered or failed
    },
    …
  ],
  "links": {
    "current": "/notifications?template_type=sms&status=delivered",
    "next": "/notifications?other_than=last_id_in_list&template_type=sms&status=delivered"
  }
}

Send email message.

Arguments

email_address (required)

The email address of the recipient.

template_id (required)

Sign in to Notification and go to the Templates page to find the template ID.

personalisation (optional)

If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a dictionary with key value pairs. For example:

"personalisation": %{
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

reference (optional)

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. For example:

"reference": "STRING"

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

email_reply_to_id (optional)

This is an email reply-to address specified by you to receive replies from your users. Your service cannot go live until you set up at least one of these email addresses. To set up:

1. Sign into your Notification account.
2. Go to Settings.
3. If you need to change to another service, select Switch service in the top right corner of the screen and select the correct one.
4. Go to the Email section and select Manage on the Email reply-to addresses row.
5. Select Change to specify the email address to receive replies, and select Save.

For example:

"email_reply_to_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

You can leave out this argument if your service only has one email reply-to address, or you want to use the default email address.

Send a file by email

Send files without the need for email attachments.

This is an invitation-only feature. Contact the Notification team to enable this function for your service.

To send a file by email, add a placeholder field to the template then upload a file. The placeholder field will contain a secure link to download the file.

Add a placeholder field to the template

1. Sign in to Notification.
2. Go to the Templates page and select the relevant email template.
3. Add a placeholder field to the email template using double brackets. For example:

"Download your file at: ((link_to_document))"

Upload your file

The file you upload must be a PDF file smaller than 2MB. You’ll need to convert the file into a string that is base64 encoded.

Pass the file object as a value into the personalisation argument. For example:

"personalisation":{
  "first_name": "Amala",
  "application_date": "2018-01-01",
  "link_to_document": "file as base64 encoded string",
}

Response

If the request to the client is successful, the client returns a dict:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "MESSAGE TEXT",
    "from_email": "SENDER EMAIL"
  },
  "uri": "https://api.notification.alpha.canada.ca/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notification.alpha.canada.ca/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

Send sms message.

phone_number (required)

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

template_id (required)

Sign in to Notification and go to the Templates page to find the template ID.

personalisation (optional)

If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key value pairs. For example:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

You can leave out this argument if a template does not have any placeholder fields for personalised information.

reference (optional)

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. For example:

"reference": "STRING"

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

sms_sender_id (optional)

A unique identifier of the sender of the text message notification. You can find this information on the Text Message sender settings screen:

1. Sign into your Notification account.
2. Go to Settings.
3. If you need to change to another service, select Switch service in the top right corner of the screen and select the correct one.
4. Go to the Text Messages section and 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

"sms_sender_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

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

Response

If the request is successful, the response body is json with a status code of 201:

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

If you are using the test API key, all your messages will come back with a delivered status.

All messages sent using the team and whitelist or live keys will appear on your dashboard.