Skip to content
Docs

Add, update and remove the subscribers of an audience.

Base URLhttps://api.emailit.com/v2AuthenticationErrorsRate limits

Add a subscriber

Adds a contact to an audience by email address.

POST/audiences/{audience_id}/subscribers

Requires a full API key. If no contact has this email yet, Emailit creates one. If the contact exists, the names and custom fields you send overwrite its current values. A contact that had unsubscribed from the audience is subscribed again and the response is 200; a contact that’s already subscribed returns 409.

Each audience can hold as many subscribers as your plan allows; past that, the request returns 422 with your usage. Fires subscriber.created, or subscriber.updated and subscriber.resubscribed for a resubscribe.

Path parameters

audience_idstringrequired
The audience ID (aud_…) or its name.

Body parameters

emailstringrequired
The email address to subscribe. Stored in lowercase.
first_namestring
The contact’s first name.
last_namestring
The contact’s last name.
custom_fieldsobject

Custom field values by key, such as {"company": "Analytical Engines"}. Replaces the contact’s existing custom fields.

Returns

Returns 201 with the subscriber object, or 200 when an unsubscribed contact was subscribed again.

POST/audiences/{audience_id}/subscribers
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines" }
  }'
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": true,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": null,
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}

Retrieve a subscriber

Retrieves a contact’s membership in an audience.

GET/audiences/{audience_id}/subscribers/{id}

Requires a full API key. A subscriber links one contact to one audience. The email, names and custom fields belong to the contact, and subscribed belongs to this audience only.

Path parameters

audience_idstringrequired
The audience ID (aud_…) or its name.
idstringrequired
The subscriber ID (sub_…) or the contact’s email address, URL-encoded.

Returns

Returns the subscriber object.

objectstring
Always subscriber.
idstring
The subscriber ID.
audience_idstring
The audience ID.
contact_idstring
The ID of the contact.
emailstring
The contact’s email address.
first_namestring | null
The contact’s first name.
last_namestring | null
The contact’s last name.
custom_fieldsobject | null
The contact’s custom field values.
subscribedboolean
true if the contact is subscribed to this audience, false if they unsubscribed.
subscribed_atstring | null
When the contact last subscribed.
unsubscribed_atstring | null
When the contact unsubscribed, or null.
created_atstring
When the contact joined the audience.
updated_atstring
When the membership last changed.
GET/audiences/{audience_id}/subscribers/{id}
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": true,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": null,
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}

Update a subscriber

Changes a subscriber’s status in the audience, or the details of its contact.

POST/audiences/{audience_id}/subscribers/{id}

Requires a full API key. Send only the fields you want to change. subscribed applies to this audience only. email, first_name, last_name and custom_fields change the contact itself, so the change shows up in every audience the contact belongs to. Fires a subscriber.updated event.

Path parameters

audience_idstringrequired
The audience ID (aud_…) or its name.
idstringrequired
The subscriber ID (sub_…) or the contact’s email address, URL-encoded.

Body parameters

subscribedboolean
false to unsubscribe the contact from this audience, true to subscribe them again. The subscriber stays in the audience either way.
emailstring
A new email address for the contact. Stored in lowercase.
first_namestring
The contact’s first name.
last_namestring
The contact’s last name.
custom_fieldsobject
Custom field values by key. Replaces the contact’s existing custom fields.

Returns

Returns the updated subscriber object. A request without any of these fields returns 400.

POST/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/ada%40example.com \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscribed": false}'
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": false,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": "2026-10-02T08:14:55.000000Z",
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-02T08:14:55.000000Z"
}

List subscribers

Returns a page of an audience’s subscribers, newest first.

GET/audiences/{audience_id}/subscribers

Requires a full API key. The list includes contacts who unsubscribed from the audience unless you filter them out with subscribed=true.

Path parameters

audience_idstringrequired
The audience ID (aud_…) or its name.

Query parameters

pageintegerdefault: 1
The page to return.
limitintegerdefault: 25
Subscribers per page, from 1 to 100. per_page works too.
subscribedstring
true for subscribed contacts only, false for unsubscribed ones only.
matchstringdefault: all
all or or. How the filters below combine.
orderstring
A filter key to sort by.
directionstring
asc or desc.

Filters

Add filters as key.condition=value, for example email.ends_with=@acme.com. See Filtering.

Key Type Notes
email string
first_name string
last_name string
subscribed boolean
created_at date When the contact joined the audience.

Every key is also a sort key.

Returns

dataobject[]
The subscriber objects on this page.
next_page_urlstring | null
Path of the next page, or null. It keeps subscribed but not your other filters. See Pagination.
previous_page_urlstring | null
Path of the previous page, or null.
usageobject
used (subscribers in the audience), limit (the most your plan allows per audience, or null) and plan.
GET/audiences/{audience_id}/subscribers
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
Terminal
curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d subscribed=true \
  -d limit=100
JSON
{
  "data": [
    {
      "object": "subscriber",
      "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "company": "Analytical Engines"
      },
      "subscribed": true,
      "subscribed_at": "2026-10-01T10:20:31.000000Z",
      "unsubscribed_at": null,
      "created_at": "2026-10-01T10:20:31.000000Z",
      "updated_at": "2026-10-01T10:20:31.000000Z"
    },
    {
      "object": "subscriber",
      "id": "sub_4KnmYprkoMRytdkm3tAHIfPW0Vh",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "custom_fields": null,
      "subscribed": false,
      "subscribed_at": "2026-09-28T07:55:02.000000Z",
      "unsubscribed_at": "2026-09-30T18:11:40.000000Z",
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

Delete a subscriber

Removes a contact from an audience.

DELETE/audiences/{audience_id}/subscribers/{id}

Requires a full API key. The contact itself isn’t deleted and stays in its other audiences. To keep a record that someone opted out, unsubscribe them with subscribed: false instead. Fires a subscriber.deleted event.

Path parameters

audience_idstringrequired
The audience ID (aud_…) or its name.
idstringrequired
The subscriber ID (sub_…) or the contact’s email address, URL-encoded.

Returns

objectstring
Always subscriber.
idstring
The ID of the deleted subscriber.
audience_idstring
The audience ID.
contact_idstring
The contact’s ID.
emailstring
The contact’s email address.
deletedboolean
Always true.
DELETE/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "deleted": true
}

Was this page helpful?

Thanks for the feedback.

Thanks, we read every message.