Send Email broadcast | Teekrr | API Documentation

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)

The full recipientCount × emailRate is reserved at broadcast creation
Each successful send (accepted by the email provider) is settled
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.

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 <Warning> **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.` </Warning> ## 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.

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.

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

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)

The full recipientCount × emailRate is reserved at broadcast creation
Each successful send (accepted by the email provider) is settled
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.

$	curl -X POST https://api.teekrr.com/email \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"templateName": "welcome_promo_v1",
>	"subject": "Welcome to Teekrr",
>	"type": "quick broadcast",
>	"campaignName": "May 2026 Welcome Promo",
>	"recipients": [
>	"ali@example.com",
>	"fatimah@example.com"
>	]
>	}'

1	{
2	"data": {
3	"broadcastUuid": "00000000-0000-0000-0000-000000000020",
4	"sent": 2,
5	"failed": 0,
6	"total": 2
7	}
8	}