Audiences

Audiences are a core part of Emailit for Marketers On this page, we'll dive into the different audience endpoints you can use to manage audiences programmatically. We'll look at how to query, create, update, and delete audiences.

The audience model

The audience model contains all the information about your audience.

Properties

Name
id
Type
string
Description
Unique identifier for the audience.
Name
name
Type
string
Description
Name of the audience.
Name
subcribers_count
Type
integer
Description
Number of subscribers in the audience.
Name
created_at
Type
date
Description
The timestamp of when the audience was created.
Name
updated_at
Type
date
Description
The timestamp of when the audience was last updated.

GET/v1/audiences

List all audiences

This endpoint allows you to retrieve a paginated list of all your audiences. By default, a maximum of 25 audiences are shown per page.

Optional attributes

Name
per_page
Type
integer
Description
Limit the number of audiences returned.
Name
page
Type
integer
Description
The page number to retrieve.
Name
filter[name]
Type
string
Description
Filter audiences by name.

Request

GET

/v1/audiences

curl -G https://api.emailit.com/v1/audiences \
   -H 'Authorization: Bearer {api_key}' \
   -H 'Content-Type: application/json' \
   -d $'{
     "per_page": 25,
     "page": 1,
     "filter[name]": "My Audience"
   }'

Response

{
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      "name": "My Audience",
      "subscribers_count": 100,
      "created_at": "2024-09-26T08:16:03.000000Z",
      "updated_at": "2024-09-26T08:16:03.000000Z"
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

POST/v1/audiences

Create an audience

This endpoint allows you to add a new audience to your account. To add a audience, you must provide its name.

Required attributes

Name
name
Type
string
Description
The name for the audience.

Request

POST

/v1/audiences

curl https://api.emailit.com/v1/audiences \
  -H "Authorization: Bearer {api_key}" \
  -H 'Content-Type: application/json' \
  -d $'{
    "name": "My Audience"
  }'

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "My Audience",
  "subscribers_count": 0,
  "created_at": "2024-09-26T08:16:03.000000Z",
  "updated_at": "2024-09-26T08:16:03.000000Z"
}

GET/v1/audiences/:id

Retrieve an audience

This endpoint allows you to retrieve a audience by providing their id. Refer to the list at the top of this page to see which properties are included with audience objects.

Request

GET

/v1/audiences/WAz8eIbvDR60rouK

curl https://api.emailit.com/v1/audiences/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json",

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "My Audience",
  "subscribers_count": 0,
  "created_at": "2024-09-26T08:16:03.000000Z",
  "updated_at": "2024-09-26T08:16:03.000000Z"
}

PUT/v1/audiences/:id

Update an audience

This endpoint allows you to perform an update on an audience. Currently, the only attribute that can be updated on audiences is the name attribute.

Optional attributes

Name
name
Type
string
Description
The name of the audience.

Request

PUT

/v1/audiences/WAz8eIbvDR60rouK

curl -X PUT https://api.emailit.com/v1/audiences/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d $'{
    "name": "My Audience"
  }'

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "My Audience",
  "subscribers_count": 0,
  "created_at": "2024-09-26T08:16:03.000000Z",
  "updated_at": "2024-09-26T08:16:03.000000Z"
}

DELETE/v1/audiences/:id

Delete an audience

This endpoint allows you to delete an audience. There always have to be at least one audience in your account.

Request

DELETE

/v1/audiences/WAz8eIbvDR60rouK

curl -X DELETE https://api.emailit.com/v1/audiences/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {api_key}"
  -H "Content-Type: application/json"