@trycourier/courier

This is the official node.js module for sending notifications with node.js with the Courier REST API.

Courier docs • 3 Different Ways To Send Emails With Node.js

Installation (via npm)

npm install @trycourier/courier

Requirements

You will need to get a Courier API key to get started. You can sign up and create one for free at courier.com.

Upgrade Guides

v5 to v6

v6 of our SDK is automatically generated by Fern. v6 comes with several improvements that we describe below:

• Resource-scoped SDK methods: Endpoints are scoped under their resource. For example, instead of courier.deleteBrands the SDK now reads courier.brands.delete(...)
• Docs on Hover: All endpoint and parameter level documentation that you see on our docs website is now embedded directly within the SDKs.
• Retries with exponential backoff: The SDK will automatically retry failures with exponential backoff. You can configure the retries by setting maxRetries.

  const response = courier.send(..., {
    maxReries: 0 // set to 0 if you want to disable retries
  })
  

• Configurable Timeouts: The SDK defaults to a 60 second timeout. You can also configure this value per-request.

  const response = courier.send(..., {
    timeoutInSeconds: 45 // set to 45 seconds for this particular request
  })
  

• Support for multiple runtimes: The SDK uses global fetch when available, otherwise defaults to node-fetch. This means you can use Courier in multiple runtimes; Node.js, Vercel, and Cloudflare Workers.

v3 to v4

v4 uses native fetch client to make requests or falls back to a polyfill if the client doesn't exist in the environment it's running in. Check Error Handling out.

Getting Started

import { CourierClient } from "@trycourier/courier";

const courier = new CourierClient({ authorizationToken: "<AUTH_TOKEN>" }); // get from the Courier UI

// Example: send a basic message to an email recipient
const { requestId } = await courier.send({
  message: {
    to: {
      data: {
        name: "Marty",
      },
      email: "[e-mail]",
    },
    content: {
      title: "Back to the Future",
      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
    },
    routing: {
      method: "single",
      channels: ["email"],
    },
  },
});

// Example: send a basic message to an sms recipient
const { requestId } = await courier.send({
  message: {
    to: {
      data: {
        name: "Jenny",
      },
      phone_number: "8675309",
    },
    content: {
      title: "Back to the Future",
      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
    },
    routing: {
      method: "single",
      channels: ["sms"],
    },
  },
});

// Example: send a message to various recipients
const { requestId } = await courier.send({
  message: {
    to: [
      {
        user_id: "<USER_ID>", // usually your system's User ID associated to a Courier profile
        email: "[e-mail]",
        data: {
          name: "some user's name",
        },
      },
      {
        email: "[e-mail]",
        data: {
          name: "Marty",
        },
      },
      {
        email: "[e-mail]",
        data: {
          name: "Doc",
        },
      },
      {
        phone_number: "8675309",
        data: {
          name: "Jenny",
        },
      },
    ],
    content: {
      title: "Back to the Future",
      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
    },
    routing: {
      method: "all",
      channels: ["sms", "email"],
    },
  },
});

// Example: send a message supporting email & SMS
const { requestId } = await courier.send({
  message: {
    template: "<TEMPLATE_OR_EVENT_ID>", // get from the Courier UI
    to: {
      user_Id: "<USER_ID>", // usually your system's User ID
      email: "[e-mail]",
      phone_number: "555-228-3890",
    },
    data: {}, // optional variables for merging into templates
  },
});

// Example: send a message to a list
const { requestId } = await courier.send({
  message: {
    template: "<TEMPLATE_OR_EVENT_ID>", // get from the Courier UI
    to: {
      list_id: "<LIST_ID>", // e.g. your Courier List Id
    },
    data: {}, // optional variables for merging into templates
  },
});

// Example: send a message to a pattern
const { requestId } = await courier.send({
  message: {
    template: "<TEMPLATE_OR_EVENT_ID>", // get from the Courier UI
    to: {
      list_pattern: "<PATTERN>", // e.g. example.list.*
    },
    data: {}, // optional variables for merging into templates
  },
});

// Example: send a message to a list, pattern and user
const { requestId } = await courier.send({
  message: {
    content: {
      title: "Hello",
      body: "Good morning!"
    },
    to: [
      {
        list_pattern: "<PATTERN>", // e.g. example.list.*
      },
      {
        list_id: "<LIST_ID>", // e.g. your Courier List Id
      },
      {
        email: "[e-mail]"
      }
    ]
  },
  routing: {
    method: "single",
    channels: ["email"],
  },
});

// Example: send a basic message that expires after the specified timeout
const { requestId } = await courier.send({
  message: {
    to: {
      data: {
        name: "Marty",
      },
      email: "[e-mail]",
    },
    content: {
      title: "Back to the Future",
      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
    },
    routing: {
      method: "single",
      channels: ["email"],
    },
    timeout: {
      message: 3600000 // 1 hour in milliseconds
    },
  },
});

// Example: send a basic message with a trace id
const { requestId } = await courier.send({
  message: {
    to: {
      data: {
        name: "Marty",
      },
      email: "[e-mail]",
    },
    content: {
      title: "Back to the Future",
      body: "Oh my {{name}}, we need 1.21 Gigawatts!",
    },
    routing: {
      method: "single",
      channels: ["email"],
    },
    metadata: {
      trace_id: "ravenclaw-for-the-win"
    },
  },
});

Environment Variables

courier-node supports credential storage in environment variables. If no authorizationToken is provided when instantiating the Courier client (e.g., const courier = CourierClient();), the value in the COURIER_AUTH_TOKEN env var will be used.

If you need to use a base url other than the default https://api.courier.com, you can set it using the COURIER_BASE_URL env var.

Advanced Usage

const { CourierClient } = require("@trycourier/courier");

const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" });

async function run() {
  // Example: send a message
  const { requestId } = await courier.send({
    message: {
      template: "<TEMPLATE_OR_EVENT_ID>",
      to: {
        // optional
        user_id: "<RECIPIENT_ID>",
      },
      data: {}, // optional
      brand_id: "<BRAND_ID>", //optional
      channels: {}, // optional
      providers: {}, // optional
    },
  });
  console.log(requestId);

  // Example: send message with utm metadata
  const { requestId } = await courier.send({
    message: {
      template: "<TEMPLATE_OR_EVENT_ID>",
      to: {...},
      routing: {
        method: "single",
        channels: ["email"],
      },
      channels: {
        email: {
          routing_method: "all",
          providers: ["sendgrid", "sns"],
          metadata: {
            utm: {
              medium: "f",
              campaign: "g",
            },
          },
        },
      },
      providers: {
        sns: {
          metadata: {
            utm: {
              medium: "h",
            },
          },
        },
      }, // optional
      metadata: {
        utm: {
          source: "a",
          medium: "b",
          campaign: "c",
        },
      },
      timeout: {
        message: 300000,
        channel: {
          email: 1000 // 1 second
        }
      }
    },
  });

/**
 * If the template or content contains any action blocks, the hyperlinks will be augmented with utm compliant query parameters.
 *
 * The resulting link of an action block sent through sendgrid would be:
 * www.example.com?utm_source=a&utm_medium=f&utm_campaign=g
 *
 * While the resulting link of an action block sent through sns would be:
 * www.example.com?utm_source=a&utm_medium=h&utm_campaign=g
 *
 * Notice that provider metadata supersedes channel metadata and channel metadata supersedes message metadata
 *
 **/

/**
 * If the message includes a timeout property we will start timing out messages after the first attempt.
 * We are able to timeout complete channels or specific providers.
 **/

  // Example: get a message status
  const messageStatus = await courier.messages.get(requestId);
  console.log(messageStatus);

  // Example: get a message history
  const { results } = await courier.messages.getHistory(requestId);
  console.log(results);

  // Example: get a message output
  const { results } = await courier.messages.getContent(requestId);
  console.log(results);

  // Example: get all messages
  const { paging, results } = await courier.messages.list();
  console.log(results);

  // Example: replace a recipient's profile
  const { status: replaceStatus } = await courier.profiles.replace(
    "<RECIPIENT_ID>",
    {
      profile: {
        email: "[e-mail]",
      },
    }
  );
  console.log(replaceStatus);

  // Example: merge into a recipient's profile
  const { status: mergeStatus } = await courier.profiles.create(
    "<RECIPIENT_ID>",
    {
      profile: {
        sms: "555-555-5555",
      },
    }
  );
  console.log(mergeStatus);

  // Example: get a recipient's profile
  const { profile } = await courier.profiles.get("<RECIPIENT_ID>");
  console.log(profile);

  // Example: get all brands
  const { paging, results } = await courier.brands.list({
    cursor: "<CURSOR>", // optional
  });
  console.log(results);

  // Example: get a specific brand
  const brand = await courier.brands.get("<BRAND_ID>");
  console.log(brand);

  // Example: create a brand
  const newBrand = await courier.brands.create({
    name: "My Brand",
    settings: {
      colors: {
        primary: "#0000FF",
        secondary: "#FF0000",
        tertiary: "#00FF00",
      },
    },
  });
  console.log(newBrand);

  // Example: replace a brand
  const replacedBrand = await courier.brands.replace("<BRAND_ID>", {
    name: "My New Brand",
    settings: {
      colors: {
        primary: "#FF0000",
        secondary: "#00FF00",
        tertiary: "#0000FF",
      },
    },
  });
  console.log(replacedBrand);

  // Example: delete a brand
  await courier.brands.delete("<BRAND_ID>");

  // Example: get all lists
  const { paging, items } = await courier.lists.list({
    cursor: "<CURSOR>", // optional
  });
  console.log(items);

  // Example: get a specific list
  const list = await courier.lists.get("<LIST_ID>");
  console.log(list);

  // Example: create or replace a list
  const replacedList = await courier.lists.update("<LIST_ID>", {
    name: "My New List",
  });
  console.log(replacedList);

  // Example: delete a list
  await courier.lists.delete("<LIST_ID>");

  // Example: restore a list
  await courier.lists.restore("<LIST_ID>");

  // Example: get a list's subscribers
  const { paging, items } = await courier.lists.getSubscribers("<LIST_ID>");
  console.log(items);

  // Example: replace many recipients to a new or existing list
  await courier.lists.updateSubscribers("<LIST_ID>", [
    { recipientId: "RECIPIENT_ID_1" },
    { recipientId: "RECIPIENT_ID_2" },
  ]);

  // Example: subscribe single recipient to a new or existing list
  await courier.lists.subscribe("<LIST_ID>", "<RECIPIENT_ID>");
  console.log(recipient);

  // Example: unsubscribe recipient from list
  await courier.lists.unsubscribe("<LIST_ID>", "<RECIPIENT_ID>");

  // Example: get a recipient's subscribed lists
  const { paging, items } = await courier.lists.getSubscribers(
    "<RECIPIENT_ID>"
  );
  console.log(items);

  // Example: Automation Ad-Hoc Invoke
  const { runId } = await courier.automations.invokeAdHocAutomation({
    automation: {
      cancelation_token: "I_AM_TOKEN",
      steps: [
        {
          action: "send",
        },
      ],
    },
    brand: "BRAND_ID",
    data: {
      example: "EXAMPLE_DATA",
    },
    profile: {
      email: "[e-mail]",
    },
    recipient: "RECIPIENT_ID",
    template: "TEMPLATE_NAME_OR_ID",
  });
  console.log(runId);

  // Example: Automation Invoke Template
  const { runId } = await courier.automations.invokeAutomationTemplate(
    "AUTOMATION_TEMPLATE_ID",
    {
      brand: "BRAND_ID",
      data: {
        example: "EXAMPLE_DATA",
      },
      profile: {
        email: "[e-mail]",
      },
      recipient: "RECIPIENT_ID",
      template: "TEMPLATE_NAME_OR_ID",
    }
  );
  console.log(runId);

  // Example: List notifications
  const { paging, results } = await courier.notifications.list();
  console.log(results);

  // Example: Get notification content
  const { blocks, channels } = await courier.notifications.getContent(
    "notification1"
  );
  console.log(blocks);
  console.log(channels);

  // Example: Get notification draft content
  const { blocks, channels } = await courier.notifications.getDraftContent(
    "notification1"
  );
  console.log(blocks);
  console.log(channels);

  // Example: Post notification variations
  await courier.notifications.updateVariations("notification1", {
    blocks: [
      {
        id: "block_1d4c32e0-bca8-43f6-b5d5-8c043199bce6",
        type: "text",
        locales: {
          fr_FR: "block fr 1",
        },
      },
      {
        id: "block_6d50a6e3-ecc3-4815-bf51-0202c6bf54e2",
        type: "text",
        locales: {
          fr_FR: "block fr 2",
        },
      },
    ],
    channels: [
      {
        id: "channel_1ba46024-f156-4ed7-893b-cb1cdcfbd36e",
        type: "email",
        locales: {
          fr_FR: {
            subject: "French Subject",
          },
        },
      },
      {
        id: "channel_2c2aad1c-30f0-4a55-8d8f-d213f32147bc",
        type: "push",
        locales: {
          fr_FR: {
            title: "French Title",
          },
        },
      },
    ],
  });

  // Example: Post notification draft variations
  await courier.notifications.updateDraftVariations("notification1", {
    blocks: [
      {
        id: "block_1d4c32e0-bca8-43f6-b5d5-8c043199bce6",
        type: "text",
        locales: {
          fr_FR: "block fr 1",
        },
      },
      {
        id: "block_6d50a6e3-ecc3-4815-bf51-0202c6bf54e2",
        type: "text",
        locales: {
          fr_FR: "block fr 2",
        },
      },
    ],
    channels: [
      {
        id: "channel_1ba46024-f156-4ed7-893b-cb1cdcfbd36e",
        type: "email",
        locales: {
          fr_FR: {
            subject: "French Subject",
          },
        },
      },
      {
        id: "channel_2c2aad1c-30f0-4a55-8d8f-d213f32147bc",
        type: "push",
        locales: {
          fr_FR: {
            title: "French Title",
          },
        },
      },
    ],
  });

  // Example: Get notification submission checks
  const { checks } = await courier.notifications.getSubmissionChecks(
    "notification1",
    "submission1"
  );
  console.log(checks);

  // Example: Put notification submission checks
  const { checks } = await courier.notifications.replaceSubmissionChecks(
    "notification1",
    "submission1",
    {
      checks: [
        {
          id: "check1",
          status: "RESOLVED",
          type: "custom",
        },
      ],
    }
  );
  console.log(checks);

  // Example: Cancel notification submission
  await courier.notifications.cancelSubmission("notification1", "submission1");

  // Bulk Processing
  // Example: create a job (API v1 semantics)
  const response = await courier.bulk.createJob({
    message: {
      event: "RR4NDQ7NZ24A8TKPWVBEDGE15E9A",
    },
  });
  console.log(response);

  // Example: create a job (API v2 semantics)
  const response = await courier.bulk.createJob({
    message: {
      message: {
        template: "RR4NDQ7NZ24A8TKPWVBEDGE15E9A",
      },
    },
  });
  console.log(response);

  // Example: get a job
  const response = await courier.bulk.getJob({
    jobId: "1-61efe386-6ff57552409e311b7a1f371f",
  });
  console.log(response);

  // Example: Ingest users in a job (API v1 semantics)
  const response = await courier.bulk.ingestUsers({
    jobId: "1-61efe386-6ff57552409e311b7a1f371f",
    users: [
      {
        profile: {
          email: "[e-mail]",
        },
      },
    ],
  });
  console.log(response);

  // Example: Ingest users in a job (API v2 semantics)
  const response = await courier.bulk.ingestUsers({
    jobId: "1-61efe386-6ff57552409e311b7a1f371f",
    users: [
      {
        to: {
          email: "[e-mail]",
        },
      },
    ],
  });
  console.log(response);

  // Example: Run a job
  await courier.bulk.runJob("1-61efe386-6ff57552409e311b7a1f371f");

  // Example: Get user details in a job
  const response = await courier.bulk.getUsers(
    "1-61efe386-6ff57552409e311b7a1f371f"
  );
  console.log(response);
}

run();

Error Handling

This package tries to use the native fetch client to make requests or falls back to a polyfill if the client doesn't exist in the environment it's running in.

All network related promise rejections are not handled in any way. All successfully made requests that produce errors on the server side are resulting in promise rejections with custom CourierHttpClientError error type.

CourierHttpClientError extends native Error interface with two extra properties:

• response: this is the fetch response as is
• data: this is the parsed body of the response

// Error handling example
import { CourierError, CourierClient } from "@trycourier/courier";

const courier = new CourierClient();

try {
  await courier.send(/* ... */);
} catch (error) {
  if (error instanceof CourierError) {
    console.log("Failed to send with status code:", error.statusCode);
    console.log("The Courier response is:", error.data);
    console.log("The error message is:", error.message);
  } else {
    console.log(
      "There was a problem making that request. Make sure you are online."
    );
  }
}

Idempotency

For POST methods, you can supply an idempotencyKey in the config parameter to ensure the idempotency of the API Call. We recommend that you use a V4 UUID for the key. Keys are eligible to be removed from the system after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been removed. For more info, see Idempotent Requests in the Courier documentation.

import { CourierClient } from "@trycourier/courier";
import uuid4 from "uuid4";

const courier = new CourierClient();
const idempotencyKey = uuid4();

async function run() {
  const { requestId } = await courier.send(
    {
      template: "<TEMPLATE_OR_EVENT_ID>",
      to: {
        user_id: "<USER_ID>",
        email: "[e-mail]",
        phone_number: "555-867-5309",
      },
      data: {
        world: "JavaScript!",
      },
    },
    {
      idempotencyKey,
    }
  );
  console.log(requestId);
}

run();

Audiences

Audiences APIs are used to create, get, update, and delete audiences. A Courier Audience is a dynamic group of users (created using Courier's Profile API) that matches a set of criteria. Audience is reactive to changes in the user's profile. As you change user profile using profiles API, the audience will be updated accordingly. You will not have to maintain a list of users in your audience. Courier takes care of that for you. If you have potentially large set of users, you first create an audience and then use the audience's id to retrieve the list of users. Once you satified with the calculated list of users, you can use the audienceId to send notification using send API.

// Example: create audience which would allow sending notification to all users that match the given filter criteria
const { audienceId } = await courier.audiences.put({
  id: "<AUDIENCE_ID>",
  filter: {
    operator: "EQ",
    path: "title",
    value: "Software Engineer",
  },
});

// To retrieve list of members in a given audience, you can use the following:
const { items: audienceMembers } = await courier.audiences.listMembers(
  audienceId
  cursor: "<CURSOR>", // optional
);

// To send a notification to all users that match the given filter criteria, you can use the following:
const { requestId } = await courier.send({
  message: {
    template: "<TEMPLATE_OR_EVENT_ID>", // This can be inline content as well
    to: {
      audience_id: audienceId,
    },
    data: {}, // optional
    brand_id: "<BRAND_ID>", //optional
    routing: {},
    channels: {}, // optional
    providers: {}, // optional
  },
});

Tenants

The Tenants API is designed to enable multi-tenant notification workflows. This is useful for defining user to tenant level relationships, especially in the context of B2B applications.

Use Cases:

• Sending branded notifications on behalf of an organization
• Creating slack-bots on behalf of an organization

Creating a Tenant

const { id } = await courier.tenants.createOrReplace("<TENANT_ID>", {
  name: "Courier",
  user_profile: {
    slack: {
      access_token: "<SLACK_ACCESS_TOKEN_SCOPED_TO_THE_TENANT>",
    },
  },
});

Retrieving a Tenant

const tenant = await courier.tenants.get("<TENANT_ID>");

Deleting a Tenant

await courier.tenants.delete("<TENANT_ID>");

Listing Tenants

const { items: tenants, has_more } = await courier.tenants.list();

Updating user preferences

Courier currently does not allow creating new topics via the API. You must create topics via the Courier UI. Once a topic is created, you can update a user's preferences for that topic via the API.

  await courier.users.preferences.update("<USER_ID>", "<VALID_TOPIC_ID>", {
    default_status: "OPTED_IN",
    status: "OPTED_OUT",
  });

Getting user preferences

• Get all topic level preferences for a user

  const { items: userPreferences } = await courier.users.preferences.list(
    "<USER_ID>"
  );

• Get a specific topic level preference for a user

  const userPreference = await courier.users.preferences.get(
    "<USER_ID>",
    "<VALID_TOPIC_ID>"
  );

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!

License

MIT License

Author

Courier ([e-mail])