--- title: "List newsletters" method: GET path: "/newsletters" tags: ["Newsletters"] --- # List newsletters `GET /newsletters` ## Request - Base URL: `https://shipmail.to/api/v1` - URL: `https://shipmail.to/api/v1/newsletters` - 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 newsletters. - object - `data` Newsletter[], required - `object` 'newsletter', required - `id` string, required - `audience_id` string, nullable, required - `sender_identity_id` string, nullable, required - `newsletter_domain_id` string, nullable, required - `name` string, required - `subject` string, nullable - `preview_text` string, nullable - `from_name` string, nullable - `from_address` string - `reply_to_address` string, nullable - `blocks` NewsletterBlock[], nullable: Structured blocks this draft was authored from. body_html and body_text are rendered from these blocks on every draft save. Null for newsletters sent before blocks existed. - union: Structured newsletter block. paragraph.body, quote.body, callout.body, list items, and column bodies accept bare text or restricted inline HTML. Shipmail sanitizes these values when it stores the blocks and renders email-safe HTML and text. - object - `type` 'heading', required - `text` string, required: Heading text. - `level` 1 | 2 | 3 - object - `type` 'paragraph', required - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks and HTML entities for literal tag-like text. - object - `type` 'list', required - `ordered` boolean - `items` string[], required - object - `type` 'callout', required - `title` string, nullable: Optional callout title. - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks. - `variant` 'accent' | 'info' | 'warning' | 'success' - object - `type` 'button', required - `label` string, required: Button label. - `url` string, required: Absolute http, https, or mailto URL. - `align` 'left' | 'center' | 'right': Horizontal alignment of the button. - object - `type` 'image', required - `url` string, uri, required: Hosted HTTPS image URL. - `alt` string, required: Image alt text. - `align` 'left' | 'center' | 'right': Horizontal alignment of the image and its caption. - `link_url` string, nullable: Optional absolute http, https, or mailto image link. - `caption` string, nullable: Optional image caption. - `caption_url` string, nullable: Optional absolute http, https, or mailto caption link. - object - `type` 'video', required - `video_url` string, required: Absolute hosted video URL. Emails render this as a linked thumbnail. - `thumbnail_url` string, uri, required: Hosted HTTPS image thumbnail URL. - `label` string, required: Video link label. - object - `type` 'columns', required - `ratio` '50-50' | '33-67' | '67-33' - `left` union, required - object: Left column content. Include at least one heading, body, image, or CTA field. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - `right` union, required - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object - `type` 'link_list', required - `title` string, nullable: Optional link list title. - `items` object[], required - `label` string, required: Link label. - `url` string, required: Absolute http, https, or mailto URL. - `description` string, nullable: Optional description shown under the link. - object - `type` 'quote', required - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks. - `cite` string, nullable: Optional quote citation. - object - `type` 'divider', required - object - `type` 'spacer', required - `height` integer - object - `type` 'code', required - `code` string, required: Code text. - object - `type` 'custom_html', required - `html` string, required: Custom email-safe HTML fragment. - `body_html` string, nullable: Rendered email HTML, derived from blocks for drafts. Read-only. - `body_text` string, nullable: Plain-text body, derived from blocks unless a manual override was set. Read-only. - `status` 'draft' | 'imported' | 'pending_approval' | 'approved' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled' | 'failed', required - `archive_visibility` 'private' | 'public', required - `feed_entry_url` string, uri, nullable, required: Optional http(s) Atom entry destination. Feed readers link the newsletter title here instead of to its Shipmail web archive, including when the archive is private. - `styling_mode` 'styled' | 'plain', required: styled applies Shipmail's email theme. plain sends your HTML without injected styles, width, or centering, so the reader's email client styles it. - `track_engagement` boolean, required: Whether this newsletter tracks opens and clicks. - `add_utm_tags` boolean, required: Whether this newsletter adds UTM tags to its links. Adds utm_source=shipmail, utm_medium (email or feed) and utm_campaign (a slug of the subject) to the newsletter's http and https links. Links that already carry a utm_ parameter, links with a merge tag in the host, and Shipmail's own unsubscribe and archive links are left alone. The web archive is never tagged. - `opened_count` integer, nullable, required: Unique recipients with at least one counted open. Opens that Apple Mail Privacy Protection preloads are not counted. Null when track_engagement is false. - `clicked_count` integer, nullable, required: Unique recipients who clicked at least one tracked link, excluding clicks attributed to link scanners. Null when track_engagement is false. - `send_limit` integer, nullable, required: The limit the newsletter was scheduled with: only this many of the most engaged subscribers went first. Null sends to everyone. - `held_count` integer, required: Subscribers held past send_limit. Send them the newsletter with POST /newsletters/{id}/send-more. - `subject_b` string, nullable, required: A second subject tested against subject. Requires track_engagement. - `subject_test_percent` integer, nullable: The share of subscribers each subject goes to first, from 1 to 25. Null when there is no subject test. - `subject_test_hours` integer, nullable: Hours after both test slices finish before the subject with more human clicks goes to the rest, from 1 to 72. - `subject_test_winner` 'a' | 'b' | 'null', nullable, required: a is subject, b is subject_b. Null until the test decides. A tie keeps a. - `subject_test_decided_at` string, date-time, nullable - `preflight_status` 'not_run' | 'passed' | 'warning' | 'failed', required - `preflight_results` object - `send_window_hours` integer - `send_rate_per_hour` integer - `recipient_count` integer - `sent_count` integer - `delivered_count` integer - `bounced_count` integer - `complained_count` integer - `failed_count` integer - `skipped_count` integer - `scheduled_at` string, date-time, nullable - `approved_at` string, date-time, nullable - `started_at` string, date-time, nullable - `published_at` string, date-time, nullable, required: Stable first-publication timestamp. - `archive_url` string, uri, nullable, required: Canonical Shipmail public archive URL. - `completed_at` string, date-time, nullable - `cancelled_at` string, date-time, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `last_test_sent_at` string, date-time, nullable - `last_test_recipient` string, nullable - `content_changed_since_test_send` boolean - `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)