Send bulk messages

POST

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>"
}

{
  "code": "<string>",
  "message": "<string>",
  "type": "<string>",
  "request_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

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.

Show child attributes

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.

Show child attributes

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

results

object[]

required

The per-recipient result of the bulk send.

Show child attributes

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.

Show child attributes

template_id

string

The template identifier used for this bulk request.

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>"
}

{
  "code": "<string>",
  "message": "<string>",
  "type": "<string>",
  "request_id": "<string>"
}

Documentation

API Reference

Notes

Authorizations

Body

Response

​Notes

Authorizations

Body

Response

Notes