Send a message

Use the send API to send a message to one or more recipients. The send API is very flexible, and has a large number of options available. Most of these are optional, and can be ignored unless you want to override the default behavior.

You are required to specify a to with at least one recipient. You must also specify either template or content.

POSThttps://api.courier.com/send

Send a notification to a specified recipient.

BODY PARAM

messageobject

tooneOfrequired

Single or multiple recipients.

user_idstring

A unique identifier associated with the recipient of the delivered message.

emailstring

A unique email address associated to the recipient of message.

phone_numberstring

A unique phone number associated to the recipient of message.

localestring

The locale of the user.

datajson

An object that includes any data you want to pass to the message. The data will populate the corresponding template or elemental variables.

templatestring

A notification template id or event mapping from Courier Studio. Either this or content must be specified.

contentobject

A simple content object or a complete Courier Elemental document. Either this or template must be specified.

titlestring

The title of a notification. (i.e. Email Subject / Push Title)

bodystring

The body of a notification.

brand_idstring

A unique identifier that represents the brand that should be used for rendering the notification. Note that a brand_id will only be applied to a Template message.

preferencesobject

A object that contains a field for the subscription topic you wish to respect.

subscription_topic_idstring

The id of the subscription topic whose preferences you wish to respect.

datajson

An object that includes any data you want to pass to the message. The data will populate the corresponding template or elemental variables.

channelsrecord

A map of valid channel identifiers (e.g. email, sms, etc.) to channel configuration objects whose properties are below. If you don't specify 'channels', Courier will use the default configuration for each channel as specified in the Courier Studio UI.

providersrecord

The providers object is a map of valid provider identifiers (e.g. twilio, slack, etc.) to provider configuration objects. If you don't specify providers, Courier will use the default configuration for each provider as specified in the Courier Studio UI.

routingobject

Allows you to customize which channel(s) Courier will potentially deliver the message. If no routing key is specified, Courier will use the default routing configured in the Courier Studio UI.

methodstring

The method for selecting channels to send the message with. Value can be either 'single' or 'all'. If not provided will default to 'single'

allsingle

channelsarray

An array of valid channel identifiers (like email, push, sms, etc.) and additional routing nodes.

metadataobject

eventstring

An arbitrary string to tracks the event that generated this request (e.g. 'signup').

tagsarray

An array of up to 9 tags you wish to associate with this request (and corresponding messages) for later analysis. Individual tags cannot be more than 30 characters in length.

trace_idstring

A unique ID used to correlate this request to processing on your servers. Courier does not verify the uniqueness of this ID.

utmobject

Identify the campaign that refers traffic to a specific website, and attributes the browser's website session.

campaignstring

contentstring

mediumstring

sourcestring

termstring

timeoutobject

messagenumber

An arbitrary duration for a message to be available for delivery. Default is 72 hours or 259200000 Milliseconds

channelnumber

(Business tier only) Time in ms to attempt a channel before failover.

providernumber

(Business tier only) Time in ms to attempt a provider before failover.

delayobject

durationnumber

The millisecond duration to delay the delivery of the message.

expiryobject

Expiry allows you to set an absolute or relative time in which a message expires. Note: This is only valid for the Courier Inbox channel as of 12-08-2022.

expires_atstring

An epoch timestamp or ISO8601 timestamp with timezone (YYYY-MM-DDThh:mm:ss.sTZD) that describes the time in which a message expires.

expires_instring

A duration in the form of milliseconds or an ISO8601 Duration format (i.e. P1DT4H). https://tc39.es/proposal-temporal/docs/duration.html

Responses

AUTH TOKEN

cURL

curl --request POST \
     --url https://api.courier.com/send \
     --header 'Accept: application/json' 

Node.js

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json'
  },
};

fetch('https://api.courier.com/send', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.courier.com/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body

Python

# Dependencies to install:
# $ python -m pip install requests

import requests

url = "https://api.courier.com/send"

headers = {
  "Accept": "application/json"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

Go

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.courier.com/send"

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Accept", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

PHP

<?php
// Dependencies to install:
// $ composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.courier.com/send', [
  'headers' => [
    'Accept' => 'application/json',
  ],
]);

echo $response->getBody();

Response Example

200 OK400 Bad Request

{
  "requestId": "1-5e2b2615-05efbb3acab9172f88dd3f6f"
}

Example

This example uses an existing notification template, and sends to a user by ID. We don't need to specify any other configuration or settings, since we will use the defaults. We don't need to provide any additional information about the user either, since we can rely on the user profile data already stored with Courier to customize the message.

Method: POST

URL: https://api.courier.com/send

Body: ​

{
    "message": {
        "to": {
            "user_id": "a1b2c3d4"
        },
        "template": "abcdef12345678"
    }
}

Example

This example uses an existing notification template, but overrides the template's routing to force the message to be sent by email. The user's email is specified in the to field, while the user's name appears in the data field. This makes the variable name available to the template for inclusion in the text of the message.

Method: POST

URL: https://api.courier.com/send

Body: ​

{
    "message": {
        "to": {
            "email": "hello@example.com"
        },
        "template": "abcdef12345678",
        "data": {
            "name": "John Doe"
        },
        "routing": {
            "method": "single",
            "channels": [
                "email"
            ]
        }
    }
}

Example

This example uses an existing notification template, and sends to multiple recipients: 2 lists and an audience.

Method: POST

URL: https://api.courier.com/send

Body:

{
    "message": {
        "to": [
            {
                "list_id": "LI56789"
            },
            {
                "list_id": "LI12345"
            },
            {
                "audience_id": "AUD334455"
            }
        ],
        "template": "abcdef12345678"
    }
}

Send Response Data

Sending a message is an async process. So upon submission of a message, only a requestId will be returned.

{ "requestId": "87e7c05b-4f46-fda24e356e23" }

Custom Formatting

To improve working with cURL, Courier also supports a custom urlencoded format that can be used in the place of JSON. This format allows nested data values using square bracket syntax. This is useful when passing profile and data parameters. For example, a cURL --data option with the profile parameter and a nested email would look like this:

--data "profile[email]=test@example.com"