Subscribers
Add, update and remove the subscribers of an audience.
Add a subscriber
Adds a contact to an audience by email address.
/audiences/{audience_id}/subscribersRequires 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_idstringrequiredaud_…) or its name.Body parameters
emailstringrequiredfirst_namestringlast_namestringcustom_fieldsobjectCustom 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.
{
"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"
}{
"error": "Audience not found"
}{
"error": "Contact is already subscribed to this audience",
"existing": {
"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.000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000Z",
"updated_at": "2026-10-01T10:20:31.000Z"
}
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Retrieve a subscriber
Retrieves a contact’s membership in an audience.
/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_idstringrequiredaud_…) or its name.idstringrequiredsub_…) or the contact’s email address, URL-encoded.Returns
Returns the subscriber object.
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject | nullsubscribedbooleantrue if the contact is subscribed to this audience, false if they unsubscribed.subscribed_atstring | nullunsubscribed_atstring | nullnull.created_atstringupdated_atstring{
"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"
}{
"error": "Subscriber not found"
}Update a subscriber
Changes a subscriber’s status in the audience, or the details of its contact.
/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_idstringrequiredaud_…) or its name.idstringrequiredsub_…) or the contact’s email address, URL-encoded.Body parameters
subscribedbooleanfalse to unsubscribe the contact from this audience, true to subscribe them again. The subscriber stays in the audience either way.emailstringfirst_namestringlast_namestringcustom_fieldsobjectReturns
Returns the updated subscriber object. A request without any of these fields returns 400.
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}'{
"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"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}{
"error": "Subscriber not found"
}List subscribers
Returns a page of an audience’s subscribers, newest first.
/audiences/{audience_id}/subscribersRequires a full API key. The list includes contacts who unsubscribed from the audience unless you filter them out with subscribed=true.
Path parameters
audience_idstringrequiredaud_…) or its name.Query parameters
pageintegerdefault: 1limitintegerdefault: 25per_page works too.subscribedstringtrue for subscribed contacts only, false for unsubscribed ones only.searchstringmatchstringdefault: allall or or. How the filters below combine.orderstringdirectionstringasc 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[]next_page_urlstring | nullprevious_page_urlstring | nullnull.usageobjectused (subscribers in the audience), limit (the most your plan allows per audience, or null) and plan.curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-d subscribed=true \
-d limit=100{
"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"
}
}{
"error": "Audience not found"
}Delete a subscriber
Removes a contact from an audience.
/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_idstringrequiredaud_…) or its name.idstringrequiredsub_…) or the contact’s email address, URL-encoded.Returns
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringdeletedbooleantrue.{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"deleted": true
}{
"error": "Subscriber not found"
}