Audiences

Organize your subscribers into audiences for targeted email campaigns.

Create an Audience

Create a new audience to group subscribers.

POST /v1/audiences

create-audience.ts

const audience = await client.audiences.create({
  name: 'Newsletter Subscribers',
  description: 'Users who signed up for our weekly newsletter',
});

console.log(audience.id); // audience_xxxxx

List Audiences

GET /v1/audiences

list-audiences.ts

const { data } = await client.audiences.list();

for (const audience of data) {
  console.log(`${audience.name}: ${audience.subscriberCount} subscribers`);
}

Managing Subscribers

Add, update, and remove subscribers from an audience.

Add a Subscriber

POST /v1/audiences/:id/subscribers

add-subscriber.ts

const subscriber = await client.audiences.subscribers('audience_xxxxx').add({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  attributes: {
    plan: 'premium',
    signupSource: 'website',
  },
  source: 'signup_form',
});

List Subscribers

GET /v1/audiences/:id/subscribers

list-subscribers.ts

// List all active subscribers
const { data } = await client.audiences.subscribers('audience_xxxxx').list({
  status: 'active',
  limit: 100,
});

// Search by email
const { data: matches } = await client.audiences.subscribers('audience_xxxxx').list({
  email: 'john@example.com',
});

Update a Subscriber

PATCH /v1/audiences/:id/subscribers/:subscriberId

update-subscriber.ts

const subscriber = await client.audiences.subscribers('audience_xxxxx').update(
  'subscriber_xxxxx',
  {
    firstName: 'Jane',
    attributes: {
      plan: 'enterprise',
    },
  }
);

Remove a Subscriber

DELETE /v1/audiences/:id/subscribers/:subscriberId

remove-subscriber.ts

await client.audiences.subscribers('audience_xxxxx').remove('subscriber_xxxxx');

Subscriber Status

Subscribers can have the following statuses:

Status	Description
`active`	Subscriber will receive emails
`unsubscribed`	Subscriber opted out of emails
`bounced`	Email address bounced
`complained`	Subscriber marked email as spam

Custom Attributes

Store custom data on subscribers using the attributes field. Use these attributes for segmentation and personalization.

custom-attributes.ts

// Add subscriber with custom attributes
const subscriber = await client.audiences.subscribers('audience_xxxxx').add({
  email: 'user@example.com',
  attributes: {
    plan: 'premium',
    industry: 'technology',
    companySize: '50-100',
    interests: ['product-updates', 'engineering'],
  },
});

// Use attributes in templates
// <p>Thanks for being a {{attributes.plan}} member!</p>