Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bryan/fixing broken link #556

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Bryan/fixing broken link #556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7ceed8
making updates for the bulk endpoint to remove confusing body parameter
bwebs Jan 26, 2024
94166c2
fixing broken tutorial link
bwebs Jan 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 79 additions & 95 deletions docs/guides/tutorials/how-to-send-bulk-notifications.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,138 @@
---
sidebar_position: 7
description: Learn how 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.
displayed_sidebar: sidebar
product: ["Sending"]
type: ["REST API"]
---

import Image from "@theme/IdealImage";
import GifWrapper from "@site/src/components/GifWrapper";

# How To Send Bulk Notifications

Bulk processing allows executing multiple job definitions across arbitrarily large set of input.
Currently, we have added a feature that enables sending message definitions to large numbers of users in a single API invocation.
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](/reference/send) 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:
**Request:**

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

```json
{
"headers": {
"idempotency-key": "rbJ9QDcWn84A-rO94HrbP"
},
"body": {
"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": {
"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
}
// optional API v2 message that supports elemental
}
}
}
```

Response:
:::info Note
All bulk endpoints also support [idempotent requests](https://www.courier.com/docs/reference/idempotent-requests/) using the `Idempotency-Key` header.
:::

**Response:**

Status: 201

```json
{
"status": 201,
"body": {
"jobId": "1-61e9dd53-b5bb6c863b7ffbe83ad4b28d"
}
"jobId": "1-61e9dd53-b5bb6c863b7ffbe83ad4b28d"
}
```

## Ingest users to the bulk job
## 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.

Request:
:::info 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}`

```json
{
"headers": {
"idempotency-key": "rbJ9QDcWn84A-rO94HrbP"
},
"body": {
"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
}
"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:
**Response:**

Status: 200

```json
{
"status": 200,
"body": {
// 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 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
}
}
],
// gives total count of users that were successfully ingested
"total": 1
}
```

## Executing the job
## Executing the Job

Once you have added the users to your job, it can be triggered.
Note: a job ID 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.

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

```json
{
"headers": {
"idempotency-key": "rbJ9QDcWn84A-rO94HrbP"
}
}
```
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.
:::

Response:
**Request:**

```json
{
"status": 202
}
```
`POST https://api.courier.com/bulk/{jobId}/run`

**Response:**

## Fetching Bulk Job information
Status: 202

### Job status
## Fetching Bulk Job Information

- `CREATED` a job has been created, but has not yet been invoked/run. This should be the initial status of a bulk job when it is created.
- `PROCESSING` the bulk job is currently being processed.
- `COMPLETED` all items in the job have been placed in to the Courier send pipeline
### 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}`

Expand All @@ -160,10 +152,6 @@ Response:

### Job Items/Users

- `PENDING` a job has been populated with the user, but has not yet been invoked/run. This should be the initial status when a user is added to a job
- `ERROR` an error occurred enqueuing the user/configuration combination in the processing pipeline
- `ENQUEUED` the user/configuration combination have been enqueued in the processing pipeline

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

```json
Expand Down Expand Up @@ -198,10 +186,6 @@ Response:
}
```

## Message information

This would be just like how a regular /send call works.

Messages are visible on the Courier UI or can be fetched via Messages API.
## Message Information

If you have webhooks configured, Courier will invoke it with the message data throughout the lifecycle of the message.
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.
Loading