TagMangoTagMango Docs
Broadcasts

Create or schedule a broadcast

POST
/api/v1/external/broadcasts

Creates one email, WhatsApp, or app-notification broadcast for immediate or scheduled asynchronous dispatch. Choose exactly one delivery, audience, and channel shape.

For WhatsApp, first call Discover WhatsApp broadcast templates. Copy the selected template's templateName into channel.template.name and use its provider (or the response's top-level provider when a provider was explicitly requested). Add one channel.bindings entry for every value in that template's variables array. Mango-subscription audiences support name, email, phone, and mangos. Direct-recipient audiences always support phone and dialCode; name and custom scalar variables are allowed only when present on every recipient. The selected provider must be connected for the creator account. AiSensy templates must be text-only; Zaptick media templates use their saved header asset.

Email subjects are stored as sanitized single-line plain text; email HTML containing disallowed constructs is rejected. Email creation also enforces the creator’s daily warm-up limit using sent and already-scheduled volume for the target calendar day; creation fails closed when current usage cannot be verified. App notifications are unavailable on the Freedom plan and require completed app setup. Supplied notification deeplinks must be absolute HTTP(S) URLs. Direct destinations are canonicalized and silently deduplicated with the first row winning, up to 25,000 input rows. Mango audiences are counted when this request is accepted but are resolved again when the existing scheduler dispatches the campaign, so the eventual delivery count can differ after membership changes.

Immediate delivery is asynchronous: in-progress means the queue-compatible records exist, not that every message was delivered. Scheduled delivery uses the requested future ISO instant.

Retry warning: this operation has no idempotency key. If a client loses the response after submission, retrying may create a duplicate broadcast. Reconcile through your own request tracking before an ambiguous retry. The response deliberately excludes content, recipient data, provider identifiers, storage URLs, credit records, and queue acknowledgements.

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

Header Parameters

x-whitelabel-host*string

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api-prod-new.tagmango.com/api/v1/external/broadcasts" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{    "title": "October member update",    "delivery": {      "mode": "immediate"    },    "audience": {      "type": "recipients",      "recipients": [        {          "email": "asha@example.com",          "name": "Asha",          "variables": {            "cohort": "October"          }        }      ]    },    "channel": {      "type": "email",      "subject": "Your October update",      "html": "<p>Hello {{name}}, your {{cohort}} update is ready.</p>"    }  }'
{
  "code": 201,
  "result": {
    "id": "66fb6df8e1c2d34567890125",
    "title": "September member update",
    "channel": "email",
    "status": "scheduled",
    "scheduledAt": "2030-10-01T09:30:00.000Z",
    "createdAt": "2030-09-22T12:00:00.000Z",
    "audience": {
      "type": "mangoSubscriptions",
      "recipientCount": 847
    }
  },
  "type": "Success",
  "message": "Broadcast accepted successfully",
  "statusMessage": "CREATED",
  "success": true
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "errorCode": "BROADCAST_INVALID_REQUEST",
  "message": "The filters, schedule, audience, content, destinations, variables, or template bindings are invalid.",
  "result": "The filters, schedule, audience, content, destinations, variables, or template bindings are invalid.",
  "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 creator is not allowed to access broadcasts.",
  "result": "The authenticated creator is not allowed to access broadcasts.",
  "success": false
}

{
  "code": 404,
  "type": "Not Found",
  "statusMessage": "NOT_FOUND",
  "errorCode": "BROADCAST_CUSTOMER_NOT_FOUND",
  "message": "A referenced customer was not found on the authenticated host.",
  "result": "A referenced customer was not found on the authenticated host.",
  "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_PERSISTENCE_FAILED",
  "message": "The provider, storage, or campaign persistence step failed before durable acceptance.",
  "result": "The provider, storage, or campaign persistence step failed before durable acceptance.",
  "success": false
}
{
  "code": 503,
  "type": "Service Unavailable",
  "statusMessage": "SERVICE_UNAVAILABLE",
  "errorCode": "BROADCAST_EMAIL_USAGE_UNAVAILABLE",
  "message": "Current sent and scheduled email usage could not be verified. Retry before creating the broadcast.",
  "result": "Current sent and scheduled email usage could not be verified. Retry before creating the broadcast.",
  "success": false
}