Subscribers

Add, update and remove the subscribers of an audience.

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

POST/audiences/{audience_id}/subscribers
GET/audiences/{audience_id}/subscribers/{id}
POST/audiences/{audience_id}/subscribers/{id}
GET/audiences/{audience_id}/subscribers
POST/audiences/{audience_id}/subscribers/bulk
DEL/audiences/{audience_id}/subscribers/{id}

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.

With double_opt_in, the person gets the audience’s double opt-in email and joins when they click it, so the response is 202 and no subscriber exists yet.

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.

double_opt_inbooleandefault: false

Send the double opt-in email instead of subscribing right away. The audience must have double opt-in on, or the request returns 422. A person who is already subscribed gets 409 as usual.

send_confirmation_emailbooleandefault: false

Send the audience’s confirmation email after subscribing, when the audience has it on.

Returns

Returns 201 with the subscriber object, or 200 when an unsubscribed contact was subscribed again. With double_opt_in, returns 202 with object: "subscriber_confirmation", status: "pending", audience_id, contact_id and email. If the double opt-in email can’t be sent, the request returns 422 with a code such as unverified_domain or insufficient_credits.

POST/audiences/{audience_id}/subscribers

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", {
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
})

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.CreateSubscriberRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})

Rust

use emailit::Emailit;
use emailit::types::CreateSubscriberParams;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  CreateSubscriberParams::new("ada@example.com")
    .with_first_name("Ada")
    .with_last_name("Lovelace")
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  SubscriberCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new SubscriberCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);

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"
}

JSON

{
  "object": "subscriber_confirmation",
  "status": "pending",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "message": "A double opt-in email was sent. They join the audience when they click its link."
}

JSON

{
  "error": "Audience not found"
}

JSON

{
  "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"
  }
}

JSON

{
  "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.

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

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"
}

JSON

{
  "error": "Subscriber not found"
}

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', {
  first_name: 'Augusta',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", {
  "first_name": "Augusta",
})

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  first_name: "Augusta"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", &emailit.UpdateSubscriberRequest{
  FirstName: "Augusta",
})

Rust

use emailit::Emailit;
use emailit::types::UpdateSubscriberParams;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", UpdateSubscriberParams {
  first_name: Some("Augusta".into()),
  ..Default::default()
}).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  SubscriberUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", new SubscriberUpdateOptions {
  FirstName = "Augusta",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

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"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}

JSON

{
  "error": "Subscriber not found"
}

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.

engagementstring

unengaged for subscribers who count as unengaged in the audience’s window, engaged for the rest. Combine with subscribed=true to leave out people who already unsubscribed.

searchstring

Case-insensitive match on the email address, first name or last name.

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
`subscribed_at`	date	When the subscription last started.
`last_engaged_at`	date	The contact’s latest open or click. Empty values sort last.
`created_at`	date	When the contact joined the audience.

Every key is also a sort key.

Returns

dataobject[]

The subscriber objects on this page. In lists, each one also has last_opened_at, last_clicked_at and last_engaged_at (the contact’s latest open, click and either, or null) and unengaged.

total_recordsinteger

The number of subscribers that match.

next_page_urlstring | null

Path of the next page, or null. It keeps subscribed and engagement 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

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscribers = await emailit.subscribers.list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

PHP

$emailit = Emailit::client('your_api_key');

$subscribers = $emailit->subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscribers, err := client.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let subscribers = emailit.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", None).await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscribers = emailit.subscribers().list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscribers = emailit.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscribers = Emailit::subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

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,
      "last_opened_at": "2026-10-06T08:14:02.000000Z",
      "last_clicked_at": null,
      "last_engaged_at": "2026-10-06T08:14:02.000000Z",
      "unengaged": false,
      "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",
      "last_opened_at": null,
      "last_clicked_at": null,
      "last_engaged_at": null,
      "unengaged": false,
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

JSON

{
  "error": "Audience not found"
}

Bulk update subscribers

Subscribes, unsubscribes or removes many subscribers of one audience.

POST/audiences/{audience_id}/subscribers/bulk

Requires a full API key. Pick the subscribers by ids, or set all_matching to act on everyone matching the filters, up to 10,000 people. Each change fires the same event as changing one subscriber: subscriber.updated for subscribe and unsubscribe, subscriber.deleted for delete. Unsubscribing keeps people on the list with subscribed: false; deleting removes their membership and keeps the contacts. See Bulk actions.

Path parameters

audience_idstringrequired

The audience ID (aud_…) or its name.

Body parameters

actionstringrequired

subscribe, unsubscribe or delete.

idsstring[]

Subscriber IDs (sub_…), up to 1,000. All must belong to the audience, or nothing changes and the request returns 404 with the missing IDs.

all_matchingbooleandefault: false

Act on every subscriber matching the filters below instead of ids. More than 10,000 matches return 422.

engagementstring

With all_matching: unengaged or engaged. See Unengaged contacts.

subscribedboolean

With all_matching: only subscribed (true) or unsubscribed (false) people.

searchstring

With all_matching: case-insensitive match on the email address, first name or last name.

Returns

objectstring

Always subscriber_bulk.

actionstring

The action you sent.

audience_idstring

The audience ID.

processedinteger

How many subscribers were selected.

changedinteger

How many changed. Subscribing someone who is already subscribed doesn’t count.

POST/audiences/{audience_id}/subscribers/bulk

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'unsubscribe',
    all_matching: true,
    engagement: 'unengaged',
    subscribed: true
  })
});

const { changed } = await response.json();

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "unsubscribe", "all_matching": true, "engagement": "unengaged", "subscribed": true}'

JSON

{
  "object": "subscriber_bulk",
  "action": "unsubscribe",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "processed": 212,
  "changed": 212
}

JSON

{
  "error": "One or more subscribers were not found",
  "missing": ["sub_4KnmYprkoMRytdkm3tAHIfPW0Vh"]
}

JSON

{
  "error": "More than 10000 subscribers match. Narrow the filter and try again."
}

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.subscribers.delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

$emailit = Emailit::client('your_api_key');

$emailit->subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.subscribers().delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

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
}

JSON

{
  "error": "Subscriber not found"
}