Skip to main content
POST
/
v2
/
notify
/
batch
const res = await fetch("https://api.prelude.dev/v2/notify/batch", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PRELUDE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to: ["+33612345678", "+15551234567"],
    variables: { order_id: "12345", amount: "$49.99" },
    callback_url: "https://your-app.com/webhooks/notify",
  }),
});

const body = await res.json();
console.log(body.total_count, body.success_count, body.error_count);
// Inspect per-recipient results in body.results

{
  "results": [
    {
      "phone_number": "<string>",
      "success": true,
      "message": {
        "id": "<string>",
        "from": "<string>",
        "to": "<string>",
        "expires_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "schedule_at": "2023-11-07T05:31:56Z",
        "correlation_id": "<string>",
        "locale": "<string>",
        "estimated_segment_count": 123
      },
      "error": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  ],
  "total_count": 123,
  "success_count": 123,
  "error_count": 123,
  "request_id": "<string>",
  "callback_url": "<string>",
  "variables": {},
  "template_id": "<string>"
}
Send to multiple recipients in one API call. Useful for transactional fan-out or marketing campaigns. If a recipient is not eligible (e.g., unsubscribed, invalid number), their entry will include an error in the results array; successful entries include a message object with IDs and timestamps. 
const res = await fetch("https://api.prelude.dev/v2/notify/batch", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PRELUDE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
    to: ["+33612345678", "+15551234567"],
    variables: { order_id: "12345", amount: "$49.99" },
    callback_url: "https://your-app.com/webhooks/notify",
  }),
});

const body = await res.json();
console.log(body.total_count, body.success_count, body.error_count);
// Inspect per-recipient results in body.results

​
Notes

  • Each recipient is processed independently.
  • For marketing sends, schedule_at may be adjusted to comply with local regulations.
  • Errors are returned per recipient in results[].error and do not fail the entire request.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
to
string<phone_number>[]
required

The list of recipients' phone numbers in E.164 format.

Example:
["+33612345678", "+15551234567"]
​
template_id
string
required

The template identifier configured by your Customer Success team.

Example:

"template_01k8ap1btqf5r9fq2c8ax5fhc9"

​
from
string

The Sender ID. Must be approved for your account.

​
locale
string

A BCP-47 formatted locale string.

Examples:

"el-GR"

"fr-FR"

​
variables
object

The variables to be replaced in the template.

Example:
{ "order_id": "12345", "amount": "$49.99" }
​
expires_at
string<date-time>

The message expiration date in RFC3339 format. Messages will not be sent after this time.

Example:

"2025-12-25T18:00:00Z"

​
schedule_at
string<date-time>

Schedule delivery in RFC3339 format. Marketing sends may be adjusted to comply with local time windows.

Example:

"2025-12-25T10:00:00Z"

​
callback_url
string

The URL where webhooks will be sent for delivery events.

Example:

"https://your-app.com/webhooks/notify"

​
correlation_id
string

A user-defined identifier to correlate this request with your internal systems.

Maximum string length: 80
Example:

"campaign-12345"

​
preferred_channel
enum<string>

Preferred channel for delivery. If unavailable, automatic fallback applies.

Available options:
sms,
rcs,
whatsapp
Example:

"whatsapp"

​
document
object

A media attachment to include in the message header. Supported on WhatsApp templates registered with a DOCUMENT, IMAGE, or VIDEO header. The media type is determined by the template's registered header format; send the matching file type for each.

  • DOCUMENT headers accept PDF and other document formats; filename is required and displayed to the recipient.
  • IMAGE headers accept .png, .jpg, .jpeg, and .webp URLs; filename is ignored.
  • VIDEO headers accept .mp4 and .3gp URLs; filename is ignored.
​
max_auto_retries
integer

Maximum number of automatic retry attempts across channels for each send in the batch, in addition to the first attempt. For example, 2 allows up to 3 total delivery attempts per recipient. Lower values reduce delivery cost on hard-to-reach numbers at the expense of deliverability. When omitted, your account's configured default applies.

Required range: 0 <= x <= 6
Example:

2

Response

OK

​
results
object[]
required

The per-recipient result of the bulk send.

​
total_count
integer
required

Total number of recipients.

​
success_count
integer
required

Number of successful sends.

​
error_count
integer
required

Number of failed sends.

​
request_id
string

A string that identifies this specific request.

​
callback_url
string

The callback URL used for this bulk request, if any.

​
variables
object

The variables used for this bulk request.

​
template_id
string

The template identifier used for this bulk request.