Audiences

Audiences let you store and organise contacts per domain. Each domain can have multiple audiences. All audience endpoints require a full-access API key.

GET/api/v1/audiencesfull access

List audiences

Returns all audiences for a domain. The domain query parameter is required.

Query Parameters

domainstringrequired

The domain whose audiences you want to list.

Response

dataAudience[]

Array of audience objects.

totalnumber

Total number of audiences for this domain.

Request (curl)

curl "https://sendexapi.com/api/v1/audiences?domain=example.com" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e1",
      "name": "Newsletter",
      "domain": "example.com",
      "contact_count": 1240,
      "created_at": "2025-02-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

POST/api/v1/audiencesfull access

Create an audience

Creates a new audience for a verified domain on your account.

Request Body

namestringrequired

Display name for the audience.

domainstringrequired

The domain this audience belongs to. Must be a verified domain on your account.

Response

idstring

Unique audience ID.

namestring

Audience name.

domainstring

Domain this audience belongs to.

contact_countnumber

Always 0 for newly created audiences.

created_atISO 8601

Creation timestamp.

Request (curl)

curl -X POST https://sendexapi.com/api/v1/audiences \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter",
    "domain": "example.com"
  }'

Response

HTTP/1.1 201 Created

{
  "id": "66f1a2b3c4d5e6f7a8b9c0e1",
  "name": "Newsletter",
  "domain": "example.com",
  "contact_count": 0,
  "created_at": "2025-02-01T00:00:00.000Z"
}

GET/api/v1/audiences/:idfull access

Retrieve an audience

Returns a single audience along with its current contact count.

Response

idstring

Audience ID.

namestring

Audience name.

domainstring

Domain this audience belongs to.

contact_countnumber

Number of contacts in this audience.

created_atISO 8601

Creation timestamp.

Request (curl)

curl "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "id": "66f1a2b3c4d5e6f7a8b9c0e1",
  "name": "Newsletter",
  "domain": "example.com",
  "contact_count": 1240,
  "created_at": "2025-02-01T00:00:00.000Z"
}

DELETE/api/v1/audiences/:idfull access

Delete an audience

Permanently deletes an audience and all of its contacts. This action cannot be undone.

Response

idstring

ID of the deleted audience.

Request (curl)

curl -X DELETE "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "id": "66f1a2b3c4d5e6f7a8b9c0e1"
}

GET/api/v1/audiences/:id/contactsfull access

List contacts

Returns a paginated list of contacts in an audience.

Query Parameters

limitnumberoptional

Number of contacts to return (1–200). Default 50.

offsetnumberoptional

Pagination offset. Default 0.

Response

dataContact[]

Array of contact objects.

totalnumber

Total contacts matching the query.

limitnumber

Limit applied.

offsetnumber

Offset applied.

Request (curl)

curl "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1/contacts?limit=50" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0f1",
      "email": "[email protected]",
      "first_name": "Alice",
      "last_name": "Smith",
      "subscribed": true,
      "created_at": "2025-02-05T08:00:00.000Z"
    }
  ],
  "total": 1240,
  "limit": 50,
  "offset": 0
}

POST/api/v1/audiences/:id/contactsfull access

Add a contact

Adds or updates a contact in an audience. If a contact with the same email already exists it is updated in place (upsert).

Request Body

emailstringrequired

Email address. Unique within the audience.

first_namestringoptional

Contact first name.

last_namestringoptional

Contact last name.

subscribedbooleanoptional

Whether the contact is subscribed. Defaults to true.

Response

idstring

Contact ID.

emailstring

Email address.

first_namestring

First name.

last_namestring

Last name.

subscribedboolean

Subscription status.

created_atISO 8601

When the contact was first added.

Request (curl)

curl -X POST "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1/contacts" \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Alice",
    "last_name": "Smith",
    "subscribed": true
  }'

Response

HTTP/1.1 201 Created

{
  "id": "66f1a2b3c4d5e6f7a8b9c0f1",
  "email": "[email protected]",
  "first_name": "Alice",
  "last_name": "Smith",
  "subscribed": true,
  "created_at": "2025-02-05T08:00:00.000Z"
}

GET/api/v1/audiences/:id/contacts/:contactIdfull access

Retrieve a contact

Returns a single contact by ID.

Response

idstring

Contact ID.

emailstring

Email address.

first_namestring

First name.

last_namestring

Last name.

subscribedboolean

Subscription status.

created_atISO 8601

When the contact was added.

Request (curl)

curl "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1/contacts/66f1a2b3c4d5e6f7a8b9c0f1" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "id": "66f1a2b3c4d5e6f7a8b9c0f1",
  "email": "[email protected]",
  "first_name": "Alice",
  "last_name": "Smith",
  "subscribed": true,
  "created_at": "2025-02-05T08:00:00.000Z"
}

PATCH/api/v1/audiences/:id/contacts/:contactIdfull access

Update a contact

Partially updates a contact. Only supplied fields are changed.

Request Body

first_namestringoptional

Updated first name.

last_namestringoptional

Updated last name.

subscribedbooleanoptional

Update subscription status.

Response

idstring

Contact ID.

emailstring

Email address.

first_namestring

First name.

last_namestring

Last name.

subscribedboolean

Subscription status.

created_atISO 8601

Original creation timestamp.

Request (curl)

curl -X PATCH "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1/contacts/66f1a2b3c4d5e6f7a8b9c0f1" \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed": false
  }'

Response

{
  "id": "66f1a2b3c4d5e6f7a8b9c0f1",
  "email": "[email protected]",
  "first_name": "Alice",
  "last_name": "Smith",
  "subscribed": false,
  "created_at": "2025-02-05T08:00:00.000Z"
}

DELETE/api/v1/audiences/:id/contacts/:contactIdfull access

Delete a contact

Permanently removes a contact from an audience.

Response

idstring

ID of the deleted contact.

Request (curl)

curl -X DELETE "https://sendexapi.com/api/v1/audiences/66f1a2b3c4d5e6f7a8b9c0e1/contacts/66f1a2b3c4d5e6f7a8b9c0f1" \
  -H "Authorization: Bearer sk_live_XXXX"

Response

{
  "id": "66f1a2b3c4d5e6f7a8b9c0f1"
}