usend Docs
API endpoints

Broadcasts

Create, update, test, send and delete broadcasts.

See Broadcasts for placeholders, unsubscribe handling and staged sending.

The broadcast object

JSON
{
  "object": "broadcast",
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794",
  "name": "October update",
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "from": "Acme <[email protected]>",
  "subject": "What is new in October",
  "reply_to": [],
  "html": "<p>Hi {{{FIRST_NAME|there}}},</p>",
  "text": "",
  "status": "sent",
  "created_at": "2026-10-11T08:00:00.000Z",
  "scheduled_at": null,
  "sent_at": "2026-10-11T09:00:04.000Z",
  "stats": {
    "total": 1240,
    "sent": 1240,
    "delivered": 1212,
    "bounced": 9,
    "opened": 530,
    "clicked": 121,
    "unsubscribed": 4
  }
}

status is draft, queued, sending, sent, paused or failed. segment_id and audience_id always have the same value.

Create a broadcast

POST /broadcasts

Creates a draft.

NameTypeRequiredDescription
segment_idstringYesThe segment (audience) to send to. audience_id is also accepted.
fromstringYesSender on a verified domain.
subjectstringNoRequired before sending. Supports placeholders.
htmlstringNoHTML body. html or text is required before sending.
textstringNoPlain-text body.
reply_tostring | string[]NoReply-to addresses.
namestringNoA name for your reference.
cURL
curl -X POST https://api.usend.et/broadcasts \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
    "from": "Acme <[email protected]>",
    "subject": "What is new in October",
    "html": "<p>Hi {{{FIRST_NAME|there}}},</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
    "name": "October update"
  }'
Response
{ "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }

Retrieve a broadcast

GET /broadcasts/{id}

cURL
curl https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  -H "Authorization: Bearer us_123456789"

Returns the broadcast object.

List broadcasts

GET /broadcasts

cURL
curl https://api.usend.et/broadcasts \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    { "object": "broadcast", "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794", "name": "October update", "status": "sent", "...": "..." }
  ]
}

Each item is a full broadcast object. Broadcasts are not paginated.

Update a broadcast

PATCH /broadcasts/{id}

Updates a draft. Takes the same fields as create, all optional. Fails with 422 when the broadcast is not a draft. Returns the updated broadcast object.

cURL
curl -X PATCH https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "October: three new features" }'

Send a test

POST /broadcasts/{id}/test

Sends one copy with sample placeholder values and a [Test] subject prefix. It counts toward your quota and follows the sandbox rules.

NameTypeRequiredDescription
tostring | string[]YesTest recipients.
cURL
curl -X POST https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/test \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "to": "[email protected]" }'
Response
{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }

The returned id is the ID of the test email.

Send a broadcast

POST /broadcasts/{id}/send

Sends a draft now or at scheduled_at. Requires production access, broadcasts on your plan, a verified from domain and enough quota for the audience's subscribed contacts.

NameTypeRequiredDescription
scheduled_atstringNoISO 8601 or a phrase like in 1 hour or tomorrow at 9am (UTC), up to 30 days ahead. Omit to send now.
cURL
curl -X POST https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/send \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-12T09:00:00Z" }'
Response
{ "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }

Fails with 422 if the broadcast was already sent or scheduled, 403 forbidden in the sandbox or when broadcasts are not on your plan, and 429 when the audience does not fit in your quota.

Delete a broadcast

DELETE /broadcasts/{id}

Deletes a draft. Fails with 422 when the broadcast is not a draft.

cURL
curl -X DELETE https://api.usend.et/broadcasts/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  -H "Authorization: Bearer us_123456789"
Response
{ "object": "broadcast", "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794", "deleted": true }