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

Activity Timeline

Get a chronological list of email events for a subscriber. This includes deliveries, opens, clicks, bounces, complaints, and more.

GET /v1/audiences/:audienceId/subscribers/:subscriberId/activity

Query Parameters

Parameter	Type	Description
limit	integer	Number of events per page (default: 50, max: 100)
cursor	string	Cursor for pagination
type	string	Filter by event type (e.g., delivered, opened, clicked)

// Get full activity timeline
const { data: events, hasMore, nextCursor } = await client.audiences
  .subscribers('audience_xxxxx')
  .activity('subscriber_xxxxx');

// Filter by event type
const opens = await client.audiences
  .subscribers('audience_xxxxx')
  .activity('subscriber_xxxxx', { type: 'opened' });

// Paginate through results
const page2 = await client.audiences
  .subscribers('audience_xxxxx')
  .activity('subscriber_xxxxx', { cursor: nextCursor });

// Each event includes:
// {
//   id: 'evt_xxx',
//   type: 'opened',
//   timestamp: '2025-01-15T10:30:00Z',
//   data: { userAgent: '...', ip: '...' },
//   email: { id: 'email_xxx', subject: 'Welcome!', from: 'hello@...', campaignId: null }
// }

Requires the audience:read scope.

Bulk Import

Import subscribers in bulk from a JSON array or CSV data. Duplicate emails are automatically skipped.

POST /v1/audiences/:id/subscribers/import

Import from Array

import-array.ts

const result = await client.audiences.subscribers('audience_xxxxx').import({
  subscribers: [
    { email: 'alice@example.com', firstName: 'Alice', lastName: 'Smith' },
    { email: 'bob@example.com', firstName: 'Bob' },
    { email: 'carol@example.com', metadata: { plan: 'premium' } },
  ],
});

console.log(result);
// { total: 3, created: 3, updated: 0, skipped: 0, errors: [] }

Import from CSV

import-csv.ts

import { readFileSync } from 'fs';

const csvData = readFileSync('subscribers.csv', 'utf-8');

const result = await client.audiences.subscribers('audience_xxxxx').import({
  csvData,
});

// CSV format:
// email,firstName,lastName
// alice@example.com,Alice,Smith
// bob@example.com,Bob,Jones

Response

Field	Type	Description
total	integer	Total subscribers processed
created	integer	New subscribers created
skipped	integer	Duplicate emails skipped
errors	array	CSV parsing or validation errors with row numbers

Limits: Maximum 10,000 subscribers per import request. CSV data cannot exceed 10MB. Additional columns beyond email, firstName, and lastName are stored as metadata.

Requires the audience:write scope.

Export Subscribers

Export subscribers as CSV data. Returns a CSV file with email, name, status, source, dates, and any custom metadata columns.

GET /v1/audiences/:id/subscribers/export

export-subscribers.ts

import { writeFileSync } from 'fs';

// Export all subscribers
const csv = await client.audiences.subscribers('audience_xxxxx').export();
writeFileSync('all-subscribers.csv', csv);

// Export only active subscribers
const activeCsv = await client.audiences
  .subscribers('audience_xxxxx')
  .export({ status: 'active' });

Requires the audience:read scope.

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>