API Reference
Broadcasts
Send email campaigns to audiences. Schedule broadcasts for later or send immediately.
Overview
Broadcasts allow you to send emails to all contacts in an audience. You can schedule them for a specific time or save as drafts for later editing.
Mass Sending
Send to entire audiences at once
Scheduling
Schedule sends for optimal timing
Analytics
Track opens, clicks, and bounces
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/broadcasts | Create a new broadcast |
| GET | /v1/broadcasts | List all broadcasts |
| GET | /v1/broadcasts/:id | Get a specific broadcast |
| PATCH | /v1/broadcasts/:id | Update a draft/scheduled broadcast |
| DELETE | /v1/broadcasts/:id | Delete a broadcast |
Create Broadcast
Create a new broadcast to send to an audience.
terminal
curl -X POST "https://www.unosend.co/api/v1/broadcasts" \
-H "Authorization: Bearer un_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "March Newsletter",
"from": "Newsletter <newsletter@yourdomain.com>",
"subject": "Your Weekly Update - March Edition",
"html": "<h1>Hello!</h1><p>Here are this week'"'"'s updates...</p>",
"audience_id": "550e8400-e29b-41d4-a716-446655440000"
}'With Template
terminal
curl -X POST "https://www.unosend.co/api/v1/broadcasts" \
-H "Authorization: Bearer un_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Launch",
"from": "hello@yourdomain.com",
"subject": "Introducing Our New Feature",
"template_id": "550e8400-e29b-41d4-a716-446655440001",
"audience_id": "550e8400-e29b-41d4-a716-446655440000"
}'Scheduled Broadcast
terminal
curl -X POST "https://www.unosend.co/api/v1/broadcasts" \
-H "Authorization: Bearer un_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Friday Digest",
"from": "digest@yourdomain.com",
"subject": "Your Weekly Digest",
"html": "<p>Here'"'"'s your digest...</p>",
"audience_id": "550e8400-e29b-41d4-a716-446655440000",
"scheduled_at": "2024-03-29T09:00:00Z"
}'Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Required | Internal name for the broadcast |
from | string | Required | Sender email (must be verified domain) |
subject | string | Required | Email subject line |
html | string | Optional | HTML content (or use template_id) |
text | string | Optional | Plain text fallback |
audience_id | string | Optional | Target audience UUID |
template_id | string | Optional | Template UUID to use |
scheduled_at | string | Optional | ISO 8601 datetime for scheduled send |
Response
response.json
{
"id": "brd_550e8400e29b41d4a716446655440000",
"name": "March Newsletter",
"from": "Newsletter <newsletter@yourdomain.com>",
"subject": "Your Weekly Update - March Edition",
"status": "draft",
"audience_id": "550e8400-e29b-41d4-a716-446655440000",
"total_recipients": 1250,
"scheduled_at": null,
"created_at": "2024-03-25T10:30:00Z"
}List Broadcasts
Retrieve all broadcasts for your organization.
terminal
curl "https://www.unosend.co/api/v1/broadcasts" \
-H "Authorization: Bearer un_xxxxxxxx"Response
response.json
{
"data": [
{
"id": "brd_xxx1",
"name": "March Newsletter",
"from": "newsletter@yourdomain.com",
"subject": "Your Weekly Update",
"status": "sent",
"audience_id": "aud_xxx",
"total_recipients": 1250,
"sent_count": 1248,
"scheduled_at": null,
"sent_at": "2024-03-25T10:30:00Z",
"created_at": "2024-03-24T15:00:00Z"
},
{
"id": "brd_xxx2",
"name": "Product Launch",
"from": "hello@yourdomain.com",
"subject": "Introducing Our New Feature",
"status": "scheduled",
"audience_id": "aud_xxx",
"total_recipients": 5000,
"sent_count": 0,
"scheduled_at": "2024-04-01T09:00:00Z",
"sent_at": null,
"created_at": "2024-03-26T10:00:00Z"
}
]
}Get Broadcast
Retrieve details of a specific broadcast.
terminal
curl "https://www.unosend.co/api/v1/broadcasts/brd_xxx" \
-H "Authorization: Bearer un_xxxxxxxx"Response
response.json
{
"id": "brd_xxx",
"name": "March Newsletter",
"from": "Newsletter <newsletter@yourdomain.com>",
"subject": "Your Weekly Update - March Edition",
"html": "<h1>Hello!</h1><p>Here are this week's updates...</p>",
"text": "Hello! Here are this week's updates...",
"status": "sent",
"audience_id": "aud_xxx",
"template_id": null,
"total_recipients": 1250,
"sent_count": 1248,
"scheduled_at": null,
"sent_at": "2024-03-25T10:30:00Z",
"created_at": "2024-03-24T15:00:00Z",
"updated_at": "2024-03-25T10:30:00Z"
}Update Broadcast
Update a draft or scheduled broadcast. Cannot update broadcasts that are sending or already sent.
terminal
curl -X PATCH "https://www.unosend.co/api/v1/broadcasts/brd_xxx" \
-H "Authorization: Bearer un_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"subject": "Updated: Your Weekly Update",
"scheduled_at": "2024-04-01T14:00:00Z"
}'Response
response.json
{
"id": "brd_xxx",
"name": "March Newsletter",
"subject": "Updated: Your Weekly Update",
"status": "scheduled",
"scheduled_at": "2024-04-01T14:00:00Z",
"updated_at": "2024-03-26T10:00:00Z"
}Note: You can only update broadcasts with status draft or scheduled. Once a broadcast is sending or sent, it cannot be modified.
Delete Broadcast
Delete a broadcast. Cannot delete while actively sending.
terminal
curl -X DELETE "https://www.unosend.co/api/v1/broadcasts/brd_xxx" \
-H "Authorization: Bearer un_xxxxxxxx"Response
response.json
{
"message": "Broadcast deleted successfully"
}Broadcast Statuses
| Status | Description |
|---|---|
| draft | Saved but not scheduled or sent |
| scheduled | Scheduled to send at a specific time |
| sending | Currently being sent to recipients |
| sent | Successfully sent to all recipients |
| failed | Failed to send (check error details) |
| cancelled | Cancelled before sending completed |
Best Practices
1
Test before sending
Send a test email to yourself before broadcasting to your entire audience.
2
Use templates
Create reusable templates for consistent branding and faster creation.
3
Schedule for optimal times
Schedule broadcasts when your audience is most likely to engage.
4
Monitor delivery metrics
Check open rates, click rates, and bounces to optimize future campaigns.