usend Docs
API endpoints

Audiences

Manage audiences and the contacts in each audience.

An audience is a list of contacts you can send broadcasts to. Audiences and segments are the same resource with the same IDs. See Contacts and segments.

Create an audience

POST /audiences

NameTypeRequiredDescription
namestringYesThe audience name.
cURL
curl -X POST https://api.usend.et/audiences \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'
Response
{ "object": "audience", "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "name": "Newsletter" }

Retrieve an audience

GET /audiences/{id}

cURL
curl https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "audience",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Newsletter",
  "created_at": "2026-10-11T08:00:00.000Z",
  "contact_count": 1240
}

List audiences

GET /audiences

cURL
curl https://api.usend.et/audiences \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "object": "audience",
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Newsletter",
      "created_at": "2026-10-11T08:00:00.000Z",
      "contact_count": 1240
    }
  ]
}

Delete an audience

DELETE /audiences/{id}

Deletes the audience and its contacts. Fails with 409 conflict while a broadcast uses it.

cURL
curl -X DELETE https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf \
  -H "Authorization: Bearer us_123456789"
Response
{ "object": "audience", "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf", "deleted": true }

Create a contact in an audience

POST /audiences/{audience_id}/contacts

NameTypeRequiredDescription
audience_idstringYesThe audience ID (path).
emailstringYesThe contact's email address. Stored in lowercase.
first_namestringNoFirst name.
last_namestringNoLast name.
unsubscribedbooleanNoDefault false.
cURL
curl -X POST https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "first_name": "Ann", "last_name": "Lee" }'
Response
{ "object": "contact", "id": "e169aa45-1ecf-4183-9955-b1499d5701d3" }

An address that is already in the audience fails with 409 conflict.

Retrieve a contact in an audience

GET /audiences/{audience_id}/contacts/{id_or_email}

cURL
curl https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "contact",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "[email protected]",
  "first_name": "Ann",
  "last_name": "Lee",
  "unsubscribed": false,
  "created_at": "2026-10-11T08:10:00.000Z"
}

List contacts in an audience

GET /audiences/{audience_id}/contacts

Paginated with limit, after and before.

cURL
curl "https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts?limit=50" \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "[email protected]",
      "first_name": "Ann",
      "last_name": "Lee",
      "unsubscribed": false,
      "created_at": "2026-10-11T08:10:00.000Z"
    }
  ],
  "has_more": false
}

Update a contact in an audience

PATCH /audiences/{audience_id}/contacts/{id_or_email}

NameTypeRequiredDescription
first_namestringNoFirst name.
last_namestringNoLast name.
unsubscribedbooleanNoUnsubscribe or resubscribe the contact in this audience.
cURL
curl -X PATCH https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "unsubscribed": true }'

Returns the updated contact.

Delete a contact from an audience

DELETE /audiences/{audience_id}/contacts/{id_or_email}

cURL
curl -X DELETE https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts/[email protected] \
  -H "Authorization: Bearer us_123456789"
Response
{ "object": "contact", "id": "e169aa45-1ecf-4183-9955-b1499d5701d3", "deleted": true }

Import contacts from CSV

POST /audiences/{audience_id}/contacts/import

NameTypeRequiredDescription
audience_idstringYesThe audience ID (path).
csvstringYesCSV text. With a header row, the email, first_name and last_name columns are matched by name; without one, columns are read in that order.
cURL
curl -X POST https://api.usend.et/audiences/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts/import \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "csv": "email,first_name,last_name\[email protected],Ann,Lee\[email protected],Ben,Okafor" }'
Response
{ "imported": 2, "skipped": 0 }

Invalid addresses and addresses already in the audience are counted in skipped.