Product

Resources

Start Routing Notifications Today!

Courier is a notification service that centralizes all of your templates and messaging channels in one place which increases visibility and reduces engineering time.

Sign-up

COURIER LIVE

First Look at Notifying Multiple Recipients using Lists

Aydrian Howard

September 30, 2020

Check out the video below to watch us:

Give an overview of the Lists feature
Discuss list organization while creating a couple lists
Subscribe new and existing recipients to a list
Send to a list using the listId and pattern methods
View the List Sends in the Courier Logs

Be sure to Like the video and Subscribe to our YouTube channel.

Using Lists with the Courier Node.js Library

During the stream we used the newly updated Courier Node.js SDK to work with our lists. During this we ran into a few issues and shortly after the stream ended, we released a patch to address them. The following code uses v1.6.1 of the SDK which can be installed using yarn or npm.

1
> npm install @trycourier/courier

Creating a List

A list can be created ahead of time or when a recipient subscribes to a list that doesn't exist. We created a couple lists using both methods. List IDs are composed of up to 4 parts separated by a dot. For our example, we are creating a list for Courier Live Alerts so we'll use courier.devrel.live. You can learn more about List ID Pattern guidelines in our help center.

1
const { CourierClient } = require("@trycourier/courier");
2
const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" });
3

4
const listId = "courier.devrel.live";
5

6
const main = async () => {
7
  await courier.lists.put(listId, {
8
    name: "Weekly Product Updates"
9
  });
10

11
  const list = await courier.lists.get(listId);
12
  console.log(list);
13
};
14

15
main();

Because the list.put method doesn't return anything, I also added a call to the list.get method to show the list had been added.

Subscribing to a List

To add a recipient to a list, you first need to make sure they have a Profile stored in Courier. Here is how you would add a new recipient to a list that will be created on the fly.

1
const { CourierClient } = require("@trycourier/courier");
2
const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" });
3

4
const listId = "courier.product.live";
5

6
const main = async () => {
7
  const { status } = await courier.mergeProfile({
8
    recipientId: "CUSTOMER94107",
9
    profile: {
10
      email: "customer@company.com",
11
      given_name: "Customer",
12
      custom: {
13
        twitter: "https://twitter.com/company"
14
      }
15
    }
16
  });
17

18
  console.log(status);
19

20
  await courier.lists.subscribe(listId, "CUSTOMER94107");
21

22
  const { results } = await courier.lists.findByRecipientId("CUSTOMER94107");
23
  console.table(results);
24
};
25

26
main();

Here we created a new recipient profile using the Profiles API and then subscribed them to a new list. Because the lists.subscribe method doesn't return anything, I also added a call to the list.findByRecipientId method to show that the recipient was added to the newly created list.

Sending to a List

Now that we have a couple lists, we can send a notification to them. We can target a specific list by sending using its List ID

1
const { CourierClient } = require("@trycourier/courier");
2
const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" });
3

4
const listId = "courier.devrel.live";
5

6
const data = {
7
  title:
8
    "Courier Live: First Look at Notifying Multiple Recipients using Lists",
9
  hosts: [
10
    {
11
      name: "Aydrian",
12
      twitter: "https://twitter.com/itsaydrian"
13
    },
14
    {
15
      name: "Danny",
16
      twitter: "https://twitter.com/DannyDouglass"
17
    }
18
  ]
19
};
20

21
const main = async () => {
22
  try {
23
    const { messageId } = await courier.lists.send({
24
      event: "COURIER_LIVE_ALERT",
25
      list: listId,
26
      data
27
    });
28
    console.log(messageId);
29
  } catch (e) {
30
    console.log(e.message);
31
  }
32
};
33

34
main();

We can target multiple lists by using a pattern. We could send to all subscribers under courier by using the pattern courier. or we could target all the live lists with the pattern courier.*.live. You can learn more about patterns in our help center. Let's send to every list under courier.

1
const { CourierClient } = require("@trycourier/courier");
2
const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" });
3

4
const pattern = "courier.**";
5

6
const data = {
7
  title:
8
    "Courier Live: First Look at Notifying Multiple Recipients using Lists",
9
  hosts: [
10
    {
11
      name: "Aydrian",
12
      twitter: "https://twitter.com/itsaydrian"
13
    },
14
    {
15
      name: "Danny",
16
      twitter: "https://twitter.com/DannyDouglass"
17
    }
18
  ]
19
};
20

21
const main = async () => {
22
  try {
23
    const { messageId } = await courier.lists.send({
24
      event: "COURIER_LIVE_ALERT",
25
      pattern,
26
      data
27
    });
28
    console.log(messageId);
29
  } catch (e) {
30
    console.log(e.message);
31
  }
32
};
33

34
main();

Courier will handle gathering and de-duping all the recipients that satisfy the pattern. Check out the Lists API Reference documentation to learn about all that can be done with lists.

Is there something you’d like to see us do using Courier? Let us know and it might be the subject of our next Courier Live. We stream a new Courier Live every Wednesday at noon Pacific. Follow us on Twitch to be notified when we go live.

-Aydrian

Start Routing Notifications Today!

Courier is a notification service that centralizes all of your templates and messaging channels in one place which increases visibility and reduces engineering time.

Sign-up

More from Courier Live

April 2021 Courier Live Release Notes Thumbnail

COURIER LIVENEWS & UPDATES

Courier April Product Release Updates: In-app Inbox, Preferences, and Automations

In this update, Aydrian and Nate (Head of Customer Success) as cohosts cover what is new with the in-app notifications API, our new preferences component, and our automations API, which is now GA.

Aydrian Howard

May 20, 2021

COURIER LIVE

Content, Notifications, and IoT

On February 2nd and 3rd, Shy Ruparel joined Aydrian for another Courier and Contentful crossover stream. This time, they decided to play around with an IoT E-ink display and use it to show the latest posts from Contentful and send notifications using Courier.

Aydrian Howard

February 10, 2021

Build your first notification in minutes

Send up to 10,000 notifications every month, for free.

Get started for free

Build your first notification in minutes

Send up to 10,000 notifications every month, for free.

Get started for free

Product

Pricing

Providers

Developers

Documentation

API

Libraries

Status

Resources

Help Center

Podcasts

Error Solutions

Product Updates

Free Tools

Company

Blog

About

Careers

Security

Terms

Privacy

Responsible Disclosure

Subprocessors