Newsletters

Create a newsletter draft

Create a draft newsletter. Drafts must be tested and pass preflight before scheduling.

post/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)

Headers

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

audience_idstring required
sender_identity_idstring required
namestring required
subjectstring required
preview_textstring nullable
body_htmlstring nullable

Full HTML body. Stored as one custom_html block when blocks are not provided.

body_textstring nullable

Plain-text body. Becomes paragraph blocks when blocks are not provided. With blocks or body_html, sets the plain-text override.

send_window_hoursinteger
archive_visibility'private' | 'public'
feed_entry_urlstring uri nullable

Optional http(s) Atom entry destination. Overrides the public web archive link.

styling_mode'styled' | 'plain'

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_engagementboolean

Track opens and clicks for this newsletter. Defaults to false. Returns 422 validation_error when open and click tracking is not available. Can only change while the newsletter is an editable draft or a future scheduled newsletter.

add_utm_tagsboolean

Add UTM tags to the links of this newsletter. Defaults to false. 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. Can only change while the newsletter is an editable draft or a future scheduled newsletter.

content_markdownstring

The body as Markdown, instead of blocks or body_html. Shipmail converts headings, paragraphs, lists, quotes, code, images, links, dividers and tables to blocks and stores blocks only. A callout starts with a line :::callout (optionally followed by info, warning or success, then a title) and ends with a line :::. Raw HTML stays visible text. Send only one of blocks, body_html or content_markdown.

subject_bstring nullable

A second subject to test against subject. Each goes to a slice of subject_test_percent of the subscribers; after subject_test_hours the one with more human clicks goes to the rest. Opens do not decide, because Apple Mail Privacy Protection opens every message. Requires track_engagement. Null removes the test.

subject_test_percentinteger nullable
subject_test_hoursinteger nullable

Response

Newsletter draft created.

object'newsletter' required
idstring required
audience_idstring nullable required
sender_identity_idstring nullable required
newsletter_domain_idstring nullable required
namestring required
subjectstring nullable
preview_textstring nullable
from_namestring nullable
from_addressstring
reply_to_addressstring nullable
body_htmlstring nullable

Rendered email HTML, derived from blocks for drafts. Read-only.

body_textstring 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_urlstring 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_engagementboolean required

Whether this newsletter tracks opens and clicks.

add_utm_tagsboolean 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_countinteger 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_countinteger nullable required

Unique recipients who clicked at least one tracked link, excluding clicks attributed to link scanners. Null when track_engagement is false.

send_limitinteger nullable required

The limit the newsletter was scheduled with: only this many of the most engaged subscribers went first. Null sends to everyone.

held_countinteger required

Subscribers held past send_limit. Send them the newsletter with POST /newsletters/{id}/send-more.

subject_bstring nullable required

A second subject tested against subject. Requires track_engagement.

subject_test_percentinteger nullable

The share of subscribers each subject goes to first, from 1 to 25. Null when there is no subject test.

subject_test_hoursinteger 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_atstring date-time nullable
preflight_status'not_run' | 'passed' | 'warning' | 'failed' required
preflight_resultsobject
send_window_hoursinteger
send_rate_per_hourinteger
recipient_countinteger
sent_countinteger
delivered_countinteger
bounced_countinteger
complained_countinteger
failed_countinteger
skipped_countinteger
scheduled_atstring date-time nullable
approved_atstring date-time nullable
started_atstring date-time nullable
published_atstring date-time nullable required

Stable first-publication timestamp.

archive_urlstring uri nullable required

Canonical Shipmail public archive URL.

completed_atstring date-time nullable
cancelled_atstring date-time nullable
created_atstring date-time required
updated_atstring date-time required
last_test_sent_atstring date-time nullable
last_test_recipientstring nullable
content_changed_since_test_sendboolean

Changes

No recorded changes to this operation across all 1 revision of this API.