---
title: "Send notification to all recipients in a group"
method: POST
path: "/api/v1/notifications/send-to-group"
tags: ["Notifications"]
---

# Send notification to all recipients in a group

`POST /api/v1/notifications/send-to-group`

## 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-to-group`
- Auth: API key in header `X-API-Key`

## Request body

- NotificationGroupSendRequest
  - `group_uuid` string, uuid, required: Which group to page. Everyone in it is a separate delivery with its own outcome — one member being unreachable does not stop the others. The group's own notification settings decide the channel and the ladder; a member's personal settings apply only where the group rule defers to them.
  - `message` string, required: The alert text, as each member will read it. On a voice channel it is also what gets spoken. Keep it self-contained — a human woken at 4am sees this and nothing else.
  - `priority` 'low' | 'normal' | 'high' | 'critical': Which of the group's notification settings applies — that is what picks the channel and the escalation ladder. Defaults to `normal` when omitted.

## Response `200`

Group notification results. Successful responses carry a `delivery` object describing where this company stands against its plan quota — see `DeliveryOverageState`. Exceeding that quota never blocks a send; only the non-tariff daily ceiling does, and that answers 429 with `code: DELIVERY_CEILING_REACHED`.

- object
  - `delivery` DeliveryOverageState: Where this company stands against the notification quota of its plan, attached to every successful send response while unmetered delivery is switched on. Absent from the body when the feature is off — treat a missing `delivery` object as "no information", not as "within quota". **The quota does not stop delivery.** `over_plan: true` means alerts are still going out and the company is past what its plan includes; it is a billing signal, not a failure. Surface it, do not retry on it. The one thing that DOES stop delivery is `ceiling`: a non-tariff daily ceiling, identical on every plan and far above the largest one, that exists to catch a sender stuck in a loop. Crossing it answers 429 with `code: DELIVERY_CEILING_REACHED` instead of a success body, and the company owner is emailed. It resets at midnight.
    - `over_plan` boolean: True when this send took the company past its plan quota, or it already was. Delivery happened either way.
    - `scope` 'daily' | 'monthly', nullable: Which quota is exceeded. `monthly` wins when both are: the daily counter clears overnight, the monthly one does not. Null when nothing is exceeded.
    - `used` integer: Notifications counted against `scope` so far in its period (the daily counter when nothing is exceeded).
    - `limit` integer, nullable: The plan quota for `scope`. Null means the plan does not cap it.
    - `over_by` integer: How far past `limit` this send leaves the company. 0 when within quota.
    - `ceiling` integer: Daily anti-abuse ceiling in notifications. 0 means no ceiling is configured.
    - `ceiling_reached` boolean: Always false in a success body — a send that hit the ceiling answers 429 instead. Present so one schema describes both outcomes.
    - `daily_used` integer: Notifications sent today, owner-fallback rescue emails included — those are real messages on the wire. The denominator for `ceiling`.

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the notifications.send ability.
- `404`: The group uuid exists, but not in this company. Deliberately indistinguishable from a typo — the API never confirms that somebody else's group exists.

---

[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)