How To Send Bulk Notifications

The Bulk API makes it possible to incrementally build a notification that goes out to a very large number of users and then execute the send with a single API call. While the Send API can be used to deliver messages to multiple recipients, the Bulk API provides more tools to examine the progress of the job as it executes.

Like sending a single message, the Bulk API can used across channels (eg. email, SMS, chat, in-app inbox, push) and providers (eg. Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

Create a Bulk Job

Bulk jobs must first be defined. The structure of a job mimics the set of available configuration values for sending an individual message.

Request:

POST https://api.courier.com/bulk

{
  "message": {
    "event": "my-notification-or-event", // optional if using API v2
    "brand": "my-brand", // optional brand id
    "data": {}, // optional data bag
    "locale": "en_US", // optional
    "override": {} // optional Courier overrides
    "message": {
      // optional API v2 message that supports elemental
    }
  }
}

Note

All bulk endpoints also support idempotent requests using the Idempotency-Key header.

Response:

Status: 201

{
  "jobId": "1-61e9dd53-b5bb6c863b7ffbe83ad4b28d"
}

Ingest Users to the Bulk Job

Using the job ID, multiple users can be ingested into the job.

Note

The ingestion does not have to happen in a single call, you could have multiple ingestion invocations as long as job is not triggered. The bulk job will not expire until it is invoked.

Request:

POST https://api.courier.com/bulk/{jobId}

{
  "users": [
    {
      "recipient": "john-001", // optional, auto-generated if not present
      "profile": {}, // optional, similar to /send profile object
      "data": {
        // optional, takes precendence over message data bag
        "recipientName": "John Doe" // optional
        // additional [key-values] similar to /send data object
      },
      "preferences": {}, // optional, similar to preferences API
      "to": {
        // optional json that represents a user recipient
      }
    }
  ]
}

Response:

Status: 200

{
  // gives errors for each user if found any
  "errors": [
    {
      "error": "Duplicate user",
      "user": {
        "profile": {
          "email": "foo@bar.com"
        },
        "data": {
          "recipientName": "Foo Bar"
        },
        "recipient": "foo-bar"
      }
    }
  ],
  // gives total count of users that were successfully ingested
  "total": 1
}

Executing the Job

Once you have added the users to your job, it can be triggered.

Note

A jobId can only be triggered once. If you wish to send messages to more users after the job was triggered, you'll have to create a new job definition and add the remaining users to the new job.

Request:

POST https://api.courier.com/bulk/{jobId}/run

Response:

Status: 202

Fetching Bulk Job Information

Job Status

The jobId can be used to track the status of the individual messages in the bulk job. You should expect the status as you see in the GET /messages endpoint which includes delivery statistics like sent, delivered, clicked and more.

GET https://api.courier.com/bulk/{jobId}

{
  "job": {
    "definition": {
      "event": "V7E6M48EFQMB78H746QCCD1KSRAA"
    },
    "enqueued": 2, // placed on the pipeline
    "failures": 0, // errors during bulk job processing
    "received": 2, // count of users in a bulk job
    "status": "COMPLETED" // status of the job
  }
}

Job Items/Users

GET https://api.courier.com/bulk/{jobId}/users?cursor={cursor}

{
  "items": [
    {
      "profile": {
        "email": "foo@courier.com"
      },
      "data": {
        "recipientName": "Foo"
      },
      "recipient": "foo",
      "messageId": "1-61e9dd7d-13c08339357603322c433d55", // Courier Message ID
      "status": "ENQUEUED"
    },
    {
      "profile": {
        "email": "bar@courier.com"
      },
      "data": {
        "recipientName": "Bar"
      },
      "recipient": "bar",
      "status": "PENDING"
    }
  ],
  "paging": {
    "cursor": "cursor",
    "more": true
  }
}

Message Information

The messageId from each item is the same as you get from looking up an invidual message from /send. Messages are visible on the Courier UI or can be fetched via Messages API as expected. If you have Outbound Webhooks configured, Courier will invoke it with the message data throughout the lifecycle of the message.