Skip to main content

Send a message

Use the send API to send a message to one or more recipients.

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

Path: /send

Method: POST

{
  "message": {
    "to": {
      "email": "darth@vader.com"
    },
    "content": {
      "title": "Why did Anakin cross the road??",
      "body": "To get to the dark side."
    }
  }
}

Request Body​

The POST accepts a JSON payload with a single message property.

messageMessagerequired
Defines the message to be delivered
+ Show message object

The Message Property​

The message property has the following primary top-level properties. They define the destination and content of the message.

Additional advanced configuration fields are defined below.

toProfile | array<Profile>required
The recipient or a list of recipients of the message
+ Show profile object
templatestring
The id of the notification template to be rendered and sent to the recipient(s). This field or the content field must be supplied.
contentContent
Describes the content of the message in a way that will work for email, push, chat, or any channel. Either this or template must be specified.
+ Show content object
dataobject
An arbitrary object that includes any data you want to pass to the message. The data will populate the corresponding template or elements variables.

The To Property​

Required. The recipient or recipients or this message.

Example of sending to a single recipient:

"to": {
    "email": "darth@vader.com"
}

Example of sending to multiple recipients:

"to": [
    {
        "email": "darth@vader.com"
    },
    {
        "email": "luke@skywalker.com"
    }
]
emailstring
Email Address
phone_numberstring
A valid phone number
localestring
The user's preferred ISO 639-1 language code.
additional fields[key: string]: any
Additional provider specific fields may be specified.
user_idstring
Id of a user stored with Courier.
list_idstring
A unique identifier associated with a List of subscribers. A message will be sent to each subscriber in the list.
audience_idstring
A unique identifier associated with an Audience. A message will be sent to each user in the audience.
tenant_idstring
A unique identifier associated with an Tenant. A message will be sent to each member of the tenant using any branding or default preferences associated with that tenant.
dataobject
An object that includes any data you want to pass to the message. The data will populate the corresponding template or content variables.
contextContext
Context to load with this recipient. Will override any context set on message.context.
+ Show context
filtersarray<Filter>
When sending to a list or audience, this field may be supplied for adhoc filtering criteria. When a member of the list or audience doesn't meet the criteria of each supplied filter, they will be skipped. A list of available operators is available under audience operators.
Note: This feature is part of the Tenants Private Beta.

The Content Property​

Describes the content of the message in a way that will work for email, push, chat, or any channel. Either this field or template must be specified.

"content": {
    "title": "Why did Anakin cross the road?",
    "body": "To get to the dark side!"
}
titlestring
The title to be displayed by channels that support a title, such as email.
bodystring
Text content displayed in the notification. Supports markdown.
elementsarray
Elements describing the content of the notification. Use this field or body. See elements for a list of available elements.
versionstring
The version of elemental being supplied. Currently, only `2020-01-01` is supported.

The Data Property​

An arbitrary object that includes any data you want to pass to the message. The data can be used to populate corresponding template/content variables or be passed-through to your application via the Courier client SDKs.

"data": {
  "real_name": "Anakin Skywalker",
  "nickname": "Darth Vader",
  "category": "villain"
}

Other Message Properties​

The following properties support overriding configured values and defaults at run-time and attaching metadata to messages.

brand_idstring
Id of the brand that should be used for rendering the message. If not specified, the brand configured as default brand will be used.
channels{ [channel: ChannelId]: ChannelConfig }
Define run-time configuration for one or more channels. If you don't specify channels, the default configuration for each channel will be used. Valid ChannelId's are: email, sms, push, inbox, direct_message, banner, and webhook.
+ Show channel config object
contextContext
Context information such as tenant_id to send the notification with.
+ Show context config object
delayDelay
Defines the time to wait before delivering the message.
+ Show delay object
metadataMetadata
Metadata such as utm tracking attached with the notification.
+ Show metadata object
expiryExpiry
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.
+ Show expiry object
preferencesMessagePreferences
Configuration related to this notification and user preferences. Primary used to set the subscription_topic associated with this message
+ Show preferences object
providers{ [provider: ProviderId]: ProviderConfig }
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.
+ Show provider config object
routingRouting
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 configuration or routing defined by the template.
+ Show routing object
timeoutTimeout
In the event of a retryable error, this field defines the amount of time courier should attempt to deliver the message and/or failover to another provider or channel
+ Show timeout object

The Channels Property​

An object whose keys are valid channel identifiers (email, sms, etc) which map to an object with the following properties.

"channels": {
    "sms": {
        "brand_id": "xxx"
    }
}
brand_idstring
Specify the ID of the Brand which will apply to all messages sent through this channel.
ifstring
A JavaScript conditional expression to determine if the message should be sent through the channel. Has access to the data and profile object. Ex. `data.name === profile.name`
providersarray<string>
A list of providers enabled for this channel. Courier will select one provider to send through unless routing_method is set to all.
routing_methodstring
The method for selecting the providers to send the message with. Valid values are single or all. Single will send to one of the available providers for this channel, all will send the message through all channels. Defaults to single.
overrideobject
Channel specific overrides.
metadataMetadata
Metadata such as utm tracking attached with the notification through this channel.
+ Show metadata object
timeoutstring
Time in ms to attempt the channel before failing over to the next available channel.Business Tier

The Expiry Property​

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 | number
A duration in the form of milliseconds or an ISO8601 Duration format (i.e. P1DT4H). 

The Metadata Property​

Attach information not related to the content of the message for application or marketing use cases.

eventstring
An arbitrary string to tracks the event that generated this request (e.g. 'signup').
tagsarray<string>
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. Note: Courier does not verify the uniqueness of this ID.
utmUtm
Identify the campaign that refers traffic to a specific website, and attributes the browser's website session.
+ Show utm fields

The Providers Property​

An object whose keys are valid provider identifiers which map to an object with the following properties:

"providers": {
  "slack": {
    "if": "profile.locale === 'en-us'"
  }
}
ifstring
A JavaScript conditional expression to determine if the message should be sent through the channel. Has access to the data and profile object. Ex. `data.name === profile.name`
overrideobject
Provider specific overrides.
metadataMetadata
Metadata such as utm tracking attached with the notification through this provider.
timeoutstring
Time in ms to attempt the provider before failing over to the next available channel.Business Tier

The Routing Property​

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 configuration or routing defined by the template.

methodstringrequired
Can be single or all
channelsarray<string | Routing>required
A list of channels or providers to send the message through. Can also recursively define sub-routing methods, which can be useful for defining advanced push notification delivery strategies.

As an Array of Channel Identifiers​

The simplest option is to specify an array of strings that match the Channel identifies you want to use to send the message.

In this example, courier will send to one of sms, email or inbox depending of user preferences.

"routing": {
  "method": "single",
  "channels": ["sms", "email", "inbox"]
}

Advanced Routing Strategy​

The routing property can be used to define advanced routing scenarios. In this example, we send a push notification to both the user's Apple and Android devices. If sending via push fails, we send an sms instead.

"routing": {
  "method": "single",
  "channels": [
    {
      "method": "all",
      "channels": ["apn", "firebase-fcm"]
    },
    "sms"
  ]
}

Note: Automated failover is a business tier feature.

Was this helpful?