# Send a message

You can use GC Notify to send emails and text messages. These might be in response to a user-generated event, like a receipt after they apply to your service, or as a reminder when a payment is due.

What you'll need:

To send a message with GC Notify, you'll need to set up a template in the user interface.

To create a template:

  1. Sign in to GC Notify (opens new window).
  2. Go to the Templates page.
  3. Select New template.

Once you've got a template ready, find the template ID associated with it. You'll need that ID to specify which template you want to use when you call the API.

Your API call must also include any fields that have been set up as personalisations. Personalisation allows you to change what shows up in a specific message as it gets sent out. You might use personalisation to:

  • Address a user by their name
  • Provide users with a specific link to click
  • Send a unique transaction number as a follow up
  • Give users a dynamically generated list of actions they need to take

# Sending an email

POST /v2/notifications/email

# Request body

{
  "email_address": "sender@something.com",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

# Arguments

email_address (required)

The email_address of the recipient.

template_id (required)

To find the template_id:

  1. Sign in to GC Notify (opens new window).
  2. Go to the Templates page and select the relevant template.
  3. Select Copy template ID to clipboard.

personalisation (optional)

Use personalisation 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)

reference is 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 mailing address. For example:

"reference": "STRING"

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

email_reply_to_id (optional)

email_reply_to_id 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 GC Notify (opens new window).
  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.

For example:

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

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.

# Sending a file by email

Enabling this feature

Sending files by email is not enabled by default. To turn on this feature, contact us (opens new window).

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

The links are unique and unguessable. GC Notify cannot access or decrypt your file.

# Add contact details to the file download page

To turn on this feature, contact us (opens new window).

# Add a placeholder to the template

  1. Sign in to GC Notify (opens new window).
  2. Go to the Templates page and select the relevant email template.
  3. Select Edit.
  4. Add a placeholder to the email template using double brackets. For example:

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

# Upload your file

File types and size requirements

You can upload PDF, CSV, .jpeg, .png, .odt, .txt, .rtf, Microsoft Excel and Microsoft Word Document files. Your file must be smaller than 10MB.

Contact us (opens new window) if you need to send other file types.

You’ll need to convert the file into a string that is base64 encoded.

Pass the encoded string into an object with a file key, and put that in the personalisation argument. For example:

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

CSV files

Uploads for CSV files should set the is_csv flag as true to ensure it is downloaded as a .csv file. For example:

"personalisation":{
  "first_name": "Amala",
  "application_date": "2018-01-01",
  "link_to_file": {
    "file": "CSV file as base64 encoded string",
    "is_csv": true
  }
}

# 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.canada.ca/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notification.canada.ca/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

# Error codes

If the request is not successful, the response body is json, refer to the table below for details.

status_code message How to fix
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
}]
Use the correct type of API key
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode
}]
Your service cannot send this notification in trial mode
400 [{
"error": "BadRequestError",
"message": "Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)"
}]
Wrong file type. You can only upload .pdf, .csv, .txt, .jpeg, .png, .doc, .docx, .xls, .xlsx, .rtf ou .odt files
400 [{
"error": "BadRequestError",
"message": "File did not pass the virus scan"
}]
The file contains a virus
400 [{
"error": "BadRequestError",
"message": "Send files by email has not been set up - add contact details for your service"
}]
See how to add contact details to the file download page
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use the correct API keys
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 1000 requests per 60 seconds"
}]
Refer to API rate limits for more information
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Refer to service limits for the limit number
500 [{
"error": "Exception",
"message": "Internal server error"
}]
GC Notify was unable to process the request, resend your notification.

# Sending a text message

POST /v2/notifications/sms

# Request body

{
  "phone_number": "+19021234567",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

# Arguments

phone_number (required)

The phone_number of the recipient of the text message.

template_id (required)

To find the template_id:

  1. Sign in to GC Notify (opens new window).
  2. Go to the Templates page and select the relevant template.
  3. Select Copy template ID to clipboard.

personalisation (optional)

Use personalisation 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)

reference is 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)

sms_sender_id is a unique identifier of the sender of the text message notification.

To find the text message sender:

  1. Sign in to Notify (opens new window).
  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
"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.canada.ca/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "https://api.notification.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 safelist or live keys will appear on your dashboard.

# Error codes

If the request is not successful, the response body is json, refer to the table below for details.

status_code message How to fix
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
}]
Use the correct type of API key
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode"
}]
Your service cannot send this notification in trial mode
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use the correct API key
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 1000 requests per 60 seconds"
}]
Refer to API rate limits for more information
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Refer to service limits for the limit number
500 [{
"error": "Exception",
"message": "Internal server error"
}]
GC Notify was unable to process the request, resend your notification.