​
Automation Schema

It’s possible to define an Automation Schema in two ways:

  1. Ad-Hoc
  2. Automation template

​
Ad-Hoc Automations

Ad-hoc automations are one-time schema definitions that allow run context to be defined in the schema itself:

{
  "automation": {
    "recipient": "abcd-1234-wxyz-6789",
    "data": {
      "title": "Weekly Digest"
    }
      "steps": [
      {
        "action": "fetch-data",
        "webhook": {
          "url": "https://main.app/digest"
        },
        "merge_strategy": "replace"
      },
      {
        "action": "send",
        "template": "WEEKLY-DIGEST",
        "profile": {
          "email": "test@courier.com"
        }
      }
    ]
  }
}

​
Automation Templates

AUTOMATION TEMPLATE VISUAL DESIGNER

An automation template is a re-usable, pre-defined list of automation steps created in the automation design studio.

Published templates are run or “invoked” using the Courier Automation API automations/:templateId/invoke endpoint.

By default, an automation template is a JSON schema definition of the following format:

{
  "cancelation_token": "",
  "steps": []
}

Run context is passed in the API request body as a first-class object, and its values are referenced at the step level by using Accessor Types.

Structure

// define global variables here
{
  sources: ["<EVENT_NAME>"], // list of event source that this
  template can be triggered by
  steps: [], // a list of automation steps
}

At runtime, you can pass a data and/or profile property into your template.

//1.define the template to send to a list of users
local list=data('users', []);
{
  steps: [
    {
      action: "send",
      profile: {
        email: email
      },
      recipient: item.userId,

    }
    for item in list
  for email in item.email
  ]
}

//2.make the api call and provide the user list

{
  event: "SEND-TO-USERS",
  user: "abc-123",
  //defaultrecipientdata: {
    users: [
      {
        userId: "123-abc-123",
        email: [
          'user1@gmail.com',
          'user1_altl@gmail.com'
        ]
      },
      {
        userId: "abc-123-abc",
        email: [
          'user2@yahoo.com'
        ]
      },

    ]
  }
}

​
Invoking Automations

To trigger an automation run, there are two apis that can be called with your Courier API token.

  • automations/invoke
  • automations/{templateId}/invoke

​
Invoke An Ad-Hoc Automation Via API

POST - /automations/invoke

Invoke an ad hoc automation run, by providing a valid automation definition in the request body.

Structure

{
  "brand": "<BRAND_ID>", // optional: brand id
  "template": "<TEMPLATE_NAME_OR_ID>", //optional
  "recipient": "<RECIPIENT_ID>", //optional: user id for automation
  "data": {}, //optional: root level data for the ad hoc automation
  "profile": {},
  //optional root level profile information for ad hoc
  "automation": {
    "cancelationToken": "<CANCELATION_TOKEN>",
    //optional: can be used to later cancel the running automation
    "steps": [
      {
        "action": "send",
        "data": {}, //optional: uses root level data if not present
        "profile": {},
        //optional: uses root level profile if not present
        "recipient": "<RECIPIENT_ID>",
        //recipient of the message. will fallback to root recipient
        "template": "<TEMPLATE_ID>",
        //the notification template to use,
        "brand": "<BRAND_ID>",
        //optional: will use root level brand_id if not present
        "override": {}, //optional: send provider override
        "if": "<CONDITIONAL_EXPRESSION>"
        //optional javascript boolean expression
        //see send step documtenation above for more details
      },
      {
        "action": "delay"
        //either duration or until is required
        //see delay step documentation above for more details
      },
      {
        "action": "cancel",
        "cancelationToken": "<CANCELATION_TOKEN>",
        "if": "<CONDITIONAL_EXPRESSION>"
        //optional javascript boolean expression
        //see cancel step documentation above for more details
      }
    ]
  }
}

​
Invoke an Automation Template Via API

POST - /automations/{templateId}/invoke

Structure

{
  "template": "<TEMPLATE_NAME_OR_ID>",
   // optional: the automation template name
  "recipient": "<RECIPIENT_ID>",
   // optional: recipient id for the automation run
  "data": {}
   // optional: root level data to be passed into automation template
  "profile": {}
   // optional: root level profile information to be passed into your automation template
}

​
Invoke a Template Via Segment

You can trigger an automation template via Segment event in the Automations Visual Designer.

INTEGRATE SEGMENT

You can follow Courier’s Segment integration guide here.

Once you have fished setting up Courier’s Segment Integration

  1. Open the Automation you wish to trigger via Segment event
  2. Click to open the Start step
  3. Select the segment event type(s) you want to trigger this event.

TRACK EVENT REQUIRES AN EXACT NAME MATCH

If you select a Segment Track event trigger to invoke your template, you must provide an event name that is the exact match to the event’s name in Segment.

​
Automation Examples

​
Sending a Digest Notification

Use automations to fetch data and render it in a group digest or send a digest with recipient-specific data to every member of a list.

​
Generic Digest

A generic digest is when every recipient in the list receives the same notification with the same data. To automate a generic digest, simply define a fetch-data step, followed by a send-list step. The data that is fetched, will be used to render a notification that is sent to each recipient.

This automation definition can be saved as an automation template and scheduled to be invoked on any recurring interval or once on a specific date.

{
  "automation": {
    "steps": [
      {
        "action": "fetch-data",
        "webhook": {
          "url": "https://main.app/digest"
        },
        "merge_strategy": "replace"
      },
      {
        "action": "send-list",
        "list": "TEAM-LIST",
        "template": "WEEKLY-GENERIC-DIGEST"
      }
    ]
  }
}

​
Recipient Digest

A recipient digest is when every recipient in the list receives a unique notification with recipient-specific data.

To automate a recipient digest, define a send-list step with a data_source property. Specific data will be fetched for each recipient and will be used to render a notification that is sent to each recipient. Note that the data_source.url should accept a recipientId query string parameter.

This automation definition can be saved as a template and scheduled to be invoked on any recurring interval or once on a specific date.

{
  "automation": {
    "steps": [
      {
        "action": "send-list",
        "list": "TEAM-LIST",
        "template": "WEEKLY-RECIPIENT-DIGEST",
        "data_source": {
          "webhook": {
            "url": "https://main.app/digest",
            "method": "GET"
          },
          "merge_strategy": "replace"
        }
      }
    ]
  }
}

​
Example Recipient Digest

As an example, you could use the recipient digest to send a weekly update to students of an online school platform.

By calling the data source, and getting the following payload:

{
  "data": {
    "title": "Weekly Progress Report",
    "username": "Count von Count",
    "school": "B.Birds's Online Math Academy",
    "nums": 1,
    "courses": [
      {
        "name": "Counting",
        "progress": "90%",
        "grade": "A+"
      }
    ]
  },
  "profile": {},
  "override": {}
}

You could send the following notification with each individual student’s progress:

Recipient digest notification template example.

Preview of the recipient digest template.

​
Batch Send to an Ad-Hoc List of Recipients

How to use Courier automations to batch send notifications to an ad hoc group of multiple recipients built at run time.

Automations allow you to use the send action to deliver a message, or series of messages, to a list of users that you build dynamically at run time with a single Automation API call.

Data for each message can vary per step. This includes data, profile, and the template.

Here is an example:

// POST /automations/invoke
{
  "automation": {
    "steps": [
      {
        "action": "send",
        "data": {},
        "profile": {},
        "recipient": "<RECIPIENT_ID_1>",
        "template": "<TEMPLATE_ID_1>"
      },
      {
        "action": "send",
        "data": {},
        "profile": {},
        "recipient": "RECIPIENT_ID_2",
        "template": "TEMPLATE_ID_2"
      }
      // ... more send events
    ]
  }
}
How to Understand Automation ConceptsHow To Send Notifications With Segment