Skip to content
DashboardGet API key

Send broadcast

View .md
POST

Start sending the broadcast immediately or schedule for later.

Sending a broadcast needs no account verification. Identity and business verification raise daily ceilings; neither is a permission to broadcast, on any channel. What stands in front of a broadcast is the content review below, and it applies to every send path — dashboard, API and CLI. Drafts can be created, edited and kept freely.

Email broadcasts need a paid plan. On Free, sending or scheduling a broadcast on the email channel is refused with 402 and code paid_plan_required; drafts can still be created and edited. A smart broadcast is not refused: its email recipients fail individually with errorCode PAID_PLAN_REQUIRED and the others are sent. Teams created before August 1, 2026 keep their earlier terms.

Daily ceilings apply per recipient. Each message a broadcast sends counts against the channel's daily ceiling (see POST /v1/messages). Once the ceiling is reached, the remaining recipients are marked failed with errorCode DAILY_LIMIT_EXCEEDED; they are not retried the next day.

Review depends on the channel, and cannot be bypassed. A draft is submitted to automated content review here; it does not go straight out. A WhatsApp broadcast built on a Meta-approved template skips review (Meta already vetted the content) and begins sending. An email broadcast sends as soon as the review passes it, unless the review asks for a person. Every other channel moves to pending_admin_review and waits for a person. A broadcast the review refuses lands on rejected: use PATCH to edit the content then call POST /retry-review, or escalate it for a manual review.

A broadcast is read once, on its own text, rather than per recipient. While an account's sending is suspended its recipients fail individually with errorCode SENDING_SUSPENDED; see POST /v1/messages.

Calling this on a broadcast that is already approved or scheduled sends or reschedules it directly, since it has already been reviewed. Reserves the estimated cost from your balance.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • broadcastIdstringrequired

Body

application/json · optional

  • scheduledAtstring<date-time>

    Schedule for future delivery. Omit to send immediately.

Responses

202Broadcast started or scheduled.
  • broadcastobjectrequired
    26 properties
    • idstringrequired
    • namestringrequired
    • statusstringrequired

      Current status of the broadcast. pending_review: in the automated content review. pending_admin_review: the automated review passed and it waits for a person, which is where every channel but a WhatsApp broadcast on an approved template goes. rejected: the review refused it; edit it and retry the review, or escalate. scheduled and sending follow approval.

      One ofdraftpending_reviewpending_admin_reviewapprovedrejectedescalatedrejected_finalscheduledsendingpausedcompletedcancelledfailed
    • channelstringrequired

      Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.

      One ofsmartsmssms_onewaywhatsapptelegramemail
    • messageTypestringrequired

      Type of message for broadcast.

      One oftextimagevideoaudiodocumenttemplate
    • textstring
    • contentobject

      Content for non-text broadcast message types.

      8 properties
      • mediaUrlstring

        URL of the media file.

      • mediaIdstring

        Media ID if already uploaded.

      • mimeTypestring

        MIME type of the media.

      • filenamestring

        Filename for documents.

      • templateIdstring

        Template ID for template messages.

      • templateVariablesobject

        Default body variables (can be overridden per contact). Key them to match the template body: by position (1, 2, ...) for positional templates, or by name (e.g. customer_name) for named templates. Zavu detects the template's format and sends the correct payload to Meta. Do not mix positional and named keys.

        1 properties
        • {key}string
      • templateButtonVariablesobject

        Default button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2). Per-contact values override these.

        1 properties
        • {key}string
      • templateHeaderVariablesobject

        Default value for a text-header variable, keyed by 1 (can be overridden per contact). If omitted, Zavu resolves the header from templateVariables by the header placeholder's name.

        1 properties
        • {key}string
    • senderIdstring
    • emailSubjectstring
    • totalContactsintegerrequired

      Total number of contacts in the broadcast.

    • pendingCountinteger
    • sendingCountinteger
    • sentCountinteger

      Recipients whose message the provider accepted, without a confirmed delivery yet. Channels that never report delivery keep their recipients here.

    • deliveredCountinteger

      Recipients with confirmed delivery to the device.

    • failedCountinteger
    • estimatedCostnumbernullable

      Estimated total cost in USD.

    • reservedAmountnumbernullable

      Amount reserved from balance in USD.

    • actualCostnumbernullable

      Actual cost so far in USD.

    • scheduledAtstring<date-time>
    • startedAtstring<date-time>
    • completedAtstring<date-time>
    • metadataobject
      1 properties
      • {key}string
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
    • reviewResultobjectnullable

      AI content review result.

      5 properties
      • scorenumber

        Content safety score from 0.0 to 1.0, where 1.0 is completely safe.

      • categoriesstring[]

        Policy categories violated, if any.

      • reasoningstring

        Explanation of the review decision.

      • reviewedAtstring<date-time>
      • flaggedContentstring[]nullable

        Problematic text fragments, if any.

    • reviewAttemptsintegernullable

      Number of review attempts (max 3).

400Invalid request, no contacts, or broadcast not in valid status.

Invalid request, no contacts, or broadcast not in valid status.

A broadcast whose sender was deleted after it was created is refused here with code sender_not_found, before any balance is reserved. Create a new broadcast with another sender.

A WhatsApp broadcast whose template Meta has not approved yet is refused here with code template_not_approved. Because a WhatsApp broadcast needs no account verification, this is the only review it passes through: retry once the template is approved.

  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402Insufficient balance (`insufficient_balance`), or an email broadcast on a plan without email broadcasts (`paid_plan_required`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Broadcast not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject