Send in bulk

Send one notification to thousands of recipients you supply yourself, with a job you can abandon before anything goes out. Looping over Send API calls has no undo. A bulk job does. You build it across as many ingestion calls as you need, and nothing sends until you run it. An ingestion that fails halfway has delivered nothing, so abandon that job and build a fresh one.

What you will build

Prerequisites

Your deduplicated recipient list, with an email or phone for each

Run a bulk job

Create the job with the notification and any shared data, ingest recipients into it, then run it once and poll for progress. Ingestion is open-ended and the job does not expire while you fill it. Running is a one-way door.

Create the job

defines the job with an event and any global data that applies to everyone. The required event is either a or a custom event ID mapped to a notification.

const { jobId } = await client.bulk.createJob({
  message: {
    event: 'welcome-email',
    data: { company_name: 'Acme Corp' },
  },
});

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

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

response = courier.bulk.create_job(
  message: { event: "welcome-email", data: { company_name: "Acme Corp" } }
)

response, err := client.Bulk.NewJob(context.TODO(), courier.BulkNewJobParams{
	Message: courier.InboundBulkMessageParam{
		Event: "welcome-email",
		Data: map[string]any{
			"company_name": "Acme Corp",
		},
	},
})

BulkCreateJobParams params = BulkCreateJobParams.builder()
    .message(InboundBulkMessage.builder()
        .event("welcome-email")
        .data(InboundBulkMessage.Data.builder()
            .putAdditionalProperty("company_name", JsonValue.from("Acme Corp"))
            .build())
        .build())
    .build();
BulkCreateJobResponse response = client.bulk().createJob(params);

$response = $client->bulk->createJob(
  message: [
    'event' => 'welcome-email',
    'data' => ['company_name' => 'Acme Corp'],
  ],
);

BulkCreateJobParams parameters = new()
{
    Message = new()
    {
        Event = "welcome-email",
        Data = new Dictionary<string, JsonElement>()
        {
            { "company_name", JsonSerializer.SerializeToElement("Acme Corp") }
        },
    },
};

var response = await client.Bulk.CreateJob(parameters);

courier bulk create-job \
  --api-key "$COURIER_API_KEY" \
  --message '{"event":"welcome-email","data":{"company_name":"Acme Corp"}}'

With Courier MCP, create a bulk job for my welcome-email event with Acme Corp as global data.

Returns 201 Created with the job ID you 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. event stays required.

Make a retry safe.
Send an Idempotency-Key header and a retry replays the original result. A repeated create returns the first jobId instead of opening a second job.

Ingest your recipients

adds recipients to the job. Identify each one in to, and put their personal variables in data, which merges into the job’s global message.data.

await client.bulk.addUsers('JOB_ID', {
  users: [
    {
      to: { user_id: 'user_123' },
      profile: { email: 'sarah@acme-corp.com' },
      data: { name: 'Sarah Bennett' },
    },
    {
      to: { user_id: 'user_456' },
      profile: { email: 'kai@acme-corp.com' },
      data: { name: 'Kai Turner' },
    },
  ],
});

client.bulk.add_users(
    job_id="JOB_ID",
    users=[
        {
            "to": {"user_id": "user_123"},
            "profile": {"email": "sarah@acme-corp.com"},
            "data": {"name": "Sarah Bennett"},
        },
        {
            "to": {"user_id": "user_456"},
            "profile": {"email": "kai@acme-corp.com"},
            "data": {"name": "Kai Turner"},
        },
    ],
)

curl -X POST https://api.courier.com/bulk/JOB_ID \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "to": { "user_id": "user_123" },
        "profile": { "email": "sarah@acme-corp.com" },
        "data": { "name": "Sarah Bennett" }
      },
      {
        "to": { "user_id": "user_456" },
        "profile": { "email": "kai@acme-corp.com" },
        "data": { "name": "Kai Turner" }
      }
    ]
  }'

result = courier.bulk.add_users(
  "JOB_ID",
  users: [
    { to: { user_id: "user_123" },
      profile: { email: "sarah@acme-corp.com" },
      data: { name: "Sarah Bennett" } },
    { to: { user_id: "user_456" },
      profile: { email: "kai@acme-corp.com" },
      data: { name: "Kai Turner" } },
  ]
)

err := client.Bulk.AddUsers(
	context.TODO(),
	"JOB_ID",
	courier.BulkAddUsersParams{
		Users: []courier.InboundBulkMessageUserParam{{
			To:      shared.UserRecipientParam{UserID: courier.String("user_123")},
			Profile: map[string]any{"email": "sarah@acme-corp.com"},
			Data:    map[string]any{"name": "Sarah Bennett"},
		}, {
			To:      shared.UserRecipientParam{UserID: courier.String("user_456")},
			Profile: map[string]any{"email": "kai@acme-corp.com"},
			Data:    map[string]any{"name": "Kai Turner"},
		}},
	},
)

BulkAddUsersParams params = BulkAddUsersParams.builder()
    .jobId("JOB_ID")
    .addUser(InboundBulkMessageUser.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .profile(InboundBulkMessageUser.Profile.builder()
            .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
            .build())
        .data(JsonValue.from(Map.of("name", "Sarah Bennett")))
        .build())
    .addUser(InboundBulkMessageUser.builder()
        .to(UserRecipient.builder().userId("user_456").build())
        .profile(InboundBulkMessageUser.Profile.builder()
            .putAdditionalProperty("email", JsonValue.from("kai@acme-corp.com"))
            .build())
        .data(JsonValue.from(Map.of("name", "Kai Turner")))
        .build())
    .build();
client.bulk().addUsers(params);

$result = $client->bulk->addUsers(
  'JOB_ID',
  users: [
    [
      'to' => ['userID' => 'user_123'],
      'profile' => ['email' => 'sarah@acme-corp.com'],
      'data' => ['name' => 'Sarah Bennett'],
    ],
    [
      'to' => ['userID' => 'user_456'],
      'profile' => ['email' => 'kai@acme-corp.com'],
      'data' => ['name' => 'Kai Turner'],
    ],
  ],
);

BulkAddUsersParams parameters = new()
{
    JobID = "JOB_ID",
    Users =
    [
        new()
        {
            To = new() { UserID = "user_123" },
            Profile = new Dictionary<string, JsonElement>()
            {
                { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") }
            },
            Data = JsonSerializer.SerializeToElement(new { name = "Sarah Bennett" }),
        },
        new()
        {
            To = new() { UserID = "user_456" },
            Profile = new Dictionary<string, JsonElement>()
            {
                { "email", JsonSerializer.SerializeToElement("kai@acme-corp.com") }
            },
            Data = JsonSerializer.SerializeToElement(new { name = "Kai Turner" }),
        },
    ],
};

await client.Bulk.AddUsers(parameters);

courier bulk add-users \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID \
  --user '{"to":{"user_id":"user_123"},"profile":{"email":"sarah@acme-corp.com"},"data":{"name":"Sarah Bennett"}}' \
  --user '{"to":{"user_id":"user_456"},"profile":{"email":"kai@acme-corp.com"},"data":{"name":"Kai Turner"}}'

With Courier MCP, add these recipients to my bulk job, each with their own name variable.

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 four fields:

to.user_id, who they are
profile, inline contact data
data, per-recipient variables
preferences, per-recipient 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 does not 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 is in, triggers the send. Courier fans out and delivers to each recipient.

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

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

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

courier.bulk.run_job("JOB_ID")

err := client.Bulk.RunJob(context.TODO(), "JOB_ID")

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

$client->bulk->runJob('JOB_ID');

await client.Bulk.RunJob(new BulkRunJobParams { JobID = "JOB_ID" });

courier bulk run-job \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID

With Courier MCP, run my bulk job.

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

returns the job’s counts and overall status.

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)

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

response = courier.bulk.retrieve_job("JOB_ID")

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

response, err := client.Bulk.GetJob(context.TODO(), "JOB_ID")
if err != nil {
	panic(err.Error())
}

fmt.Printf("%+v\n", response.Job)

BulkRetrieveJobResponse response = client.bulk().retrieveJob("JOB_ID");

$response = $client->bulk->retrieveJob('JOB_ID');

var_dump($response);

var response = await client.Bulk.RetrieveJob(new BulkRetrieveJobParams { JobID = "JOB_ID" });

Console.WriteLine(response);

courier bulk retrieve-job \
  --api-key "$COURIER_API_KEY" \
  --job-id JOB_ID

With Courier MCP, show me the status and counts for my bulk job.

{
  "job": {
    "definition": {
      "event": "welcome-email"
    },
    "enqueued": 2,
    "failures": 0,
    "received": 2,
    "status": "COMPLETED"
  }
}

received: recipients ingested.
enqueued: messages that reached the delivery pipeline.
failures: errors hit while processing.
status: CREATED, PROCESSING, COMPLETED, or ERROR.

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

Verify

Confirm the counts line up

Poll the job until it reaches COMPLETED, then check that enqueued matches received and failures is zero.

Spot-check a recipient

Page through the job’s users with client.bulk.listUsers. Leave cursor off the first request, then keep passing paging.cursor back while paging.more is true. Each entry carries a recipient, a status of PENDING, ENQUEUED, or ERROR, and a messageId once enqueued.

Trace one message end to end

A messageId is the same ID a regular send returns, so look one up in and confirm it delivered.

To skip polling, with an outbound webhook and handle message:updated, which fires on every status change for every message the job produced.

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

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

What you will build

Prerequisites

Run a bulk job

Verify

Troubleshooting

​What you will build

​Prerequisites

​Run a bulk job

​Verify

​Troubleshooting

What you will build

Prerequisites

Run a bulk job

Verify

Troubleshooting