Audiences & contacts

Manage audiences and the contacts you send broadcasts to.

An audience is a list of contacts you send broadcasts to. Contacts belong to one audience; the same email address can be a contact in several audiences. All endpoints require a full_access key.

Create an audience

POST/api/v1/audiences

Body

namestringrequired: 1–200 characters.

# Create an audience
curl -X POST 'https://api.bytesms.com/api/v1/audiences' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Newsletter"}'

Response

{
  "object": "audience",
  "id": "cmg4p3v1e0006l8v9k8d2m5nb",
  "name": "Newsletter"
}

The number of audiences is limited on the free Marketing plan (403 plan_limit_exceeded, code: segment_limit_reached).

List, retrieve and delete audiences

GET/api/v1/audiences

GET/api/v1/audiences/{audience_id}

DELETE/api/v1/audiences/{audience_id}

GET /v1/audiences

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "audience",
      "id": "cmg4p3v1e0006l8v9k8d2m5nb",
      "name": "Newsletter",
      "created_at": "2026-09-28T09:55:00.000Z"
    }
  ]
}

DELETE /v1/audiences/{audience_id}

{
  "object": "audience",
  "id": "cmg4p3v1e0006l8v9k8d2m5nb",
  "deleted": true
}

Create a contact

POST/api/v1/audiences/{audience_id}/contacts

Body

emailstringrequired: A valid email address (stored lower-cased). Unique per audience.
first_namestring: ≤ 200 characters.
last_namestring: ≤ 200 characters.
unsubscribedbooleandefault false: Unsubscribed contacts are skipped when a broadcast is sent.
propertiesobject: Custom fields for personalisation, e.g. { "plan": "pro" }. Values are strings (truncated to 1,000 characters), numbers or booleans; at most 100 per contact. Keys are normalised to lower-case snake_case and registered as workspace contact properties.

# Create a contact
curl -X POST 'https://api.bytesms.com/api/v1/audiences/cmg4p3v1e0006l8v9k8d2m5nb/contacts' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","properties":{"plan":"pro","seats":5}}'

Response

{
  "object": "contact",
  "id": "cmg4p7x4f0007l8v9t6a9q1zc"
}

A duplicate email is 409 validation_error. Contacts are limited by your Marketing plan (403 plan_limit_exceeded, code: contact_limit_reached).

Retrieve a contact

GET/api/v1/audiences/{audience_id}/contacts/{contact_id_or_email}

Look a contact up by id or by email address.

# Retrieve a contact
curl -X GET 'https://api.bytesms.com/api/v1/audiences/cmg4p3v1e0006l8v9k8d2m5nb/contacts/[email protected]' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx'

Response

{
  "object": "contact",
  "id": "cmg4p7x4f0007l8v9t6a9q1zc",
  "audience_id": "cmg4p3v1e0006l8v9k8d2m5nb",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "unsubscribed": false,
  "properties": {
    "plan": "pro",
    "seats": 5
  },
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z"
}

List contacts

GET/api/v1/audiences/{audience_id}/contacts

Query

limitintegerdefault 100: Page size, 1–500.
pageintegerdefault 1: Page number (newest first). has_more tells you if there is another page.

# List contacts
curl -X GET 'https://api.bytesms.com/api/v1/audiences/cmg4p3v1e0006l8v9k8d2m5nb/contacts?limit=100&page=1' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx'

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "cmg4p7x4f0007l8v9t6a9q1zc",
      "audience_id": "cmg4p3v1e0006l8v9k8d2m5nb",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "unsubscribed": false,
      "properties": {
        "plan": "pro",
        "seats": 5
      },
      "created_at": "2026-09-28T10:00:00.000Z",
      "updated_at": "2026-09-28T10:00:00.000Z"
    }
  ]
}

Update a contact

PATCH/api/v1/audiences/{audience_id}/contacts/{contact_id_or_email}

Same fields as create, all optional. properties are merged into the existing ones. Returns { object: "contact", id }.

# Unsubscribe a contact
curl -X PATCH 'https://api.bytesms.com/api/v1/audiences/cmg4p3v1e0006l8v9k8d2m5nb/contacts/[email protected]' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"unsubscribed":true}'

Delete a contact

DELETE/api/v1/audiences/{audience_id}/contacts/{contact_id_or_email}

Response

{
  "object": "contact",
  "contact": "cmg4p7x4f0007l8v9t6a9q1zc",
  "deleted": true
}

CSV import

Bulk import from CSV (up to 5 MB) is available in the dashboard under Audience → Import.