---
title: "Send one message to multiple recipients (async)"
method: POST
path: "/api/v1/notifications/send-bulk-async"
tags: ["Notifications"]
---

# Send one message to multiple recipients (async)

`POST /api/v1/notifications/send-bulk-async`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/notifications/send-bulk-async`
- Auth: API key in header `X-API-Key`

Queues one notification per recipient. Always asynchronous: the 202 means jobs were queued, not that anything was delivered.

COMPARE `total_requested` WITH `queued_count` ON EVERY CALL. They differ when a recipient is inactive — that recipient is skipped and nothing else in the response says so. `queued_recipient_uuids` lists exactly who was queued, in UUIDs you can match against what you sent; the difference between that list and your input is who was silently skipped.

A request in which NOT ONE recipient could be queued is refused with 422 and `code: BULK_NOTHING_QUEUED` rather than answered 202 with a zero count, because "successfully queued nobody" reads as success.

Unknown, deleted or other-company UUIDs are a 422 on the request as a whole — nothing is queued, so a typo cannot half-send a batch. Follow each queued notification through GET /api/v1/notifications/{notification}/status; this endpoint returns no notification UUIDs, so find them via GET /api/v1/notifications filtered by recipient.

## Request body

- NotificationBulkSendRequest: One message, one channel, many recipients. There is no per-recipient override here — vary the message or the channel and you need separate calls.
  - `recipient_uuids` string[], required: Recipients to notify. Every UUID must belong to this company and must not be deleted — anything else is a 422 naming the offending index, not a silent skip.
  - `message` string, required: Text delivered to every recipient in the call.
  - `channel_type` string, required: Channel slug used for all of them: text_message, voice_message, voice_call, email, sms. Unlike the single-recipient send there is no automatic routing here — you pick the channel, and a recipient without a contact of that type simply fails on delivery.
  - `provider` string, required: Provider slug for that channel: telegram, platform_asterisk, smtp, … The valid pairs are the ones in the capabilities endpoint.
  - `audio_file` string, nullable: Audio to play, for voice channels only.
  - `priority` 'low' | 'normal' | 'high' | 'critical': Defaults to normal.
  - `queue` string, nullable: Named queue to dispatch onto. Defaults to `default`; leave it alone unless you have a reason.

## Response `202`

At least one notification was queued.

- object
  - `success` boolean
  - `queued` boolean
  - `message` string
  - `total_requested` integer: How many UUIDs you sent.
  - `queued_count` integer: How many were actually queued. Lower than total_requested means inactive recipients were skipped — compare the two.
  - `queued_recipient_uuids` string[]: The recipients that were queued, by UUID. Diff against your input to see who was skipped.
  - `queue` string

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the notifications.send ability.
- `404`: The recipient uuid exists, but not in this company. Deliberately indistinguishable from a typo — the API never confirms that somebody else's recipient exists. Note it is a 404 and not a 403: nothing here says the uuid is real.
- `422`: Either validation failed (an unknown, deleted or other-company recipient UUID, a missing channel_type/provider, a message over 4096 characters), or nothing could be queued at all — the latter carries `code: BULK_NOTHING_QUEUED` with `queued_count: 0`.
- `429`: The company does not have enough remaining notification quota for the whole batch. Carries `code: BULK_QUOTA_EXCEEDED` plus the daily and monthly remainders. Nothing is queued — the check is all-or-nothing, so a partial batch is never sent.

---

[API](https://skmtc.dev/wardenpoint/apis/wardenpoint-api.md) · [All operations](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/revisions/259ee445728e?raw)