Audiences

Create an Audience

POST /api/v1/audiences

Scope: contacts:manage

Request Body

Field	Type	Required	Description
`name`	string	Yes	Audience name

const audience = await wm.audiences.create('Newsletter Subscribers')
console.log(audience.id) // aud_abc123

Response

{
  "id": "aud_abc123",
  "name": "Newsletter Subscribers",
  "contactCount": 0,
  "createdAt": "2026-03-28T00:00:00Z"
}

List Audiences

GET /api/v1/audiences

Scope: contacts:manage

const audiences = await wm.audiences.list()
audiences.forEach(a => console.log(a.name, a.contactCount))

Response

{
  "data": [
    {
      "id": "aud_abc123",
      "name": "Newsletter Subscribers",
      "contactCount": 1250,
      "createdAt": "2026-03-28T00:00:00Z"
    }
  ]
}

Get an Audience

GET /api/v1/audiences/:id

Scope: contacts:manage

const audience = await wm.audiences.get('aud_abc123')
console.log(audience.name, audience.contactCount)

Delete an Audience

DELETE /api/v1/audiences/:id

Scope: contacts:manage

await wm.audiences.delete('aud_abc123')

Returns 204 No Content on success.

Add a Contact

POST /api/v1/audiences/:audienceId/contacts

Scope: contacts:manage

Request Body

Field	Type	Required	Description
`email`	string	Yes	Contact email address
`name`	string	No	Contact display name
`metadata`	object	No	Custom key-value data
`topics`	string[]	No	Subscription topics

const contact = await wm.audiences.addContact('aud_abc123', {
  email: 'alice@example.com',
  name: 'Alice Smith',
  metadata: { plan: 'pro', signupSource: 'landing-page' },
  topics: ['product-updates', 'changelog'],
})
 
console.log(contact.id) // con_abc123

Response

{
  "id": "con_abc123",
  "email": "alice@example.com",
  "name": "Alice Smith",
  "metadata": { "plan": "pro", "signupSource": "landing-page" },
  "topics": ["product-updates", "changelog"],
  "subscribed": true,
  "createdAt": "2026-03-28T00:00:00Z"
}

List Contacts

GET /api/v1/audiences/:audienceId/contacts

Scope: contacts:manage

Supports pagination with page and pageSize query parameters.

const { data, total } = await wm.audiences.listContacts('aud_abc123', {
  page: 1,
  pageSize: 25,
})
 
data.forEach(c => console.log(c.email, c.subscribed))

Response

{
  "data": [
    {
      "id": "con_abc123",
      "email": "alice@example.com",
      "name": "Alice Smith",
      "subscribed": true,
      "createdAt": "2026-03-28T00:00:00Z"
    }
  ],
  "total": 1250,
  "page": 1,
  "pageSize": 25
}

Update a Contact

PATCH /api/v1/contacts/:contactId

Scope: contacts:manage

Request Body

Field	Type	Required	Description
`name`	string	No	Updated display name
`metadata`	object	No	Updated custom data (merged)
`topics`	string[]	No	Updated subscription topics
`subscribed`	boolean	No	Subscription status

const updated = await wm.audiences.updateContact('con_abc123', {
  metadata: { plan: 'enterprise' },
  topics: ['product-updates', 'changelog', 'security'],
})

Delete a Contact

DELETE /api/v1/contacts/:contactId

Scope: contacts:manage

await wm.audiences.deleteContact('con_abc123')

Returns 204 No Content on success.

On this page