Send bulk messages

Send a message to multiple recipients in a single request using Prelude Notify API.

POST /v2/notify/batch

Node.js (HTTP)

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: ["[phone]", "[phone]"],
    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

200

{
  "results": [
    {
      "phone_number": "[phone]",
      "success": true,
      "message": {
        "id": "tx_01k8ap1btqf5r9fq2c8ax5fhc9",
        "from": "YourBrand",
        "to": "[phone]",
        "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": 1,
        "encoding": "GSM-7"
      },
      "error": {
        "code": "invalid_phone_number",
        "message": "The provided phone number is invalid. Provide a valid E.164 phone number."
      }
    }
  ],
  "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.

Node.js (HTTP)

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: ["[phone]", "[phone]"],
    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

Personalize each recipient

Use recipients instead of to to give each recipient their own template variables. Top-level variables are shared by all recipients. When a recipient sets the same key, the recipient’s value is used.

Node.js (HTTP)

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",
    variables: { amount: "$49.99" },
    recipients: [
      { to: "[phone]", variables: { name: "Alice" } },
      { to: "[phone]", variables: { name: "Bob", amount: "$19.99" } },
    ],
  }),
});

Alice receives the message with amount set to $49.99, and Bob with amount set to $19.99. You can’t set both to and recipients to a non-empty list in the same request.

Notes

• Each recipient is processed independently. Results are returned in the same order as the request.
• 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

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.

to · string<phone_number>[]

The list of recipients' phone numbers in E.164 format. Provide either to or recipients, not both.

Example:

["[phone]", "[phone]"]

recipients · object[]

The list of recipients, each with its own template variables. Use it to personalize the message for each recipient. Provide either to or recipients, not both.

Each recipient's variables are merged with the top-level variables. When both set the same key, the recipient's value is used. The same phone number can appear more than once, and each entry sends its own message.

Show child attributes

Example:

[
  {
    "to": "[phone]",
    "variables": { "name": "Alice" }
  },
  {
    "to": "[phone]",
    "variables": { "name": "Bob", "amount": "$19.99" }
  }
]

locale · string

A BCP-47 formatted locale string.

Examples:

"el-GR"

"fr-FR"

variables · object

The variables to be replaced in the template, shared by all recipients. When you use recipients, a recipient's own value for the same key is used instead.

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

200

application/json

OK

results · object[] · required

The per-recipient result of the bulk send, in the same order as the request.

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 shared variables used for this bulk request.

Show child attributes

template_id · string

The template identifier used for this bulk request.