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, etc).

​
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": {
    "brand": "my-brand", // optional brand id
    "data": {}, // global data bag used for all users
    "locale": "en_US", // optional
    "message": {
        "template": "my-notification-or-event",
    }
  }
}

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.

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": [
    {
      "profile": {}, // optional, similar to /send profile object
      "preferences": {}, // optional, similar to preferences API
      "to": {
        "user_id": "spike_spiegel",
        "data": {    // optional, takes precedence over global message data bag
        "recipientName": "Spike Spiegel"
      }
      }
    }
  ]
}

Response with errors:

{
  // gives errors for each user if found
  "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 by calling the /run endpoint with the jobId.

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 individual message from /send requests. Messages are visible on the Courier Logs 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.

How to Use Brands to Customize Email NotificationsHow To Create And Send To A List Or List Pattern