Blasts API
Send bulk messages to your contacts. Create blasts, schedule them, and track delivery.
GET /v1/blasts
List all blasts for your organization. Optionally filter by status.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter: draft, scheduled, sending, completed, failed |
cURL
curl https://api.yoursend.dev/v1/blasts?status=completed \
-H "Authorization: Bearer ys_live_..."
GET /v1/blasts/:id
Get a single blast with full stats.
cURL
curl https://api.yoursend.dev/v1/blasts/bla_abc123 \
-H "Authorization: Bearer ys_live_..."
Response
{
"id": "bla_abc123",
"name": "Summer Sale",
"channel": "email",
"template_id": "tpl_xyz",
"audience_type": "tag",
"audience_filter": { "tag": "customers" },
"status": "completed",
"total_contacts": 1500,
"sent_count": 1500,
"delivered_count": 1485,
"failed_count": 15,
"scheduled_at": null,
"started_at": "2025-06-01T10:00:00Z",
"completed_at": "2025-06-01T10:05:00Z",
"created_at": "2025-06-01T09:50:00Z"
}POST /v1/blasts
Create a new blast. Set scheduled_at to schedule for later, or omit to create as a draft.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Blast name |
channel | string | Yes | email, sms, voice, whatsapp |
template_id | string | No | Template to use for the blast |
audience_type | string | No | "all" (default) or "tag" |
audience_filter | object | No | Filter object, e.g. { "tag": "vip" } |
scheduled_at | string | No | ISO 8601 datetime to schedule the blast |
ai_best_time | boolean | No | Let AI optimize send time per recipient |
cURL
curl -X POST https://api.yoursend.dev/v1/blasts \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Summer Sale",
"channel": "email",
"template_id": "tpl_xyz",
"audience_type": "tag",
"audience_filter": { "tag": "customers" },
"scheduled_at": "2025-06-01T10:00:00Z"
}'