Skip to navigation
API ReferenceEmail

Send Email broadcast

View as Markdown

Creates an email broadcast, records one message per recipient, atomically reserves credit (prepaid), and dispatches it synchronously. The response returns once every recipient has been attempted, with per-recipient send/failed counts.

Required scope: send_email Rate limit: 10 requests / 15 min / client

Email cannot be scheduled. type must be quick broadcast; sending schedule broadcast returns 400 - Scheduled sending is not available for email. Send it as a quick broadcast instead.

Billing semantics (prepaid clients)

  1. The full recipientCount × emailRate is reserved at broadcast creation
  2. Each successful send (accepted by the email provider) is settled
  3. Each rejected send releases that recipient’s portion back to balance

A 100-recipient broadcast that succeeds for 95 and fails for 5 ends with 95 charges settled and 5 reserved-credit returned.

Delivery reporting

The sent / failed / total counts in the response are the complete result - the email channel does not emit webhook events. Use the dashboard’s Message Logs for per-recipient detail.

Authentication

AuthorizationBearer

Bearer API keys are issued from the in-app /api-management page. Each key has a permission scope (send_sms, send_whatsapp, send_email) and an optional IP whitelist.

The IP whitelist, when set, is matched by exact string equality against the resolved caller IP - CIDR ranges are not supported. An empty whitelist allows any source address.

Request

This endpoint expects an object.
templateNamestringRequired1-512 characters
subjectstringRequired1-200 characters
typeenumRequired

Must be quick broadcast. Scheduling is not available on the email channel.

Allowed values:
campaignNamestringOptional1-255 characters
Optional on the email channel.
recipientslist of stringsOptional
recipientVariableslist of objectsOptional

Response

Broadcast fully attempted, with send/failed counts

dataobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error