Skip to content

Newsletters APIAudiences

Audiences API

An audience is the list a newsletter goes to. Point your own signup form or app at these endpoints to keep it in sync. Adds are single opt-in and get the same checks as an import: invalid and role addresses are rejected, and anyone suppressed or unsubscribed is skipped. Each add returns an outcome per row, with the reason when an address cannot receive newsletters.

Last updated

The audience object

{
  "object": "audience",
  "id": "aud_abc123",
  "name": "Newsletter",
  "description": null,
  "member_count": 1240,
  "subscribed_count": 1198,
  "consent_source": "Website signup form",
  "feed_enabled": true,
  "feed_url": "https://shipmail.to/f/audfeed_abc123/feed.xml",
  "view_in_browser_default": true,
  "track_engagement_default": false,
  "publish_target_default": "email_and_website",
  "add_utm_tags_default": false,
  "feed_entry_url_default": null,
  "cleanup_enabled": true,
  "cleanup_ignored_issues": 6,
  "cleanup_inactive_days": 180,
  "cleanup_send_last_chance": true,
  "confirmation_email_copy": null,
  "last_chance_email_copy": {
    "en": {
      "subject": "Still want our notes?",
      "message": "You have not opened our newsletter in a while.

Keep it coming with one click."
    }
  },
  "created_at": "2026-07-02T10:00:00.000Z",
  "updated_at": "2026-07-02T10:00:00.000Z"
}
FieldTypeDescription
namestringAudience name, up to 200 characters.
member_countintegerSubscribers of any status.
subscribed_countintegerSubscribers currently receiving newsletters.
consent_sourcestringWhere and how these people opted in.
feed_enabledbooleanWhether this audience publishes an Atom feed of its sent newsletters.
feed_urlstringAtom feed URL, or null when the feed is disabled. Nobody can guess it, but it needs no login, so anyone who has it can read every sent newsletter. Set up the feed on the audience page in the dashboard.
view_in_browser_defaultbooleanWhether issues created in the dashboard for this audience start with a View in browser link (the newsletter's view_in_browser). On by default. Set it with PATCH /audiences/:id.
track_engagement_defaultbooleanWhether a new newsletter for this audience tracks opens and clicks when its creator leaves out track_engagement. Applies only while open and click tracking is available. Welcome emails and duplicates keep their own value. Off by default.
publish_target_defaultstringWhere issues created in the dashboard for this audience go (the newsletter's publish_target): email_and_website (default), email or website. A target that needs the web gives email while the audience has neither its website nor its feed on.
add_utm_tags_defaultbooleanWhether issues created in the dashboard for this audience add UTM tags to their links (the newsletter's add_utm_tags). Off by default.
feed_entry_url_defaultstringThe http or https feed title link issues created in the dashboard for this audience start with (the newsletter's feed_entry_url), or null. Send null to clear it. Changing a default never changes an existing issue, and API calls follow their own fields.
cleanup_enabledbooleanList cleanup. A cold subscriber gets one last-chance email in place of the next newsletter, and becomes dormant without a keep click within 14 days. On for audiences created since list cleanup shipped.
cleanup_ignored_issuesintegerTracked newsletters ignored in a row before a subscriber is cold, from 2 to 100.
cleanup_inactive_daysintegerDays without a sign of life before a subscriber is cold, from 30 to 3650. A sign of life is an open or click by a person, a reply, a confirmation, a signup again, or a keep click.
cleanup_send_last_chancebooleanWith list cleanup on, true (the default, and the safer choice) sends a cold subscriber the last-chance email first. With false, they become dormant at the next send with no email. Re-confirm requests are unaffected.
confirmation_email_copyobject or nullYour own subject and message for the double opt-in confirmation email, per language. Null means the built-in wording. See Email wording below.
last_chance_email_copyobject or nullYour own subject and message for the list-cleanup last-chance email, in the same shape. Null means the built-in wording.

The subscriber object

{
  "object": "subscriber",
  "id": "audmem_abc123",
  "audience_id": "aud_abc123",
  "email_address": "jane@example.com",
  "display_name": "Jane Doe",
  "status": "subscribed",
  "mailable": true,
  "not_mailable_reasons": [],
  "merge_fields": { "plan": "pro" },
  "consent_source": "Website signup form",
  "created_at": "2026-07-02T10:00:00.000Z",
  "updated_at": "2026-07-02T10:00:00.000Z"
}

status is one of subscribed, pending, unsubscribed, bounced, complained, suppressed, transactional_only, or dormant. Public signup forms with double opt-in create pending subscribers until the confirmation link is opened. Newsletters skip dormant subscribers; a keep click, a signup again, or resubscribe makes them subscribed. merge_fields holds up to 50 string, number, boolean, or null values keyed by field name.

status belongs to this audience. mailable says whether your organization may send newsletters to the address at all right now, and not_mailable_reasons says why not, most decisive first. A subscriber can be subscribed here and still not mailable, for example after choosing to stop all of your emails from a newsletter of another audience. A reader who unsubscribes through a newsletter's link leaves only the audience it went to: their status there becomes unsubscribed, and they stay mailable in your other audiences. Each reason is an organization-wide newsletter opt-out or a suppression:

"not_mailable_reasons": [
  {
    "reason": "unsubscribed",
    "source": "newsletter_optout",
    "created_at": "2026-07-10T08:00:00.000Z",
    "newsletter_id": "nws_abc123",
    "test_send": false
  },
  {
    "reason": "hard_bounce",
    "source": "suppression",
    "created_at": "2026-07-12T08:00:00.000Z",
    "expires_at": null
  }
]

An opt-out has reason: "unsubscribed", the newsletter it came from (or null), and test_send: true when the reader unsubscribed from a test send. A suppression has hard_bounce, soft_bounce, complaint or manual, and expires_at for a soft-bounce pause. Only resubscribe, with fresh consent, lifts an opt-out; see the Suppressions API for suppressions.

Create an audience

POST/v1/audiences

Scope: audiences:write. Body: { name, description?, consent_source }. consent_source is a required attestation of where and how these people opted in. Returns the audience object with a 201.

List, get, update, and delete audiences

GET    /v1/audiences
GET    /v1/audiences/:id
PATCH  /v1/audiences/:id
DELETE /v1/audiences/:id

List supports cursor and limit pagination. Update accepts { name?, description?, view_in_browser_default?, track_engagement_default?, publish_target_default?, add_utm_tags_default?, feed_entry_url_default?, cleanup_enabled?, cleanup_ignored_issues?, cleanup_inactive_days?, cleanup_send_last_chance?, confirmation_email_copy?, last_chance_email_copy? }. Delete returns 204 and removes the audience's subscribers; newsletters you already sent keep their history.

Email wording

confirmation_email_copy and last_chance_email_copy replace the subject and the opening message of the confirmation and last-chance emails. Set them with PATCH /v1/audiences/:id; creating an audience does not take them. Each holds a subject and a message per language:

{
  "confirmation_email_copy": {
    "en": { "subject": "One click to join", "message": "Thanks for signing up.

Confirm below and the next issue is yours." },
    "fr": { "subject": "Un clic pour vous inscrire", "message": "Merci de votre inscription." }
  }
}
  • The object replaces that email's wording. A language you leave out uses the built-in text. Send null or {} to clear it, and leave the field out to keep it.
  • A subject is one line of at most 120 characters. A message is plain text of at most 600 characters; line breaks are kept and a blank line starts a paragraph. A language needs both.
  • Text may hold no links or anything that works as one (https://, www., domains such as example.com or bit.ly/x, spaced or spelled-out forms), no email addresses, no phone numbers of 7 or more digits, and no invisible or direction-changing characters. Shipmail normalizes the text (NFKC) before checking it.
  • Wording applies to its own language only. A reader whose email is in another language gets the whole built-in email in that language, never a mix.
  • The rest of the email stays fixed: the button and its label, the fallback link, the expiry and “if you didn't sign up” line, the “last email” line, the unsubscribe link, your business name and postal address, and the preview text.

A rule violation answers 422 validation_error with one detail per field, such as { "field": "confirmation_email_copy.fr.message", "code": "link" }. The codes are link, email, phone, invisible, lineBreak, tooLong, and required.

Adding or changing text needs a paid plan (the free trial does not count) and newsletter sending in good standing. Otherwise the request answers 403 authorization_error with the detail code plan or standing. Removing text is always allowed. If an organization stops qualifying later, its emails go out with the built-in wording and the saved text is kept.

Add a subscriber

POST/v1/audiences/:id/subscribers

Scope: audiences:write. This is the endpoint your signup form calls. Body:

{
  "email_address": "jane@example.com",
  "display_name": "Jane Doe",
  "merge_fields": { "plan": "pro" }
}

You get an outcome back instead of the subscriber, so a suppressed or invalid address never fails the request:

{ "email_address": "jane@example.com", "outcome": "created" }

A skipped_not_mailable outcome also carries a reason: unsubscribed, complaint, hard_bounce, soft_bounce, manual, or not_resubscribable_status when the subscriber is already unsubscribed, bounced or complained in this audience. Adding never changes that status; only resubscribe does. An address that unsubscribed from this audience gets unsubscribed even after you removed the subscriber.

{
  "email_address": "jane@example.com",
  "outcome": "skipped_not_mailable",
  "reason": "unsubscribed"
}

outcome is one of created, updated, skipped_not_mailable, skipped_invalid, skipped_cap, or skipped_quota. The returned email_address is the normalized (trimmed, lowercased) form of what you sent.

A skipped_invalid outcome carries a reason code and a suggestion, which holds the corrected address for a typo and is null otherwise.

{
  "email_address": "alex@gamil.com",
  "outcome": "skipped_invalid",
  "reason": "typo",
  "suggestion": "alex@gmail.com"
}
reasonMeaning
malformedNot a valid email address.
duplicateThe address appears earlier in the same request.
role_addressA role or operational inbox, such as support@ or noreply@.
test_addressA test-looking address, such as test@ or example@.
disposable_domainA temporary email domain.
typoA likely typo of a big provider, such as gmial.com. suggestion holds the fix.
spam_trapA spam-trap address.
no_mail_domainThe domain receives no email.
undeliverableShipmail will not send to this address.

Adding an existing subscriber again merges instead of overwriting. A provided display_name replaces the stored one (omitting it keeps it), merge_fields keys you send are merged into the stored object, and consent is attested again. A subscriber keeps at most 50 custom fields: when the merge would pass that, only the fields they already have are updated and new keys are left out. To replace fields outright, use the update endpoint below.

Manage the audience feed

GET   /v1/audiences/:id/feed
PATCH /v1/audiences/:id/feed
POST  /v1/audiences/:id/feed/rotate
POST  /v1/audiences/:id/feed/revoke

Read access uses audiences:read; changes use audiences:write. PATCH accepts any of { enabled, title, subtitle, site_url, canonical_url, author_name, icon_url, entry_limit }. It returns the complete feed object:

{
  "object": "audience_feed",
  "audience_id": "aud_abc123",
  "enabled": true,
  "title": "Release notes",
  "subtitle": "What shipped this week",
  "site_url": "https://example.com",
  "canonical_url": "https://example.com/feed.xml",
  "author_name": "Example team",
  "icon_url": "https://example.com/icon.png",
  "entry_limit": 25,
  "url": "https://shipmail.to/f/audfeed_abc123/feed.xml",
  "updated_at": "2026-07-29T10:00:00.000Z"
}

canonical_url is your own HTTPS feed URL and is emitted as the Atom rel=self link. entry_limit is an integer from 10 to 100. The response reports the stored value, so it remains null until you choose one, even though the feed uses a default of 50. Omitted PATCH fields stay unchanged. Send null to clear the canonical URL or return the entry limit to its default.

Rotate creates a new URL and keeps the old one as a redirect until the next rotate. Revoke is for a leaked URL. It invalidates the current and previous URLs at once, so existing readers must subscribe again. Both require a feed that has been enabled at least once and return a validation error otherwise; the response contains the replacement URL when the feed is enabled and null while it is disabled. Send an Idempotency-Key with feed mutations.

Add subscribers in bulk

POST/v1/audiences/:id/subscribers/batch

Add up to 1000 subscribers in one call. Body: { subscribers: [ ... ] } where each entry has the same shape as a single add. Returns { results: [ ... ] } with one outcome per row, in order. A request body can be at most 1 MB, so large merge_fields may need smaller batches.

To check a list before you import it, send "dry_run": true. Each row gets the outcome it would have (created, updated, skipped_invalid with its reason, or skipped_not_mailable), and nothing changes: no subscriber is added or updated, no quota is used, no event or webhook fires and no welcome email goes out. It uses the same scope, audiences:write.

POST /v1/audiences/aud_abc123/subscribers/batch
{
  "dry_run": true,
  "subscribers": [
    { "email_address": "jane@example.com" },
    { "email_address": "alex@gamil.com" }
  ]
}

200 OK
{
  "dry_run": true,
  "results": [
    { "email_address": "jane@example.com", "outcome": "created" },
    { "email_address": "alex@gamil.com", "outcome": "skipped_invalid", "reason": "typo", "suggestion": "alex@gmail.com" }
  ]
}

A dry run does not check the trial's active subscriber limit, the monthly ingest quota or whether the API key may email every address its welcome sequence would reach. The real add can still return skipped_cap, skipped_quota or a 403.

Dry runs can check up to 10,000 addresses a day for each organization. A request over the limit returns a 429 rate_limit_error.

Limits

Paid plans do not limit active subscribers or audiences. Net-new adds count against a monthly ingest quota: 1,000 on Solo, 5,000 on Pro, and 25,000 on Team and Scale. Adding an active subscriber to another audience is free. Adds over the quota return skipped_quota; during the trial, adds over the active subscriber limit return skipped_cap.

The quota is checked per call. If what is left cannot fit every net-new address in a batch, all the net-new addresses in that batch come back as skipped_quota. Retry with a smaller batch to use what remains. During the free trial an organization has 100 active subscribers, counting an address on several audiences once, and 200 net-new adds per month. Ending the trial early from Billing removes the subscriber limit and lifts the quota to the plan's.

List and look up subscribers

GET /v1/audiences/:id/subscribers
GET /v1/audiences/:id/subscribers/:subscriber_id
GET /v1/audiences/:id/subscribers/by-email/:email

List supports cursor, limit, a status filter, and an exact email filter. The by-email lookup expects a URL-encoded address. Every subscriber in these responses, and in the update, unsubscribe and resubscribe responses, carries mailable and not_mailable_reasons.

Update, unsubscribe, resubscribe, and remove

PATCH  /v1/audiences/:id/subscribers/:subscriber_id
POST   /v1/audiences/:id/subscribers/:subscriber_id/unsubscribe
POST   /v1/audiences/:id/subscribers/:subscriber_id/resubscribe
DELETE /v1/audiences/:id/subscribers/:subscriber_id

Update accepts { display_name?, merge_fields? }. Unsubscribe records an opt-out for the whole organization, so future newsletters skip the address in every audience, and returns the updated subscriber. Send { "scope": "audience" } to unsubscribe them from this audience only, as an issue's unsubscribe link does: the organization's other audiences still reach them, and a subscriber already unsubscribed here is left as is. The default scope is organization. Resubscribe accepts { consent_source }, removes that opt-out and the subscriber's unsubscribe from this audience once the person opts in again, and marks the subscriber active. The consent covers this audience only: in each other audience where the subscriber was still subscribed or dormant, they become unsubscribed, and their earlier unsubscribes from other audiences stay. Delete returns 204. Prefer unsubscribe, which keeps the opt-out history.

Resend the confirmation email

POST /v1/audiences/:id/subscribers/resend-confirmation

Emails the double opt-in link again to pending subscribers. Send { subscriber_ids } (1 to 100 IDs) to pick them, or no body to reach every eligible pending subscriber, at most 500 per call; remaining says how many are left for another call. A subscriber gets the email only if they signed up at most 30 days ago, had fewer than 3 resends, and got no confirmation email in the last 24 hours. Each email carries a new link valid for 7 days, and the old link stops working. If an email fails to send, the subscriber counts as failed and the old link keeps working, unless the mail server may have accepted it: then the new link is kept.

{
  "object": "confirmation_resend",
  "audience_id": "aud_abc123",
  "sent": 12,
  "failed": 0,
  "skipped": {
    "not_found": 0,
    "not_pending": 0,
    "too_old": 3,
    "resend_limit": 1,
    "recently_sent": 2
  },
  "remaining": 0
}

not_found and not_pending count IDs you named that are not in the audience or not pending. Each skipped subscriber has one reason, checked in the order shown. It needs the audiences:write scope and uses the send rate limit. It answers 422 when the organization has no verified newsletter domain with a Reply-To address, and 403 when newsletter sending is restricted or the key is limited to recipients, domains or mailboxes. Without subscriber_ids, pending subscribers whose address is suppressed are left out; a suppressed subscriber you name counts as failed.