Create and Schedule Broadcast

Create a broadcast with HTML content and schedule it for delivery to specified recipients.

Use Cases:

• Send marketing newsletters to a segment of contacts
• Announce product launches to specific topics
• Send promotional emails to a list of email addresses
• Trigger one-time campaigns with personalized variables per recipient

Recipient Modes:
Recipients can be specified in multiple ways (at least one is required):

• contacts: Array of contact IDs from your workspace
• emails: Array of email addresses (will upsert contacts automatically)
• segment: Segment ID to send to all contacts matching segment conditions
• topic: Topic ID to send to all subscribed contacts

Per-Email Variables:
The emails field supports two formats:

1. Simple format (backward compatible):

{
  "emails": ["user1@example.com", "user2@example.com"]
}

2. With variables:

{
  "emails": [
    { "email": "user1@example.com", "variables": { "orderNumber": "12345", "discount": 20 } },
    { "email": "user2@example.com", "variables": { "orderNumber": "67890", "discount": 15 } }
  ]
}

Variables can be used in email content with {{variableName}} syntax:

• {{orderNumber}} - Direct variable reference
• {{contact.orderNumber}} - Prefixed with contact (both work the same)

Variable Priority (highest to lowest):

1. Transient variables (per-email, from API request)
2. Contact properties (from database)
3. Built-in variables (email, firstName, lastName, URLs)

Transient variables override contact properties with the same name but are NOT saved to the contact record.

Behavior:

• Creates a new broadcast in QUEUED_FOR_SENDING status
• Email content is validated and stored
• Broadcast is scheduled for delivery at the specified sendAt time
• Recipients are resolved at send time (not at creation time)
• For emails mode, contacts are upserted (created if not existing)
• Sending domain must be verified before the broadcast can be sent

Required Scope: broadcasts:write

Rate Limits:

• 100 broadcasts per hour per workspace
• Maximum 100,000 recipients per broadcast

Email Content:

• Subject and HTML are required
• Plain text is auto-generated from HTML if not provided
• Preview text is optional but recommended for inbox preview
• Use {{variableName}} for personalization (first name, custom properties, etc.)

Scheduling:

• sendAt must be a future ISO 8601 datetime
• Broadcast will be processed at the scheduled time
• Cannot be modified after creation (create a new broadcast instead)

Sandbox/Test Mode:
For testing without sending real emails, use @kibamail.dev test addresses. These addresses simulate different delivery outcomes:

Address	Simulated Outcome
delivered@kibamail.dev	Successful delivery
bounced@kibamail.dev	Hard bounce
softbounce@kibamail.dev	Soft bounce (transient failure)
complained@kibamail.dev	Spam complaint
failed@kibamail.dev	Permanent delivery failure
delayed@kibamail.dev	Delayed delivery (retries then succeeds)
opened@kibamail.dev	Delivered + opened
clicked@kibamail.dev	Delivered + opened + clicked

Sandbox features:

• Add +label for tracking: delivered+campaign1@kibamail.dev
• Events are generated instantly (no actual email sent)
• sendAt can be any time (processed immediately)
• Cannot mix sandbox and real email addresses in the same broadcast
• Per-email variables work with sandbox addresses

Best Practices:

• Always test with a small segment first
• Use preview text for better inbox engagement
• Include unsubscribe links for compliance
• Verify sending domain before scheduling