---
title: "List audiences"
method: GET
path: "/audiences"
tags: ["Audiences"]
---

# List audiences

`GET /audiences`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/audiences`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

## Query parameters

- `cursor` string
- `limit` integer

## Headers

- `X-Shipmail-Organization` string

## Response `200`

Paginated list of audiences.

- object
  - `data` Audience[], required
    - `object` 'audience', required
    - `id` string, required
    - `name` string, required
    - `description` string, nullable, required
    - `member_count` integer, required: Total subscribers of any status.
    - `subscribed_count` integer, required: Subscribers currently receiving newsletters.
    - `consent_source` string, nullable, required
    - `feed_enabled` boolean, required: Whether this audience publishes an Atom feed of its sent newsletters.
    - `feed_url` string, nullable, required: Unguessable Shipmail Atom feed URL, or null when the feed is disabled.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `cleanup_enabled` boolean, required: List cleanup. A cold subscriber gets one last-chance email in place of a newsletter, and becomes dormant if they do not click keep within 14 days. On by default for audiences created since list cleanup shipped.
    - `cleanup_ignored_issues` integer, required: How many tracked newsletters in a row a subscriber ignores before they count as cold. Default 6.
    - `cleanup_inactive_days` integer, required: How many days without a sign of life (a human open or click, a reply, a confirmation, a signup again, a keep click) before a subscriber counts as cold. Default 180.
  - `pagination` Pagination, required
    - `next_cursor` string, nullable, required: Cursor for the next page. Null if no more results.
    - `has_more` boolean, required: Whether more results exist beyond this page.
    - `limit` integer, required: Number of items per page.

## Other responses

- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)