Audiences

Manage subscriber lists used by campaigns and sign-up forms.

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

POST/audiences
GET/audiences/{id}
POST/audiences/{id}
GET/audiences
POST/audiences/{id}/merge
POST/audiences/bulk
DEL/audiences/{id}

Create an audience

Creates an empty audience.

POST/audiences

Requires a full API key. Add people with Add a subscriber, or by passing the audience ID in audiences when you create a contact. Fires an audience.created event. See Audiences.

Body parameters

namestringrequired

The audience name, such as Newsletter. Must be unique in the workspace.

visibilitystringdefault: private

public lists the audience on the manage subscriptions page for everyone; private only for people subscribed to it.

public_namestring | null

The name subscribers see in emails and on recipient pages. Up to 120 characters. null shows name.

public_descriptionstring | null

One line shown on the manage subscriptions page. Up to 500 characters.

double_opt_inboolean | object

true or false, or an object with any of enabled, redirect_url (an http(s) URL people go to after confirming, or null) and email. email takes from, reply_to, subject, design (default or custom), heading, body, button_label and footer. Fields you leave out keep their stored value. Turning it on needs a from address on a verified sending domain. See Double opt-in.

confirmation_emailboolean | object

true or false, or an object with enabled and email, which takes the same fields as above plus button_url.

unengagedobject

exclude (skip unengaged subscribers in campaigns) and days (30 to 1,825).

Returns

Returns 201 with the new audience, including its settings as described in Retrieve an audience:

objectstring

Always audience.

idstring

The audience ID.

namestring

The audience name.

tokenstring

The token in the audience’s subscribe URL. Keep it secret.

visibilitystring

public or private.

created_atstring

When the audience was created.

updated_atstring

When the audience was last changed.

POST/audiences

JavaScript

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

const audience = await emailit.audiences.create({
  name: 'Newsletter',
});

Python

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

audience = client.audiences.create({
  "name": "Newsletter"
})

PHP

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

$audience = $emailit->audiences()->create([
  'name' => 'Newsletter',
]);

Ruby

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

audience = client.audiences.create(name: "Newsletter")

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

audience, err := client.Audiences.Create(&emailit.CreateAudienceRequest{
  Name: "Newsletter",
})

Rust

use emailit::Emailit;
use emailit::types::CreateAudienceParams;

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

let audience = emailit.audiences.create(
  CreateAudienceParams::new("Newsletter")
).await?;

Java

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().create(
  AudienceCreateParams.builder()
    .setName("Newsletter")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Create(new AudienceCreateOptions {
  Name = "Newsletter",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->create([
  'name' => 'Newsletter',
]);

Terminal

curl -X POST https://api.emailit.com/v2/audiences \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter"}'

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "visibility": "private",
  "public_name": null,
  "public_description": null,
  "double_opt_in": {
    "enabled": false,
    "redirect_url": null,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "button_url": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "source": null
    }
  },
  "unengaged": { "exclude": false, "days": 365 },
  "archived": false,
  "archived_at": null,
  "subscribers_count": 0,
  "created_at": "2026-10-01T10:02:44.613207Z",
  "updated_at": "2026-10-01T10:02:44.613207Z"
}

JSON

{
  "error": "Audience with this name already exists",
  "existing": {
    "object": "audience",
    "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "name": "Newsletter",
    "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
    "subscribers_count": 0,
    "created_at": "2026-10-01T10:02:44.000000Z",
    "updated_at": "2026-10-01T10:02:44.000000Z"
  }
}

Retrieve an audience

Retrieves an audience with its settings, counts and public token.

GET/audiences/{id}

Requires a full API key.

Path parameters

idstringrequired

The audience ID (aud_…) or its exact name, URL-encoded.

Returns

Returns the audience object.

objectstring

Always audience.

idstring

The audience ID.

namestring

The audience name.

tokenstring

The token in the audience’s subscribe URL. Keep it secret: anyone with it can add people to the audience.

visibilitystring

public or private. Public audiences are listed on the manage subscriptions page for everyone; private ones only for people subscribed to them.

public_namestring | null

The name subscribers see, or null to show name.

public_descriptionstring | null

The description shown on the manage subscriptions page.

double_opt_inobject

enabled, redirect_url (where people go after confirming, or null) and email, the double opt-in email with from, reply_to, subject, design (default or custom), heading, body, button_label, footer and source (the MJML of a custom design, or null; lists leave it out). Fields you never set hold the defaults.

confirmation_emailobject

enabled and email, the confirmation email, with the same fields as above plus button_url.

unengagedobject

exclude (whether campaigns skip unengaged subscribers) and days (the window, 365 by default).

archivedboolean

Whether the audience is archived. archived_at holds the time, or null.

subscribers_countinteger

How many contacts are in the audience, including unsubscribed ones.

usageobject

used (the same count), limit (the most subscribers an audience can have on your plan, or null for no limit) and plan. See Limits.

unengaged_countinteger

How many subscribed members count as unengaged right now.

pending_confirmations_countinteger

How many double opt-in requests are waiting for a click, not counting expired ones.

created_atstring

When the audience was created.

updated_atstring

When the audience was last changed.

GET/audiences/{id}

JavaScript

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

const audience = await emailit.audiences.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Python

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

PHP

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

$audience = $emailit->audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Ruby

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

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

audience, err := client.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

Rust

use emailit::Emailit;

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

let audience = emailit.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Terminal

curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "visibility": "public",
  "public_name": "Monthly newsletter",
  "public_description": "Product news and tips, once a month.",
  "double_opt_in": {
    "enabled": true,
    "redirect_url": null,
    "email": {
      "from": "News <news@example.com>",
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "button_url": "",
      "source": null
    }
  },
  "unengaged": { "exclude": true, "days": 365 },
  "archived": false,
  "archived_at": null,
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 1284,
  "unengaged_count": 212,
  "pending_confirmations_count": 3,
  "usage": {
    "used": 1284,
    "limit": 50000,
    "plan": "pro"
  },
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T10:02:44.000000Z"
}

JSON

{
  "error": "Audience not found"
}

Update an audience

Renames an audience or changes its settings.

POST/audiences/{id}

Requires a full API key. Send only the fields you want to change. The ID, token and subscribers don’t change. Fires an audience.updated event.

Path parameters

idstringrequired

The audience ID or its current name.

Body parameters

namestring

The new name. Must be unique in the workspace.

visibilitystring

public lists the audience on the manage subscriptions page for everyone; private only for people subscribed to it.

public_namestring | null

The name subscribers see in emails and on recipient pages. Up to 120 characters. null shows name.

public_descriptionstring | null

One line shown on the manage subscriptions page. Up to 500 characters.

double_opt_inboolean | object

confirmation_emailboolean | object

true or false, or an object with enabled and email, which takes the same fields as above plus button_url.

unengagedobject

exclude (skip unengaged subscribers in campaigns) and days (30 to 1,825).

archivedboolean

true archives the audience, false unarchives it. See Archive an audience.

Setting a custom MJML design with email.source is part of the MJML alpha and returns 403 with error: "mjml_alpha" for API keys.

Returns

Returns the audience with its settings, as in Retrieve an audience. In this response subscribers_count is always 0, and the counts are left out; use Retrieve an audience for them. Invalid settings return 422 with an errors object keyed by field, such as double_opt_in.email.from.

POST/audiences/{id}

JavaScript

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

const audience = await emailit.audiences.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  name: 'Weekly newsletter',
});

Python

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", {
  "name": "Weekly newsletter"
})

PHP

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

$audience = $emailit->audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);

Ruby

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", name: "Weekly newsletter")

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

audience, err := client.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.UpdateAudienceRequest{
  Name: "Weekly newsletter",
})

Rust

use emailit::Emailit;
use emailit::types::UpdateAudienceParams;

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

let audience = emailit.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", UpdateAudienceParams {
  name: Some("Weekly newsletter".into()),
  ..Default::default()
}).await?;

Java

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  AudienceUpdateParams.builder()
    .setName("Weekly newsletter")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new AudienceUpdateOptions {
  Name = "Weekly newsletter",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly newsletter"}'

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Weekly newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "visibility": "public",
  "public_name": "Weekly newsletter",
  "public_description": null,
  "double_opt_in": {
    "enabled": true,
    "redirect_url": null,
    "email": {
      "from": "News <news@example.com>",
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "button_url": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "source": null
    }
  },
  "unengaged": {
    "exclude": false,
    "days": 365
  },
  "archived": false,
  "archived_at": null,
  "subscribers_count": 0,
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T14:31:09.000000Z"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: name, visibility, public_name, public_description, double_opt_in, confirmation_email, unengaged, archived"
}

JSON

{
  "message": "Validation failed.",
  "errors": {
    "double_opt_in.email.from": ["Use an address on a verified sending domain of this workspace."]
  }
}

JSON

{
  "error": "Audience not found"
}

JSON

{
  "error": "Another audience with this name already exists"
}

List audiences

Returns a page of audiences, newest first. Archived audiences are left out unless you ask for them.

GET/audiences

Requires a full API key. List items don’t include the audience token; use Retrieve an audience for it.

Query parameters

pageintegerdefault: 1

The page to return.

limitintegerdefault: 10

Audiences per page, from 1 to 100.

searchstring

Case-insensitive match on the audience name.

archivedstringdefault: false

false for active audiences, true for archived ones only, all for both.

visibilitystring

public or private to list only those.

matchstringdefault: all

all or or. How the filters below combine.

orderstring

name, public_name, visibility, subscribers_count or created_at.

directionstring

asc or desc.

Filters

Add filters as key.condition=value, for example name.contains=news. See Filtering.

Key	Type
`name`	string
`public_name`	string
`visibility`	enum: `public`, `private`
`subscribers_count`	number
`created_at`	date

Returns

dataobject[]

The audiences on this page, each with object, id, name, the settings (visibility, public_name, public_description, double_opt_in, confirmation_email, unengaged, archived, archived_at), subscribers_count, usage, created_at and updated_at. See Retrieve an audience. The email objects in lists leave out source.

total_recordsinteger

The number of audiences that match the search, filters and archived.

next_page_urlstring | null

Path of the next page, or null. See Pagination.

previous_page_urlstring | null

Path of the previous page, or null.

GET/audiences

JavaScript

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

const audiences = await emailit.audiences.list();

Python

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

audiences = client.audiences.list()

PHP

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

$audiences = $emailit->audiences()->list();

Ruby

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

audiences = client.audiences.list

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

audiences, err := client.Audiences.List(nil)

Rust

use emailit::Emailit;

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

let audiences = emailit.audiences.list(None).await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audiences = emailit.audiences().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audiences = emailit.Audiences.List();

PHP

use Emailit\Laravel\Facades\Emailit;

$audiences = Emailit::audiences()->list();

Terminal

curl https://api.emailit.com/v2/audiences \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "data": [
    {
      "object": "audience",
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "visibility": "public",
      "public_name": "Monthly newsletter",
      "public_description": "Product news and tips, once a month.",
      "double_opt_in": {
        "enabled": true,
        "redirect_url": null,
        "email": {
          "from": "News <news@example.com>",
          "reply_to": null,
          "subject": "Confirm your subscription to {{audience_name}}",
          "design": "default",
          "heading": "Please confirm your subscription",
          "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
          "button_label": "Confirm subscription",
          "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm."
        }
      },
      "confirmation_email": {
        "enabled": false,
        "email": {
          "from": "News <news@example.com>",
          "reply_to": null,
          "subject": "You're subscribed to {{audience_name}}",
          "design": "default",
          "heading": "You're subscribed",
          "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
          "button_label": "",
          "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
          "button_url": ""
        }
      },
      "unengaged": {
        "exclude": false,
        "days": 365
      },
      "archived": false,
      "archived_at": null,
      "subscribers_count": 1284,
      "usage": {
        "used": 1284,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-10-01T10:02:44.000000Z",
      "updated_at": "2026-10-01T10:02:44.000000Z"
    },
    {
      "object": "audience",
      "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
      "name": "Customers",
      "visibility": "private",
      "public_name": null,
      "public_description": null,
      "double_opt_in": {
        "enabled": false,
        "redirect_url": null,
        "email": {
          "from": null,
          "reply_to": null,
          "subject": "Confirm your subscription to {{audience_name}}",
          "design": "default",
          "heading": "Please confirm your subscription",
          "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
          "button_label": "Confirm subscription",
          "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm."
        }
      },
      "confirmation_email": {
        "enabled": false,
        "email": {
          "from": null,
          "reply_to": null,
          "subject": "You're subscribed to {{audience_name}}",
          "design": "default",
          "heading": "You're subscribed",
          "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
          "button_label": "",
          "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
          "button_url": ""
        }
      },
      "unengaged": {
        "exclude": false,
        "days": 365
      },
      "archived": false,
      "archived_at": null,
      "subscribers_count": 312,
      "usage": {
        "used": 312,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-09-20T16:45:10.000000Z",
      "updated_at": "2026-09-20T16:45:10.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null
}

Merge audiences

Copies the subscribers of other audiences into this one.

POST/audiences/{id}/merge

Requires a full API key. People who are already on the target audience keep their status there, so nobody who unsubscribed is subscribed again. A person on several of the merged audiences joins with Subscribed on when at least one of them has them subscribed. With delete_sources, the merged audiences are deleted afterwards and campaigns that haven’t finished sending (drafts, scheduled, queued and sending campaigns, and A/B tests waiting for their winner) send to the target instead. If such a campaign included one merged audience and excluded another, the target stays included. Segments that draw from or have a rule on a deleted audience use the target instead, and so do automation triggers, steps, conditions and exit conditions that name it. So do forms that add people to it or offer it as a choice, double opt-in links that haven’t been confirmed yet, and automation runs waiting on a condition about it. Each deletion fires audience.deleted.

Merging doesn’t fire subscriber.* events, start automations or send double opt-in or confirmation emails. If the new subscribers would take the target over your plan’s subscriber limit, nothing is merged and the request returns 422 with your usage. Invalid input, such as merging an audience into itself, also returns 422. See Merge audiences.

Path parameters

idstringrequired

The audience to merge into, by ID or name.

Body parameters

source_idsstring[]required

IDs of the audiences to merge, 1 to 50. Can’t include the target.

delete_sourcesbooleandefault: false

Delete the merged audiences after copying their subscribers.

Returns

objectstring

Always audience_merge.

audienceobject

The target audience: object, id, name and its new subscribers_count.

addedinteger

How many people joined the target.

already_in_audienceinteger

How many people from the merged audiences were already on the target and kept their status.

deleted_source_idsstring[]

The audiences that were deleted, or an empty array.

POST/audiences/{id}/merge

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/merge', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_ids: ['aud_4KOlh9t2uw5od4qypqCtyrZyDq2'],
    delete_sources: true
  })
});

const { added, already_in_audience } = await response.json();

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/merge \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_ids": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"], "delete_sources": true}'

JSON

{
  "object": "audience_merge",
  "audience": {
    "object": "audience",
    "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "name": "Newsletter",
    "subscribers_count": 1503
  },
  "added": 219,
  "already_in_audience": 93,
  "deleted_source_ids": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "error": "One or more audiences were not found",
  "missing": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "message": "Validation failed.",
  "errors": {
    "source_ids": ["An audience cannot be merged into itself."]
  }
}

Bulk update audiences

Archives, unarchives or deletes several audiences at once.

POST/audiences/bulk

Requires a full API key. Every ID must belong to the workspace, or nothing changes and the request returns 404 with the missing IDs. Archiving and unarchiving fire audience.updated; deleting fires audience.deleted and removes the audiences’ subscribers, like Delete an audience. See Archive an audience.

Body parameters

actionstringrequired

archive, unarchive or delete.

idsstring[]required

Audience IDs, 1 to 100.

Returns

objectstring

Always audience_bulk.

actionstring

The action you sent.

processedinteger

How many audiences were found.

changedinteger

How many actually changed. Archiving an audience that’s already archived doesn’t count.

idsstring[]

The IDs you sent.

POST/audiences/bulk

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'archive',
    ids: ['aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2']
  })
});

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

Terminal

curl -X POST https://api.emailit.com/v2/audiences/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "archive", "ids": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]}'

JSON

{
  "object": "audience_bulk",
  "action": "archive",
  "processed": 2,
  "changed": 2,
  "ids": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "error": "One or more audiences were not found",
  "missing": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

Delete an audience

Permanently deletes an audience and removes everyone from it.

DELETE/audiences/{id}

Requires a full API key. The audience’s subscriber memberships are deleted with it, but the contacts stay in your workspace and in their other audiences. Its hosted subscribe URL stops working. Fires an audience.deleted event. No subscriber.deleted events are sent for the removed memberships.

Path parameters

idstringrequired

The audience ID or its name.

Returns

objectstring

Always audience.

idstring

The ID of the deleted audience.

namestring

The audience name.

deletedboolean

Always true.

DELETE/audiences/{id}

JavaScript

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

await emailit.audiences.delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Python

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

PHP

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

$emailit->audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Ruby

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

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

err := client.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

Rust

use emailit::Emailit;

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

emailit.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.audiences().delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Terminal

curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KOlh9t2uw5od4qypqCtyrZyDq2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "audience",
  "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
  "name": "Customers",
  "deleted": true
}

JSON

{
  "error": "Audience not found"
}