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"
POST/v1/audiences/subscribe/:token

Subscribe to an audience

This endpoint allows you to subscribe an email address to an audience. If not in contacts, it will be added to contacts too.

You can call this endpoint from anywhere you want. To get the token you need to go to the audience page and click on "Subscribe URL" button in the top right corner.

Required attributes

  • Name
    email
    Type
    string
    Description

    The email address to subscribe.

  • Name
    first_name
    Type
    string
    Description

    The first name of the subscriber.

  • Name
    last_name
    Type
    string
    Description

    The last name of the subscriber.

  • Name
    custom_fields
    Type
    object
    Description

    Custom fields to add to the subscriber.
    Example: {'custom_field_key':'custom_field_value'}

Request

POST
/v1/audiences/subscribe/:token
curl -X POST https://api.emailit.com/v1/audiences/subscribe/:token \
  -H "Authorization: Bearer {api_key}"
  -H "Content-Type: application/json"
  -d $'{
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "custom_fields": {"custom_field_key": "custom_field_value"}
  }'

Was this page helpful?