Broadcast (admin) — Submit, queue, approve, reject

/api/v1/admin/notifications/broadcast* — 👤 Admin · permission notification:manage

Wave F-3 (shipped 2026-06-22) added a two-person approval gate for broadcast sends. When the notification.broadcast_dual_approval flag is TRUE (production default), every broadcast lands in NotificationBroadcastRequest as PENDING and a second admin must call the approve endpoint to fire the segment fan-out. Same-admin guard: the requester cannot approve or reject their own pending request.

POST /admin/notifications/broadcast — submit

Submits a broadcast for the configured segment. Returns either a pending request ID (flag ON) or direct fan-out result (flag OFF).

Request body — RequestBroadcastDto

Throttle / permission

Response — flag ON

{
  "success": true,
  "data": {
    "requestId": "n-broadcast-uuid-here",
    "status": "PENDING"
  }
}

Response — flag OFF (dev / staging)

{
  "success": true,
  "data": {
    "sent": 4823,
    "total": 4823,
    "segment": "all",
    "eventKey": "system_maintenance"
  }
}

Errors

GET /admin/notifications/broadcast/pending — pending queue

Returns up to 100 NotificationBroadcastRequest rows in PENDING status, oldest first. Powers the admin queue view for second-admin sign-off.

Response — ArrayApiResponseOf<PendingBroadcastItemDto>

{
  "success": true,
  "data": [
    {
      "id": "n-broadcast-uuid-here",
      "eventKey": "marketing_campaign",
      "segment": "fans",
      "channels": { "email": true, "push": false, "inApp": true, "sms": false },
      "variables": { "campaignName": "Spring 2026" },
      "scheduledAt": null,
      "requesterId": "admin-uuid",
      "requestedAt": "2026-06-22T14:00:00.000Z"
    }
  ]
}

Errors

POST /admin/notifications/broadcast/:id/approve

Second admin approves a pending broadcast. Atomic updateMany WHERE requesterId != approverId AND status = PENDING prevents self-approval and double-processing. On success, segment fan-out runs inline and NotificationBroadcastRequest.status flips PENDING → SENT.

Throttle / permission

Response — BroadcastApprovalResponseDto

{
  "success": true,
  "data": {
    "requestId": "n-broadcast-uuid-here",
    "status": "SENT",
    "sent": 4823,
    "total": 4823,
    "segment": "fans",
    "eventKey": "marketing_campaign"
  }
}

Errors

Side effects

1. Atomic flip PENDING → APPROVED with approverId + approvedAt set (race-safe).
2. If matched row is 0, disambiguates: findUnique → 404 (missing) / 400 self-approve / 400 wrong-status.
3. Load the now-APPROVED row, fan out via fanOutBroadcast using requestId as the dedupe seed (stable across the request → approve gap — re-approve never double-sends).
4. scheduledAt in the future is propagated onto every per-user NotificationJob.scheduleAt so the worker poll respects the slot.
5. Flip APPROVED → SENT with sentAt timestamp.
6. Fire broadcast_approved in-app notification to the requester (fire-and-forget, no email).

POST /admin/notifications/broadcast/:id/reject

Second admin rejects a pending broadcast. reason is required (10–500 chars) and persisted on the request row for audit.

Request body — RejectBroadcastDto

Throttle / permission

Response — BroadcastRejectionResponseDto

{
  "success": true,
  "data": {
    "requestId": "n-broadcast-uuid-here",
    "status": "REJECTED"
  }
}

Errors

Side effects

1. Validate reason (non-empty after trim — 400 if blank, length validators run at DTO level).
2. Atomic flip PENDING → REJECTED with approverId, approvedAt, rejectionReason set (race-safe; same-admin guard).
3. If matched is 0, disambiguates: 404 (missing) / 400 self-rejection / 400 wrong-status.
4. No notification dispatch to the requester (advisor scope-cut for F3).

Source