Send Email broadcast

View as Markdown
Creates an email broadcast, inserts one row per recipient into `email_messages`, atomically reserves credit (prepaid), and dispatches via AWS SES **synchronously** for `quick broadcast`. 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 ## Billing semantics (prepaid clients) 1. The full `recipientCount × emailRate` is **reserved** at broadcast creation 2. Each **successful** send (HTTP 2xx from SES) is **settled** 3. Each **failed** send (non-2xx or thrown error) **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. ## Bounce handling Hard bounces reach your registered webhook URL as a `bounced` event. Suppress these addresses from future broadcasts; SES enforces sender-reputation hygiene.

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.

Request

This endpoint expects an object.
templateNamestringRequired1-512 characters
subjectstringRequired1-200 characters
typeenumRequired
  • quick broadcast — send immediately
  • schedule broadcast — defer; requires scheduledAt
Allowed values:
campaignNamestringOptional1-255 characters
scheduledAtdatetimeOptional
recipientslist of stringsOptional
recipientVariableslist of objectsOptional

Response

Quick broadcast — fully attempted, with send/failed counts

dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error