TagMangoTagMango Docs
Broadcasts

List broadcasts

GET
/api/v1/external/broadcasts

Returns broadcasts owned by the authenticated creator. Filters are combined. Results are ordered by scheduledAt descending, then id descending; offset pages can shift as broadcasts change, so de-duplicate by id. Status is evaluated when the request runs. Malformed scalar parameters return the standard validation 400 response; invalid date-bound combinations return BROADCAST_INVALID_REQUEST. This operation is read-only and safe to retry.

External access policy

An API key and an authorized white-label host are required. Both tier and plan requirements are enforced.

These requirements apply to the white-label creator for backend-to-backend access. TagMango platform access is not supported.

  • Plans: Unrestricted.

  • Tiers: Unrestricted.

AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Maximum broadcasts per page. Values outside the documented range are rejected rather than clamped.

Default25
Range1 <= value <= 100
page?integer

One-based page. Out-of-range pages return an empty data array.

Default1
Range1 <= value
status?string

Filter by lifecycle state evaluated when the request runs. all applies no status filter.

Default"all"
Value in"cancelled" | "failed" | "in-progress" | "scheduled" | "sent" | "all"
channel?string

Filter by delivery channel.

Value in"email" | "whatsapp" | "appNotification"
scheduledAfter?string

Inclusive scheduled-time lower bound. Must be supplied with scheduledBefore.

Formatdate-time
scheduledBefore?string

Inclusive scheduled-time upper bound. Must be supplied with scheduledAfter.

Formatdate-time

Header Parameters

x-whitelabel-host*string

Host name of the dashboard, ex: mydomain.tagmango.com

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api-prod-new.tagmango.com/api/v1/external/broadcasts" \  -H "x-whitelabel-host: string"
{
  "total": 100,
  "data": [
    {
      "id": "66fb6df8e1c2d34567890125",
      "title": "September member update",
      "channel": "email",
      "scheduledAt": "2026-10-01T09:30:00.000Z",
      "createdAt": "2026-09-22T12:00:00.000Z",
      "status": "scheduled",
      "audience": {
        "type": "mangoSubscriptions",
        "recipientCount": 847,
        "mangoes": [
          {
            "_id": "66a1390268a76f2f5c9f39a3",
            "title": "Introduction to Coding"
          }
        ]
      }
    }
  ],
  "page": 1,
  "limit": 10,
  "hasNext": true
}
{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "BROADCAST_INVALID_REQUEST",
  "message": "`scheduledAfter` and `scheduledBefore` were not supplied together, or the lower bound is later than the upper bound.",
  "result": "`scheduledAfter` and `scheduledBefore` were not supplied together, or the lower bound is later than the upper bound.",
  "success": false
}
{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}
{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "BROADCAST_PERMISSION_DENIED",
  "message": "The authenticated account is not a creator or has not completed creator onboarding.",
  "result": "The authenticated account is not a creator or has not completed creator onboarding.",
  "success": false
}
{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}
{
  "code": 500,
  "type": "UnknownError",
  "statusMessage": "INTERNAL_SERVER_ERROR",
  "errorCode": "BROADCAST_LIST_FAILED",
  "message": "The broadcast list could not be returned. This request is safe to retry.",
  "result": "The broadcast list could not be returned. This request is safe to retry.",
  "success": false
}