> ## Documentation Index > Fetch the complete documentation index at: https://docs.prelude.so/llms.txt > Use this file to discover all available pages before exploring further. # Send bulk messages > Send the same message to multiple recipients in a single request using Prelude Notify API. 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. ```javascript Node.js (HTTP) theme={null} 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. ## OpenAPI ````yaml post /v2/notify/batch openapi: 3.1.0 info: title: Prelude API version: 2.0.0 description: The Prelude API allows you to send messages to your users. contact: email: support@prelude.so servers: - url: https://api.prelude.dev description: Production server security: - apiToken: [] tags: - name: Notify description: Send transactional and marketing messages with compliance enforcement. - name: Transactional description: Send transactional messages (deprecated - use Notify API instead). - name: Verify description: Verify phone numbers. - name: Watch description: Evaluate email addresses and phone numbers for trustworthiness. - name: Lookup description: >- Retrieve detailed information about a phone number including carrier data, line type, and portability status. paths: /v2/notify/batch: post: tags: - Notify summary: Send bulk messages description: Send the same message to multiple recipients in a single request. operationId: sendNotifyBulk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendNotifyBulkRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SendNotifyBulkResponse' '400': description: KO content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SendNotifyBulkRequest: type: object properties: from: type: string description: The Sender ID. Must be approved for your account. to: type: array description: The list of recipients' phone numbers in E.164 format. items: type: string format: phone_number examples: - - '+33612345678' - '+15551234567' template_id: type: string description: The template identifier configured by your Customer Success team. examples: - template_01k8ap1btqf5r9fq2c8ax5fhc9 locale: type: string description: A BCP-47 formatted locale string. examples: - el-GR - fr-FR variables: type: object description: The variables to be replaced in the template. additionalProperties: type: string examples: - order_id: '12345' amount: $49.99 expires_at: type: string format: date-time description: >- The message expiration date in RFC3339 format. Messages will not be sent after this time. examples: - '2025-12-25T18:00:00Z' schedule_at: type: string format: date-time description: >- Schedule delivery in RFC3339 format. Marketing sends may be adjusted to comply with local time windows. examples: - '2025-12-25T10:00:00Z' callback_url: type: string description: The URL where webhooks will be sent for delivery events. examples: - https://your-app.com/webhooks/notify correlation_id: type: string description: >- A user-defined identifier to correlate this request with your internal systems. maxLength: 80 examples: - campaign-12345 preferred_channel: type: string description: >- Preferred channel for delivery. If unavailable, automatic fallback applies. enum: - sms - rcs - whatsapp examples: - whatsapp document: type: object description: > 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. properties: url: type: string description: >- HTTPS URL of the media file. The file extension must match the template's registered header format (PDF for DOCUMENT; PNG/JPG/JPEG/WEBP for IMAGE; MP4/3GP for VIDEO). examples: - https://example.com/invoice.pdf - https://example.com/promo.png - https://example.com/demo.mp4 filename: type: string description: >- Filename displayed to the recipient. Required for templates with a `DOCUMENT` header; ignored for `IMAGE` and `VIDEO` headers. examples: - invoice.pdf required: - url required: - to - template_id SendNotifyBulkResponse: type: object properties: results: type: array description: The per-recipient result of the bulk send. items: $ref: '#/components/schemas/SendNotifyBulkResult' total_count: type: integer description: Total number of recipients. success_count: type: integer description: Number of successful sends. error_count: type: integer description: Number of failed sends. request_id: type: string description: A string that identifies this specific request. callback_url: type: string description: The callback URL used for this bulk request, if any. variables: type: object description: The variables used for this bulk request. additionalProperties: type: string template_id: type: string description: The template identifier used for this bulk request. required: - results - total_count - success_count - error_count Error: type: object properties: code: type: string description: The error code. examples: - invalid_phone_number message: type: string examples: - >- The provided phone number is invalid. Provide a valid E.164 phone number. description: A human-readable message describing the error. type: type: string examples: - bad_request description: The error type. request_id: type: string examples: - 3d19215e-2991-4a05-a41a-527314e6ff6a description: >- A string that identifies this specific request. Report it back to us to help us diagnose your issues. required: - code - message - type SendNotifyBulkResult: type: object properties: phone_number: type: string description: The recipient's phone number in E.164 format. examples: - '+33612345678' success: type: boolean description: Whether the message was accepted for delivery. message: allOf: - $ref: '#/components/schemas/SendNotifyBulkResultMessage' description: Present only if success is true. error: allOf: - $ref: '#/components/schemas/SendNotifyBulkResultError' description: Present only if success is false. required: - phone_number - success SendNotifyBulkResultMessage: type: object properties: id: type: string description: The message identifier. examples: - tx_01k8ap1btqf5r9fq2c8ax5fhc9 from: type: string description: The Sender ID used for this message. examples: - YourBrand to: type: string description: The recipient's phone number in E.164 format. examples: - '+33612345678' expires_at: type: string format: date-time description: The message expiration date in RFC3339 format. created_at: type: string format: date-time description: The message creation date in RFC3339 format. schedule_at: type: string format: date-time description: >- When the message will actually be sent in RFC3339 format with timezone offset. correlation_id: type: string description: The correlation identifier for the message. locale: type: string description: The locale used for the message, if any. estimated_segment_count: type: integer description: >- The estimated number of SMS segments for this message. This value is not contractual; the actual segment count will be determined after the SMS is sent by the provider. Only present for SMS messages. examples: - 1 encoding: type: string enum: - GSM-7 - UCS-2 description: >- The SMS encoding type based on message content. GSM-7 supports standard characters (up to 160 chars per segment), while UCS-2 supports Unicode including emoji (up to 70 chars per segment). Only present for SMS messages. examples: - GSM-7 SendNotifyBulkResultError: type: object properties: code: type: string description: The error code. examples: - invalid_phone_number message: type: string description: A human-readable error message. examples: - >- The provided phone number is invalid. Provide a valid E.164 phone number. securitySchemes: apiToken: type: http scheme: bearer ````