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"
}| Field | Type | Description |
|---|---|---|
| name | string | Audience name, up to 200 characters. |
| member_count | integer | Subscribers of any status. |
| subscribed_count | integer | Subscribers currently receiving newsletters. |
| consent_source | string | Where and how these people opted in. |
| feed_enabled | boolean | Whether this audience publishes an Atom feed of its sent newsletters. |
| feed_url | string | Atom 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_default | boolean | Whether 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_default | boolean | Whether 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_default | string | Where 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_default | boolean | Whether 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_default | string | The 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_enabled | boolean | List 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_issues | integer | Tracked newsletters ignored in a row before a subscriber is cold, from 2 to 100. |
| cleanup_inactive_days | integer | Days 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_chance | boolean | With 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_copy | object or null | Your 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_copy | object or null | Your 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
/v1/audiencesScope: 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/:idList 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
nullor{}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 asexample.comorbit.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
/v1/audiences/:id/subscribersScope: 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"
}| reason | Meaning |
|---|---|
| malformed | Not a valid email address. |
| duplicate | The address appears earlier in the same request. |
| role_address | A role or operational inbox, such as support@ or noreply@. |
| test_address | A test-looking address, such as test@ or example@. |
| disposable_domain | A temporary email domain. |
| typo | A likely typo of a big provider, such as gmial.com. suggestion holds the fix. |
| spam_trap | A spam-trap address. |
| no_mail_domain | The domain receives no email. |
| undeliverable | Shipmail 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/revokeRead 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
/v1/audiences/:id/subscribers/batchAdd 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/:emailList 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_idUpdate 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-confirmationEmails 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.