How To Send Bulk Notifications

The Bulk API lets you incrementally build a notification job for a large number of users and then execute it with a single API call. While the Send API can deliver messages to multiple recipients, the Bulk API gives you more control over ingestion and lets you track progress as the job runs. That control matters most when something goes wrong. Nothing sends until you run the job, so an ingestion that fails halfway delivers nothing at all. You never run it, and build a fresh job instead. Looping over Send API calls has no equivalent safety net, because whatever already went out has gone out. Like sending a single message, the Bulk API works across channels (email, SMS, chat, in-app inbox, push) and providers (Twilio, SendGrid, etc).

Prerequisites

A Courier account with an API key
A published notification, plus its notification ID or a custom event ID mapped to it
User IDs or profile data for the recipients you want to reach

How A Bulk Job Works

A job moves through three phases:

Create the job with the notification you want to send and any data shared by every recipient.
Ingest recipients into it, across as many calls as you need.
Run it once, then poll for progress.

Ingestion is open-ended and the job won’t expire while you’re filling it. Running is a one-way door, so get everyone in before you trigger it.

Sending A Bulk Job

Create the job

Define the job with an event and any global data that applies to everyone. The event is required, and it’s either a notification ID like FRH3QXM9E34W4RKP7MRC8NZ1T8V8 or a custom event ID like welcome-email that’s mapped to a notification.

curl -X POST https://api.courier.com/bulk \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "event": "YOUR_EVENT_ID",
      "data": {
        "company_name": "Acme Corp"
      }
    }
  }'

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "YOUR_AUTH_TOKEN" });

const { jobId } = await client.bulk.createJob({
  message: {
    event: "YOUR_EVENT_ID",
    data: {
      company_name: "Acme Corp",
    },
  },
});

console.log("Job created:", jobId);

from courier import Courier

client = Courier(api_key="YOUR_AUTH_TOKEN")

response = client.bulk.create_job(
    message={
        "event": "YOUR_EVENT_ID",
        "data": {
            "company_name": "Acme Corp",
        },
    }
)

print("Job created:", response.job_id)

Returns 201 Created with the job ID you’ll use for every call that follows:

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

You can also pass brand, locale, and override. To send something other than the notification attached to the event, add template (a notification ID) or content (Elemental content). Either way, event stays required.

Retrying with the same Idempotency-Key header replays the original result instead of repeating the work. A repeated create returns the first jobId rather than opening a second job.

Ingest your recipients

Add recipients with the job ID. Identify each one in to, and put their personal variables in data, which gets merged into the job’s global message.data.

curl -X POST https://api.courier.com/bulk/JOB_ID \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "to": { "user_id": "avery_diaz" },
        "profile": { "email": "avery@example.com" },
        "data": { "recipientName": "Avery Diaz" }
      },
      {
        "to": { "user_id": "jordan_lee" },
        "profile": { "email": "jordan@example.com" },
        "data": { "recipientName": "Jordan Lee" }
      }
    ]
  }'

await client.bulk.addUsers("JOB_ID", {
  users: [
    {
      to: { user_id: "avery_diaz" },
      profile: { email: "avery@example.com" },
      data: { recipientName: "Avery Diaz" },
    },
    {
      to: { user_id: "jordan_lee" },
      profile: { email: "jordan@example.com" },
      data: { recipientName: "Jordan Lee" },
    },
  ],
});

client.bulk.add_users(
    job_id="JOB_ID",
    users=[
        {
            "to": {"user_id": "avery_diaz"},
            "profile": {"email": "avery@example.com"},
            "data": {"recipientName": "Avery Diaz"},
        },
        {
            "to": {"user_id": "jordan_lee"},
            "profile": {"email": "jordan@example.com"},
            "data": {"recipientName": "Jordan Lee"},
        },
    ],
)

Returns 200 OK, where total is the running count for the whole job rather than the current call:

{
  "errors": [],
  "total": 2
}

Email jobs need each address in profile.email. Provider routing ignores to.email, so a job built without profile.email runs clean and delivers nothing.

Each recipient accepts these fields:

Field	Description
`to.user_id`	Courier user ID for the recipient
`profile`	Inline profile data, such as email address and phone number
`data`	Per-recipient variables, merged into the job’s global `message.data`
`preferences`	Per-recipient preference overrides

Call this endpoint as often as you need, keeping each batch to around 1000 recipients. Larger batches can fail with a 502 instead of a validation error, so split big lists across several calls.

Ingestion doesn’t deduplicate. The same user_id sent twice becomes two entries and two messages, so clean your list before you ingest it.

Run the job

Once everyone’s in, trigger the send. Courier fans out and delivers to each recipient individually.

curl -X POST https://api.courier.com/bulk/JOB_ID/run \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

await client.bulk.runJob("JOB_ID");

client.bulk.run_job(job_id="JOB_ID")

Returns 202 Accepted with an empty body, and the job starts processing in the background.

A job runs once. A second attempt returns 400 BulkJobDuplicateInvocationError, so reaching more recipients means creating a new job.

Track progress

Poll the job for counts and overall status.

curl https://api.courier.com/bulk/JOB_ID \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

const { job } = await client.bulk.retrieveJob("JOB_ID");

console.log(job.status, `${job.enqueued}/${job.received} enqueued`);

response = client.bulk.retrieve_job(job_id="JOB_ID")

print(response.job.status, response.job.enqueued, response.job.received)

{
  "job": {
    "definition": {
      "event": "V7E6M48EFQMB78H746QCCD1KSRAA"
    },
    "enqueued": 2,
    "failures": 0,
    "received": 2,
    "status": "COMPLETED"
  }
}

Field	Description
`received`	Recipients ingested into the job
`enqueued`	Messages placed on the delivery pipeline
`failures`	Errors hit while processing the job
`status`	`CREATED`, `PROCESSING`, `COMPLETED`, or `ERROR`

COMPLETED and ERROR are both terminal. Watch for either, or a failed job leaves you polling forever.

For per-recipient detail, page through the job’s users. Each entry echoes back the to, profile, and data you ingested. Leave cursor off the first request, then keep passing paging.cursor back while paging.more is true.

# First page
curl "https://api.courier.com/bulk/JOB_ID/users" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

# Next page, using paging.cursor from the response above
curl "https://api.courier.com/bulk/JOB_ID/users?cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

let cursor = null;

while (true) {
  const page = await client.bulk.listUsers("JOB_ID", { cursor });

  for (const item of page.items) {
    console.log(item.recipient, item.status, item.messageId);
  }

  if (!page.paging.more) break;

  cursor = page.paging.cursor;
}

cursor = None

while True:
    page = client.bulk.list_users(job_id="JOB_ID", cursor=cursor)

    for item in page.items:
        print(item.recipient, item.status, item.message_id)

    if not page.paging.more:
        break

    cursor = page.paging.cursor

{
  "items": [
    {
      "to": { "user_id": "avery_diaz" },
      "data": { "recipientName": "Avery Diaz" },
      "recipient": "CwrT6W8Wqyl_rroWc-qw8",
      "status": "ENQUEUED",
      "messageId": "1-61e9dd7d-13c08339357603322c433d55"
    },
    {
      "to": { "user_id": "jordan_lee" },
      "data": { "recipientName": "Jordan Lee" },
      "recipient": "U6pQX_IydGJF8fs3wsgk3",
      "status": "PENDING"
    }
  ],
  "paging": {
    "cursor": null,
    "more": false
  }
}

Field	Description
`recipient`	Courier’s ID for this entry in the job, which isn’t your `user_id`
`status`	`PENDING`, `ENQUEUED`, or `ERROR`
`messageId`	Appears once the entry is enqueued

A messageId is the same ID a regular send returns, so you can look one up in the Message Logs or through the Messages API.If you’d rather not poll at all, configure Outbound Webhooks and handle message:updated. It fires on every status change for every message the job produced, which saves you walking the user list to find out what happened.

Troubleshooting

Symptom	Cause	Fix
Job completes, no email arrives	Address was in `to.email`	Move it to `profile.email`
`400 The 'event' parameter is required`	Create body has no `event`	Add a notification ID or event ID
`400 BulkJobDuplicateInvocationError`	Job already ran	Create a new job for more recipients
`502` on ingest	Batch too large	Send around 1000 recipients per call
Status never reaches `COMPLETED`	Job ended in `ERROR`	Treat `ERROR` as terminal too
Someone got the same notification twice	Ingested twice	Deduplicate before ingesting

Next Steps

Bulk API reference

Full request and response detail for all five bulk endpoints.

Send to a list

Reach a saved audience without ingesting recipients yourself.

Message logs

Track delivery for the messages a job produced.

User profiles

Store contact data so you don’t send it with every job.

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

How To Send Bulk Notifications

Prerequisites

How A Bulk Job Works

Sending A Bulk Job

Troubleshooting

Next Steps

Bulk API reference

Send to a list

Message logs

User profiles

​Prerequisites

​How A Bulk Job Works

​Sending A Bulk Job

​Troubleshooting

​Next Steps

Bulk API reference

Send to a list

Message logs

User profiles

Prerequisites

How A Bulk Job Works

Sending A Bulk Job

Troubleshooting

Next Steps