Newsletters API
Create, test and schedule newsletters from code. The API applies the same checks as the dashboard: verified newsletter domains, audience opt-outs, suppressions, pacing, one-click unsubscribe, test sends and preflight.
Last updated
Create a draft
/v1/newslettersScope: newsletters:write. Body:
{
"audience_id": "aud_abc123",
"sender_identity_id": "nwsid_abc123",
"name": "July changelog",
"subject": "What shipped in July",
"preview_text": "A quick product update",
"blocks": [
{ "type": "heading", "level": 1, "text": "July updates" },
{
"type": "callout",
"title": "Quick note",
"body": "Read the <a href=\"https://example.com/launch\">launch notes</a> with <strong>key details</strong>."
},
{
"type": "video",
"video_url": "https://cdn.example.com/demo.mp4",
"thumbnail_url": "https://cdn.example.com/demo.jpg",
"label": "Watch demo"
}
],
"send_window_hours": 6,
"publish_target": "email_and_website",
"view_in_browser": true,
"feed_entry_url": "https://example.com/original-post",
"styling_mode": "styled",
"track_engagement": false,
"add_utm_tags": false
}Body formats
Provide blocks, body_html, or body_text. Use blocks when you can, especially from an agent: Shipmail renders them to email-safe HTML and text for you. The response includes the stored blocks plus derived body_html and body_text with status draft.
Markdown
content_markdown takes the body as Markdown, up to 100,000 characters, on create and update. Shipmail converts headings, paragraphs, lists, quotes, code, images, links, dividers and tables to blocks and stores only the blocks. A callout starts with a line :::callout, optionally followed by info, warning or success and a title, and ends with a line :::. Raw HTML stays visible text. Send only one of blocks, body_html or content_markdown. The CLI flag is --markdown @issue.md.
{
"subject": "What shipped in October",
"content_markdown": "# October
Three things shipped.
:::callout info Heads up
Pricing changes on **Nov 1**.
:::"
}Feed entry link
Set feed_entry_url to an optional absolute http or https URL when the newsletter appears in its audience's Atom feed. Feed readers link the entry title there instead of to the issue's Shipmail page. On PATCH, send null to link the title to that page again.
Where it goes
publish_target is email_and_website (the default), email or website. The default sends the newsletter, and lists it on the audience's newsletter website and in its feed when archive_visibility is public. email is never listed on the web: no website entry, sitemap or RSS entry, Atom feed entry or share image.
website publishes the newsletter on the audience's newsletter website and in its feed, with no email. Call POST /newsletters/:id/schedule with the time it should go live. Nobody receives it, so it uses none of your sends and skips the send preflight, warm-up and send stages. The audience needs its website or its feed on, or the call returns 422 validation_error. Once live, its status is published. The CLI flag is --publish-target.
View in browser link
view_in_browser says whether the email carries a View in browser link to the issue's own page. It is independent of the website and the feed: an email issue can have the link and still not be listed anywhere. A website issue sends no email, so it never has the link. Anyone with the link can open the page. On create, when omitted, it is true for an email_and_website issue whose archive_visibility is public, and false otherwise. Omitting it on PATCH keeps the current value, unless archive_visibility changes in the same request. --view-in-browser true|false sets it in the CLI.
Archive visibility
archive_visibility (private or public, default private) decides whether an email_and_website issue is listed on the audience's newsletter website and in its Atom feed. A website issue is always listed and an email issue never is. It does not control the View in browser link, except as the default for view_in_browser.
Open and click tracking
Set track_engagement to true to track opens and clicks for this newsletter. Omitted on create, it takes the audience's track_engagement_default (which is false unless the owner turned it on), and omitting it on PATCH keeps the current value. Like other content options, it can only change while the newsletter is an editable draft or a scheduled newsletter whose send time is still in the future. When open and click tracking is not available, Shipmail returns 422 validation_error with the message "Open and click tracking is not available." See open and click tracking for what Shipmail records and which opens and clicks it leaves out.
UTM tags
Set add_utm_tags to true to add utm_source=shipmail, utm_medium and utm_campaign to the newsletter's http and https links. utm_medium is email in the email and feed in the Atom feed. utm_campaign is the subject in lowercase with hyphens, for example what-shipped-in-july. Links that already have a utm_ parameter keep their own. It defaults to false, omitting it on PATCH keeps the current value, and it changes only while the newsletter is editable.
How the body is resolved
Body resolution on create: blocks win, then body_html (stored as one custom_html block), then body_text (paragraph blocks). When you also send body_text alongside blocks or HTML, it sets the plain-text override instead of deriving text from blocks.
Rich prose fields inside blocks accept bare text or sanitized inline HTML. This includes paragraph.body, callout.body, quote.body, list items, and column bodies. Allowed tags are a, b, br, code, em, i, p, s, span, strong, and u. Use p and br for line breaks because raw newlines are not converted. Encode literal tag-like text as HTML entities, such as <example>. Use body_html or a custom_html block for a fully custom email-safe layout.
Use GET /v1/newsletter-sender-identities to find available sender_identity_id values before creating a draft. Each identity fixes the From name, sending address, business name, postal address, and optional footer text for that brand.
Plain semantic HTML gets email-safe spacing and type for headings, paragraphs, lists, quotes, tables and images. Add inline styles only if you want your own template.
styling_mode controls that theming: styled (default) applies Shipmail's email theme and centered layout, plain sends your HTML without injected styles, width, or centering, so the reader's email client styles it like a normal email. Sanitization and the unsubscribe footer apply in both modes.
Do not use raw <video> or <iframe> embeds in send HTML. Most email clients drop them. Link a hosted video from an image thumbnail with descriptive alt text instead.
Block types
Each block is a JSON object with a type field. Up to 200 blocks per draft. See also newsletter for dashboard editing details.
heading { type, text, level? } level: 1 | 2 | 3
paragraph { type, body }
list { type, ordered?, items }
callout { type, title?, body, variant? } variant: accent | info | warning | success
button { type, label, url, align? } align: left | center | right
image { type, url, alt, align?, link_url?, caption?, caption_url? }
align: left | center | right
video { type, video_url, thumbnail_url, label }
columns { type, ratio?, left, right } ratio: 50-50 | 33-67 | 67-33
each column: title?, body?, image_url?, image_alt?, image_fit?, cta_label?, cta_url?
image_fit: natural | contain | cover
link_list { type, title?, items: [{ label, url, description? }] }
quote { type, body, cite? }
divider { type }
spacer { type, height? } height: 8-80
code { type, code }
event { type, event_id } event_id: nwsevt_...
custom_html { type, html }Image alignment defaults to left. Set its optional align field to center or right to align the image and its caption together.
Column images default to their natural aspect ratio. Set image_fit to contain to show the whole image in a 4:3 frame, or cover to fill and crop that frame.
An event block shows an event's card: its title, date and time in the event's time zone, location, and places left when capped, with Going and Not going buttons. Each email recipient gets their own answer links. The website, archive and test sends link to the event's public page, or show no buttons when the public page is off. Only an event of the newsletter's own organization and audience renders; any other event_id renders nothing. Events are created in the dashboard; there are no event API endpoints.
Block visibility
Any block can carry an optional visibility object that limits where it shows and to which readers. Omit it to show the block everywhere.
{
"type": "paragraph",
"body": "Members get early access on Friday.",
"visibility": {
"channel": "all", // all | email | web
"segment_id": "nwsseg_123", // a segment of the newsletter's audience, or null
"segment_rule": "in" // in | not_in
}
}email hides the block on the newsletter website, archive and feed; web hides it in the email. With a segment_id, in shows the block only to readers in that segment and not_in to everyone else. The website shows the issue as a reader in no segment sees it.
Segment membership is fixed when you schedule the send. Test sends show every email block. Preflight fails with section_segments when a block names a segment outside the audience, and with email_body when every block is web. Welcome emails accept channel only.
Newsletter assets
GET /v1/newsletter-assets
POST /v1/newsletter-assets?filename=demo.mp4
POST /v1/newsletter-assets
{
"url": "https://cdn.shipmail.to/newsletter-images/org_123/demo.png",
"filename": "demo.png"
}
POST /v1/newsletter-assets/upload-tokens
{
"filename": "demo.png",
"content_type": "image/png",
"size": 12345,
"sha256": "<lowercase SHA-256>"
}
# PUT the exact raw bytes to upload_url with upload_headers.
# For video, PUT a generated JPEG poster to thumbnail_upload_url.
# POST an empty body to complete_url. Its response is the newsletter_asset.Scope: newsletters:read for list and newsletters:write for upload. Upload raw JPEG, PNG, WebP, GIF, MP4, MOV, or WebM bytes. Video uploads generate a thumbnail and return asset metadata plus current storage usage: url, image_url or video_url, thumbnail URL, duration, dimensions, checksum, content type, and byte size. Repeated uploads dedupe by checksum. To keep existing Shipmail CDN media visible in the media library, post JSON with url and, for videos, thumbnail_url. URLs must belong to the same workspace newsletter media namespace. New media counts toward workspace newsletter storage: 2 GB on Solo, 5 GB on Pro, and 10 GB on Team and Scale. Prepared uploads bind the organization, filename, content type, size, and SHA-256 digest to a five-minute, single-use storage PUT. The separate completion URL verifies the stored object before it creates the asset, so 25 MB videos do not pass through an application function.
Read and update newsletters
GET /v1/newsletters
GET /v1/newsletters/:id
PATCH /v1/newsletters/:idList supports cursor and limit pagination. Patch accepts the same fields as create, all optional, and updates editable drafts or scheduled newsletters whose send time is still in the future. Responses include stored blocks when the newsletter was authored with blocks.
Every newsletter object includes view_in_browser, track_engagement, add_utm_tags, opened_count, and clicked_count. opened_count is the number of unique recipients with at least one counted open; opens that Apple Mail Privacy Protection preloads are not counted. clicked_count is the number of unique recipients who clicked at least one tracked link, excluding clicks attributed to link scanners. Both are null when track_engagement is false.
Changing a scheduled newsletter's subject, preview, body, presentation, or audience returns it to status: "draft" and clears scheduled_at. Send a new test and schedule it again. Check the returned status after updates made through the API, SDKs, CLI, or MCP. Changes to its name, feed link, or send window can keep the schedule and refresh its recipient snapshot.
Body resolution on patch: explicit blocks win, then body_html, then body_text when the draft has no blocks yet, then the existing blocks. Sending only body_text updates the plain-text override when blocks already exist.
Updates use a revision check. If someone saves the same newsletter from the dashboard or the API at the same time and wins, you get 409 conflict. Fetch the newsletter again, merge your changes, and retry the patch.
PATCH /v1/newsletters/nws_abc123
{
"blocks": [
{ "type": "heading", "level": 1, "text": "August updates" },
{
"type": "paragraph",
"body": "Read the <a href=\"https://example.com/august\">August announcement</a>."
}
]
}Test and preflight
POST /v1/newsletters/:id/test-send
POST /v1/newsletters/:id/preflight
POST /v1/newsletters/:id/previewTest sends accept { recipient_email } for any reviewer email address. Preflight returns structured readiness items for domain verification, Reply-To address, audience consent, body, links, images, footer identity, test-send history, and account restrictions. If a guardrail fails, test-send returns a validation error with the failed preflight items in details.
Preflight includes url_breakdown: href count, image src count, video href count, text URL count, unique URL count, maximum unique URLs, and offending URLs. Too many clickable destinations fail preflight. High remote resource counts from links, images, and video thumbnails produce a deliverability warning.
Preview
/v1/newsletters/:id/previewscope newsletters:readPreview renders the email exactly as a reader receives it, with the same renderer as the send: html and text include the footer with the business name, postal address and unsubscribe link, subject has its merge tags filled in, and headers lists the headers the send adds, such as List-Unsubscribe, List-Unsubscribe-Post and, when set, Reply-To. Links in a preview are never tracked. The response also carries the public archive HTML, warnings, and the same URL breakdown as preflight.
The body is optional. By default the preview uses a sample reader. To see what one subscriber gets, with their name and merge fields, pass their ID. That needs the audiences:read scope too (403 otherwise), and answers 404 when the subscriber is not among the readers a send would reach: subscribed, inside the newsletter's segment, not unsubscribed and not suppressed.
POST /v1/newsletters/nws_abc123/preview
{ "preview_as": { "type": "subscriber", "subscriber_id": "audmem_abc123" } }{
"object": "newsletter_preview",
"newsletter_id": "nws_abc123",
"subject": "What shipped in July, Ada",
"html": "<!doctype html>...",
"text": "July updates ... Unsubscribe: https://shipmail.to/u/...",
"headers": {
"List-Unsubscribe": "<https://shipmail.to/u/...>",
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
"Reply-To": "hello@example.com"
},
"archive_html": "<h1>July updates</h1>...",
"warnings": [],
"url_breakdown": { "...": "..." }
}Schedule and lifecycle
POST /v1/newsletters/:id/schedule
POST /v1/newsletters/:id/send-more
POST /v1/newsletters/:id/cancel
POST /v1/newsletters/:id/resumeSchedule accepts { scheduled_at } as an ISO 8601 timestamp. It must be in the future and the newsletter must pass preflight. Scheduling builds the recipient list from the audience, skipping opt-outs and suppressions, then sends at the stored hourly pace. Failed preflight guardrails return 422 validation_error with one detail per failed preflight item.
Engaged first, then send to more
Add limit to the schedule body to send only to that many of the most engaged subscribers: last click first, then last open, then the click and open rates imported from another provider, then join date. The newsletter reports send_limit and held_count, the subscribers still waiting. send-more takes an optional count and sends to the next most engaged held subscribers, or to all of them without it. It works while the newsletter is sending or after it was sent. Nobody gets a newsletter twice, and subscribers you never emailed still go in a first-send slice.
POST /v1/newsletters/nws_abc123/schedule
{ "scheduled_at": "2026-08-01T09:00:00Z", "limit": 500 }
POST /v1/newsletters/nws_abc123/send-more
{ "count": 1000 }Subject test
Set subject_b on create or patch to test a second subject. Each subject goes to subject_test_percent of the subscribers first (1 to 25, default 10). subject_test_hours after both slices finish (1 to 72, default 4), the subject with more human clicks goes to the rest; a tie keeps subject. When the slices include subscribers the organization has never emailed, they are its first-send slice, and the decision waits at least 3 hours. The test needs track_engagement: true, or preflight fails with subject_test. The newsletter reports subject_test_winner (a, b, or null until it decides) and subject_test_decided_at. send-more waits until the test has a winner. Send "subject_b": null to remove the test.
List cleanup at send time
When the audience has list cleanup on, a cold subscriber gets one last-chance email in place of the newsletter, a subscriber who has not answered it is skipped, and one who never answered it within 14 days becomes dormant. These recipients are not counted in the newsletter's recipient_count and other counts. See the Audiences API for the settings.
Recipients
GET /v1/newsletters/:id/recipients
GET /v1/newsletters/:id/recipients/by-email/:emailScopes: newsletters:read and audiences:read, because each row carries a reader's address. The same access rules as GET /v1/newsletters/:id apply. The list returns one row per reader of the issue, newest first, with cursor and limit pagination, and filters by status and reason. The by-email lookup answers why one address did or did not get the issue, or 404 when it is not a recipient of it.
{
"object": "newsletter_recipient",
"id": "nwsrcp_abc123",
"newsletter_id": "nws_abc123",
"email_address": "reader@example.com",
"status": "skipped",
"reason": "opted_out",
"subscriber_id": "audmem_abc123",
"sent_at": null,
"delivered_at": null,
"bounced_at": null,
"complained_at": null,
"unsubscribed_at": null,
"created_at": "2026-08-01T09:00:00.000Z"
}status is one of pending, retrying, sending, sent, delivered, bounced, complained, failed, skipped or unsubscribed. reason is null while the email is on its way or delivered, and otherwise one of the values below. The raw error text from the receiving server is never returned.
| Reason | Meaning |
|---|---|
| opted_out | Skipped: the reader had unsubscribed from your newsletters. |
| suppressed | Skipped: the address is on your suppression list. |
| never_email | Skipped: the address asked Shipmail never to email it, for every sender. |
| undeliverable_domain | Skipped: the reader's domain does not receive email. |
| dormant | Skipped: list cleanup made the reader dormant. |
| last_chance_waiting | Skipped: the reader has not answered the list cleanup last-chance email yet. |
| no_longer_eligible | Skipped: when their turn came, the reader could no longer receive the issue, for example after leaving the audience. |
| cancelled | Skipped: the newsletter was cancelled before their turn. |
| content_in_review | Skipped: a welcome email was held by the content check. |
| email_removed | Skipped: the welcome email was removed from the sequence. |
| skipped_other | Skipped for another reason. |
| bounced | The receiving server refused the email. |
| complained | The reader marked the email as spam. |
| unsubscribed | The reader unsubscribed through this issue. |
| send_failed | Shipmail could not send the email after its retries. |
To hear about bounces, complaints and unsubscribes as they happen, subscribe a webhook to the newsletter.recipient.* events.
Content check
Before a newsletter or welcome email goes out, Shipmail checks it for phishing, malware, scams and abuse. Most go out at once. A newsletter the check holds reports status: "in_review" until a person at Shipmail looks at it. It then returns to scheduled and goes out, or to draft when it cannot be sent, and the owners get an email. cancel still works while it is in review. Subscribers' data is never part of the check.
Changelog example
const newsletter = await shipmail.newsletters.createFromChangelog({
audience_id: "aud_abc123",
sender_identity_id: "nwsid_abc123",
name: "July changelog",
subject: "What shipped in July",
preview_text: "A quick product update",
tone: "friendly",
entries: [
{
title: "Reusable media library",
body: "Search recent newsletter images and videos, then insert them again.",
media: [{ kind: "image", url: "https://cdn.example.com/media-picker.png", alt: "Media picker" }],
},
],
final_cta: { label: "Read the changelog", url: "https://example.com/changelog" },
});
await shipmail.newsletters.preview(newsletter.id);
await shipmail.newsletters.sendTest(newsletter.id, {
recipient_email: "owner@example.com",
});
await shipmail.newsletters.preflight(newsletter.id);
await shipmail.newsletters.schedule(newsletter.id, {
scheduled_at: "2026-08-01T09:00:00.000Z",
});