Sending & Scheduling

Once you’ve added contacts to your broadcast, trigger the send to start delivering messages.

Send Immediately

const broadcast = await zavu.broadcasts.send(broadcastId);

console.log(`Status: ${broadcast.status}`); // "pending_review"

broadcast = zavu.broadcasts.send(broadcast_id)

print(f"Status: {broadcast.status}")  # "pending_review"

broadcast = client.broadcasts.send(broadcast_id)

puts "Status: #{broadcast.status}"  # "pending_review"

broadcast, _ := client.Broadcasts.Send(context.TODO(), broadcastID, zavudev.BroadcastSendParams{})

fmt.Printf("Status: %s\n", broadcast.Status)  // "pending_review"

$broadcast = $client->broadcasts->send($broadcastId);

echo "Status: {$broadcast->status}\n";  // "pending_review"

curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/send \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Response

{
  "id": "brd_abc123",
  "name": "Weekly Newsletter",
  "status": "pending_review",
  "channel": "sms",
  "totalContacts": 1500,
  "reviewAttempts": 1,
  "createdAt": "2024-01-15T10:00:00.000Z"
}

All broadcasts go through an automated AI content review before sending. The broadcast enters pending_review status and, once approved, proceeds to sending automatically. Subscribe to the broadcast.status_changed webhook event to track the review process in real-time.

Schedule for Later

Schedule a broadcast to send at a specific time:

// Schedule for tomorrow at 9am UTC
const broadcast = await zavu.broadcasts.send(broadcastId, {
  scheduledAt: "2024-01-16T09:00:00.000Z",
});

console.log(`Status: ${broadcast.status}`); // "scheduled"
console.log(`Scheduled for: ${broadcast.scheduledAt}`);

broadcast = zavu.broadcasts.send(
    broadcast_id,
    scheduled_at="2024-01-16T09:00:00.000Z"
)

print(f"Status: {broadcast.status}")  # "scheduled"
print(f"Scheduled for: {broadcast.scheduled_at}")

broadcast = client.broadcasts.send(broadcast_id,
  scheduled_at: "2024-01-16T09:00:00.000Z"
)

puts "Status: #{broadcast.status}"             # "scheduled"
puts "Scheduled for: #{broadcast.scheduled_at}"

broadcast, _ := client.Broadcasts.Send(context.TODO(), broadcastID, zavudev.BroadcastSendParams{
	ScheduledAt: zavudev.String("2024-01-16T09:00:00.000Z"),
})

fmt.Printf("Status: %s\n", broadcast.Status)           // "scheduled"
fmt.Printf("Scheduled for: %s\n", broadcast.ScheduledAt)

$broadcast = $client->broadcasts->send($broadcastId, [
    'scheduledAt' => '2024-01-16T09:00:00.000Z',
]);

echo "Status: {$broadcast->status}\n";             // "scheduled"
echo "Scheduled for: {$broadcast->scheduledAt}\n";

curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/send \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2024-01-16T09:00:00.000Z"
  }'

Use scheduling to send campaigns at optimal times for your audience’s timezone. For example, schedule a morning message to arrive at 9am in the recipient’s local time.

Rescheduling a Broadcast

If you need to change the scheduled time, you can reschedule a broadcast that’s in scheduled status:

const broadcast = await zavu.broadcasts.reschedule(broadcastId, {
  scheduledAt: "2024-01-17T14:00:00.000Z",
});

console.log(`New scheduled time: ${broadcast.scheduledAt}`);

broadcast = zavu.broadcasts.reschedule(
    broadcast_id,
    scheduled_at="2024-01-17T14:00:00.000Z"
)

print(f"New scheduled time: {broadcast.scheduled_at}")

broadcast = client.broadcasts.reschedule(broadcast_id,
  scheduled_at: "2024-01-17T14:00:00.000Z"
)

puts "New scheduled time: #{broadcast.scheduled_at}"

broadcast, _ := client.Broadcasts.Reschedule(context.TODO(), broadcastID, zavudev.BroadcastRescheduleParams{
	ScheduledAt: zavudev.String("2024-01-17T14:00:00.000Z"),
})

fmt.Printf("New scheduled time: %s\n", broadcast.ScheduledAt)

$broadcast = $client->broadcasts->reschedule($broadcastId, [
    'scheduledAt' => '2024-01-17T14:00:00.000Z',
]);

echo "New scheduled time: {$broadcast->scheduledAt}\n";

curl -X PATCH https://api.zavu.dev/v1/broadcasts/{broadcastId}/schedule \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2024-01-17T14:00:00.000Z"
  }'

You can only reschedule broadcasts that are in scheduled status. The new time must be in the future.

Pre-Send Validation

Before sending, the API validates:

Validation	Error if Failed
Status is `draft`, `approved`, or `scheduled`	`broadcast_already_sending`
At least 1 contact exists	`no_contacts`
Sender is configured for channel	`sender_not_configured`
Sufficient balance (SMS/Email)	`insufficient_balance`
Template exists and approved (WhatsApp)	`template_not_approved`

Balance Reservation

When you trigger a broadcast, Zavu reserves the estimated cost from your balance. This ensures funds are available for the entire campaign.

Available Balance: $100.00
Broadcast Cost:     $25.00 (estimated)
                    ───────
Reserved Balance:   $25.00 (blocked)
Usable Balance:     $75.00

How It Works

Cost Estimation

When you call /send, Zavu calculates the estimated cost based on contacts and channel rates

Balance Check

If your available balance (excluding other reservations) is less than the estimated cost, the request fails

Reservation Created

The estimated amount is reserved and cannot be used for other broadcasts or messages

Messages Sent

As messages are delivered, actual costs are deducted from the reservation

Reservation Released

When the broadcast completes or is cancelled, any unused reserved funds are released back to your available balance

Checking Your Balance

const billing = await zavu.balance.retrieve();

// `balance` is in cents.
console.log(`Balance: $${(billing.balance / 100).toFixed(2)}`);

Reserved and available amounts are not part of the balance response. When a send is refused for funds, the 402 body carries them under details:

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Available: $50.00",
  "details": {
    "totalBalance": 50,
    "reservedBalance": 25,
    "availableBalance": 25
  }
}

Response with Reservation

When a broadcast starts, the response includes reservation details:

{
  "id": "brd_abc123",
  "status": "sending",
  "totalContacts": 1500,
  "estimatedCost": 25.00,
  "reservedAmount": 25.00,
  "startedAt": "2024-01-15T10:30:00.000Z"
}

Insufficient Balance

If you don’t have enough available balance:

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this broadcast",
  "details": {
    "estimatedCost": 25.00,
    "availableBalance": 10.50,
    "reservedBalance": 15.00,
    "totalBalance": 25.50,
    "requiredAmount": 14.50
  }
}

Reserved funds are blocked until the broadcast completes or is cancelled. Plan your campaigns to avoid blocking funds needed for other messaging.

Reservation Release

Scenario	What Happens
Broadcast completes	Unused reservation released immediately
Broadcast cancelled	Full reservation released (minus already-sent messages)
Actual cost < estimated	Difference released when broadcast completes
Actual cost > estimated	Additional amount charged from available balance

WhatsApp message costs are billed directly by Meta, not deducted from your Zavu balance. No reservation is created for WhatsApp-only broadcasts.

Content Review

All broadcasts go through an automated AI content review before sending. This protects both you and your recipients from policy violations.

How Content Review Works

Submit for Sending

When you call /send, the broadcast enters pending_review status

AI Analysis

Content is analyzed for spam, phishing, prohibited content, and policy violations

Decision

Broadcast is either approved and proceeds, or rejected with feedback

Review Statuses

Status	Description
`pending_review`	Content being analyzed
`approved`	Review passed, broadcast proceeds
`rejected`	Content rejected, needs editing
`escalated`	Sent to human review
`rejected_final`	Rejected by human review (cannot be appealed)

Handling Rejections

If your broadcast is rejected, you’ll receive details about the issue:

{
  "id": "brd_abc123",
  "status": "rejected",
  "reviewResult": {
    "score": 0.35,
    "categories": ["spam_indicators", "missing_opt_out"],
    "reasoning": "Message contains promotional content without unsubscribe option",
    "flaggedContent": ["limited time offer", "act now"],
    "reviewedAt": "2024-01-15T10:31:00.000Z"
  },
  "reviewAttempts": 1
}

Editing and Retrying

After rejection, edit your broadcast content and retry the review:

// 1. Get the rejected broadcast
const broadcast = await zavu.broadcasts.retrieve(broadcastId);

if (broadcast.status === "rejected") {
  console.log("Rejection reason:", broadcast.reviewResult?.reasoning);

  // 2. Edit the content to address issues
  await zavu.broadcasts.update(broadcastId, {
    text: "Thanks for being a customer! Check out our latest products. Reply STOP to unsubscribe.",
  });

  // 3. Retry the review
  const updated = await zavu.broadcasts.retryReview(broadcastId);
  console.log("New status:", updated.status); // "pending_review"
}

# 1. Get the rejected broadcast
broadcast = zavu.broadcasts.retrieve(broadcast_id)

if broadcast.status == "rejected":
    print(f"Rejection reason: {broadcast.review_result.reasoning}")

    # 2. Edit the content to address issues
    zavu.broadcasts.update(broadcast_id,
        text="Thanks for being a customer! Check out our latest products. Reply STOP to unsubscribe."
    )

    # 3. Retry the review. Not generated in the Python SDK yet, so call the
    #    endpoint directly: POST /v1/broadcasts/{id}/retry-review
    res = httpx.post(
        f"https://api.zavu.dev/v1/broadcasts/{broadcast_id}/retry-review",
        headers={"Authorization": f"Bearer {os.environ['ZAVUDEV_API_KEY']}"},
    )
    print(f"New status: {res.json()['broadcast']['status']}")  # "pending_review"

# 1. Get the rejected broadcast
broadcast = client.broadcasts.retrieve(broadcast_id)

if broadcast.status == "rejected"
  puts "Rejection reason: #{broadcast.review_result&.reasoning}"

  # 2. Edit the content to address issues
  client.broadcasts.update(broadcast_id,
    text: "Thanks for being a customer! Check out our latest products. Reply STOP to unsubscribe."
  )

  # 3. Retry the review
  updated = client.broadcasts.retry_review(broadcast_id)
  puts "New status: #{updated.status}"  # "pending_review"
end

# 1. Update the content
curl -X PATCH https://api.zavu.dev/v1/broadcasts/{broadcastId} \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thanks for being a customer! Check out our latest products. Reply STOP to unsubscribe."
  }'

# 2. Retry the review
curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/retry-review \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

You have a maximum of 3 review attempts per broadcast. After 3 rejections, you must escalate to manual review or create a new broadcast.

Escalating to Manual Review

If you believe your content was incorrectly rejected, escalate to the Zavu team:

const broadcast = await zavu.broadcasts.escalateReview(broadcastId);

console.log("Status:", broadcast.status); // "escalated"
// Zavu team will review and update status to "approved" or "rejected_final"

broadcast = client.broadcasts.escalate_review(broadcast_id)

puts "Status: #{broadcast.status}"  # "escalated"

curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/escalate \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Manual reviews are typically processed within 24 hours during business days. You’ll receive a webhook notification when the review is complete.

Content Guidelines

To avoid rejections, ensure your broadcasts:

Requirement	Example
Include opt-out instructions	”Reply STOP to unsubscribe”
Avoid spam trigger words	Avoid “FREE”, “ACT NOW”, “LIMITED TIME” in all caps
Identify your business	Include your company name
Don’t impersonate	Never pretend to be banks, government, etc.
Avoid URL shorteners	Use full URLs (see URL Verification)

Cancelling a Broadcast

Cancel a broadcast that hasn’t completed:

const broadcast = await zavu.broadcasts.cancel(broadcastId);

console.log(`Status: ${broadcast.status}`); // "cancelled"

broadcast = zavu.broadcasts.cancel(broadcast_id)

print(f"Status: {broadcast.status}")  # "cancelled"

broadcast = client.broadcasts.cancel(broadcast_id)

puts "Status: #{broadcast.status}"  # "cancelled"

broadcast, _ := client.Broadcasts.Cancel(context.TODO(), broadcastID)

fmt.Printf("Status: %s\n", broadcast.Status) // "cancelled"

$broadcast = $client->broadcasts->cancel($broadcastId);

echo "Status: {$broadcast->status}\n"; // "cancelled"

curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/cancel \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

What Happens on Cancel

Original Status	Action
`draft`	Broadcast deleted
`scheduled`	Returns to `draft`, can be rescheduled
`sending`	Stops new messages, pending contacts marked as `skipped`

Messages already queued or sent cannot be cancelled. Only pending contacts are skipped.

Delivery Rate Limits

Zavu automatically rate-limits delivery to prevent carrier throttling:

Channel	Rate	Notes
SMS	10/second	Shared across all projects
WhatsApp	60/second	Per WhatsApp Business Account
Email	14/second

For a 10,000 contact SMS broadcast:

Estimated time: ~17 minutes (10,000 / 10 per second)

Large broadcasts are processed in the background. Use the progress endpoint to monitor delivery.

Cost Estimation

Get estimated cost before sending:

const broadcast = await zavu.broadcasts.retrieve(broadcastId);

console.log(`Estimated cost: $${broadcast.estimatedCost}`);
console.log(`Total contacts: ${broadcast.totalContacts}`);

Channel	Cost Model
SMS	Per-message (varies by country)
WhatsApp	Free (24h window) or template pricing
Email	$0.02 per message

Messages also count toward your plan’s monthly message limits, with usage-based overage applied beyond them. See your plan for the exact limits and rates.

Complete Workflow Example

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

async function sendPromotion(contacts: Array<{phone: string, name: string}>) {
  // 1. Create broadcast
  const broadcast = await zavu.broadcasts.create({
    name: "Holiday Sale 2024",
    channel: "sms",
    text: "Hi {{name}}! Our holiday sale is live. Get 30% off with code HOLIDAY30. Shop now!",
  });

  console.log(`Created broadcast: ${broadcast.id}`);

  // 2. Add contacts in batches
  const BATCH_SIZE = 1000;
  for (let i = 0; i < contacts.length; i += BATCH_SIZE) {
    const batch = contacts.slice(i, i + BATCH_SIZE);

    const result = await zavu.broadcasts.contacts.add(broadcast.id, {
      contacts: batch.map(c => ({
        recipient: c.phone,
        templateVariables: { name: c.name },
      })),
    });

    console.log(`Batch ${Math.floor(i / BATCH_SIZE) + 1}: Added ${result.added} contacts`);
  }

  // 3. Check estimated cost
  const updated = await zavu.broadcasts.retrieve(broadcast.id);
  console.log(`Estimated cost: $${updated.estimatedCost}`);
  console.log(`Total contacts: ${updated.totalContacts}`);

  // 4. Send the broadcast
  await zavu.broadcasts.send(broadcast.id);
  console.log("Broadcast started!");

  // 5. Poll for progress
  let complete = false;
  while (!complete) {
    await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds

    const progress = await zavu.broadcasts.progress(broadcast.id);
    console.log(`Progress: ${progress.percentComplete}% (${progress.delivered} delivered, ${progress.failed} failed)`);

    if (progress.status === "completed" || progress.status === "cancelled") {
      complete = true;
    }
  }

  console.log("Broadcast complete!");
}

Next Steps

Tracking Progress

Monitor delivery progress in real-time

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Sending & Scheduling

Send Immediately

Response

Schedule for Later

Rescheduling a Broadcast

Pre-Send Validation

Balance Reservation

How It Works

Checking Your Balance

Response with Reservation

Insufficient Balance

Reservation Release

Content Review

How Content Review Works

Review Statuses

Handling Rejections

Editing and Retrying

Escalating to Manual Review

Content Guidelines

Cancelling a Broadcast

What Happens on Cancel

Delivery Rate Limits

Cost Estimation

Complete Workflow Example

Next Steps

Tracking Progress

​Send Immediately

​Response

​Schedule for Later

​Rescheduling a Broadcast

​Pre-Send Validation

​Balance Reservation

​How It Works

​Checking Your Balance

​Response with Reservation

​Insufficient Balance

​Reservation Release

​Content Review

​How Content Review Works

​Review Statuses

​Handling Rejections

​Editing and Retrying

​Escalating to Manual Review

​Content Guidelines

​Cancelling a Broadcast

​What Happens on Cancel

​Delivery Rate Limits

​Cost Estimation

​Complete Workflow Example

​Next Steps

Tracking Progress

Send Immediately

Response

Schedule for Later

Rescheduling a Broadcast

Pre-Send Validation

Balance Reservation

How It Works

Checking Your Balance

Response with Reservation

Insufficient Balance

Reservation Release

Content Review

How Content Review Works

Review Statuses

Handling Rejections

Editing and Retrying

Escalating to Manual Review

Content Guidelines

Cancelling a Broadcast

What Happens on Cancel

Delivery Rate Limits

Cost Estimation

Complete Workflow Example

Next Steps