The NewsletterScriv API

A small API for putting things into an author’s NewsletterScriv account: subscribers arrive with their consent evidence attached, campaigns arrive as drafts the author sends themselves, and landing pages arrive unpublished until someone publishes them. Built for book-delivery services, giveaway platforms, authors’ own websites—and, over MCP, their AI assistants.

Authentication

The author creates a key under Account settings → API keys and pastes it into your service. Send it on every request as X-Api-Key: nsk_live_… (or Authorization: Bearer nsk_live_…). Keys can carry a default audience, so most callers never need an audienceId.

Create or update a subscriber

POST https://newsletterscriv.com/api/v1/subscribers

Field	Type	Notes
`email`	string, required	Normalized and deduplicated per audience.
`audienceId`	string	Optional when the key has a default audience.
`firstName` / `lastName`	string	`first_name`/`last_name` accepted too.
`source`	string	Where this signup came from—shows on the contact.
`tags`	string[]	Created if missing; can trigger the author’s automations.
`fields`	object	Custom field values by key, e.g. `{ "birthday": "1985-03-15" }`. Keys must already exist under the audience’s Fields page; dates are `YYYY-MM-DD`. An unknown key or an unparseable value is a `400` naming it. A date field can start an automation on the day, or N days before or after it—see the automation trigger “On a date a reader gave”.
`consentAt`	ISO date	Consent evidence, stored verbatim—pass what you captured at signup. If you send `consentIp` or `consentText` without `consentAt`, `consentAt` is set to the time of your request. Send none of the three and all stay empty.
`consentIp`	string
`consentText`	string
`doubleOptIn`	boolean	Default `false`—set `true` to send the author’s confirmation email instead of subscribing directly.
`removeTags`	string[]	Tag names to take off a reader who is already in the audience. Removing a tag never starts an automation; a name the audience doesn’t have is ignored. A name can’t be in both `tags` and `removeTags`.
`clearFields`	string[]	Custom field keys to empty on a reader who is already in the audience, e.g. `["lactation_status"]`. Keys must exist under the Fields page. Empty values in `fields` are ignored, so this is the way to blank one.

Example

curl -X POST https://newsletterscriv.com/api/v1/subscribers \
  -H "X-Api-Key: nsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "reader@example.com",
    "firstName": "Robin",
    "source": "bookfunnel",
    "tags": ["BookFunnel", "spring-giveaway"],
    "fields": { "birthday": "1985-03-15" },
    "consentAt": "2026-07-16T14:03:00Z",
    "consentIp": "203.0.113.9",
    "consentText": "Sign up for Elle E. Kay\u2019s newsletter to get your free book."
  }'

Semantics your retry logic can rely on

Idempotent. An existing contact returns ok: true, duplicate: true—post the same reader daily and nothing breaks or double-fires. A repeat post still adds any tags in it that the contact doesn’t already have (only those newly added tags can start the author’s automations), merges fields, and fills in firstName if it was blank. It doesn’t change the contact’s status, lastName, or source.
Suppression-safe. A new address on the suppression list—unsubscribed (by the reader or by the author from the dashboard), hard-bounced, marked as spam, or a known spam trap—is skipped and still returns ok: true, so your service never learns who is suppressed. With doubleOptIn: true, an address suppressed because it unsubscribed gets the confirmation email instead, and clicking it is how they rejoin; bounces, spam reports, and spam traps are always skipped. An address already in the audience is never skipped this way: it returns duplicate: true and its status doesn’t change, so an unsubscribed reader stays unsubscribed.
No rate limit today. /api/v1 doesn’t enforce a request rate right now. Send one request per subscriber at a steady pace; there is no batch endpoint.
Consent is recorded as you send it. consentIp and consentText are stored exactly as sent and never made up. The one default: when consentIp or consentText arrives without consentAt, consentAt is set to the time of your request. With no consent fields at all, all three stay empty.

Responses

200 { ok: true, id, duplicate?, held? }—created (or already present). held: true means the reader is saved and waiting to receive campaigns until the account has room on a hard subscriber cap. Scale never sets it.
200 { ok: true, skipped: "no-email" }—the request had no email; nothing was created.
400—malformed JSON, missing audienceId (when the key has no default), or { error: "invalid email" } for an address that can’t be parsed.
401—missing or revoked key.
403 { error: "api_access_required" }—the account isn’t on a paid plan, so its keys can’t use the API.
403 { error: "account_suspended", message }—the account is suspended; its data is intact.
404—audienceId not on the key’s account.

Errors are JSON with an error code, plus a human-readable message or hint where one helps. The 401 and both account-level 403s (api_access_required, account_suspended) apply to every /api/v1 endpoint.

Update an existing subscriber

PATCH https://newsletterscriv.com/api/v1/subscribers

Same body as POST (email, audienceId, firstName, lastName, fields, tags, removeTags, clearFields), but it never creates anyone: a reader who isn’t in the audience is a 404 { error: "subscriber not found" }. A sent firstName or lastNamereplaces the stored one. Newly added tags can start the author’s automations, exactly as with POST; removals never do. It never changes the reader’s status, consent or source, so an unsubscribed reader stays unsubscribed. Returns 200 { ok: true, id }. Over MCP this is the update_subscriber tool.

List the account’s audiences

GET https://newsletterscriv.com/api/v1/audiences

Read-only. Returns the newsletter audiences (lists) on the key’s account, so your integration can let the author pick a list by name and send its id as audienceId when adding subscribers.

curl https://newsletterscriv.com/api/v1/audiences \
  -H "X-Api-Key: nsk_live_..."

Response:

{
  "audiences": [
    {
      "id": "aud_...",
      "name": "Cozy Mystery Readers",
      "fromName": "Elle E. Kay",
      "fromEmail": "elle@example.com",
      "subscriberCount": 1234
    }
  ]
}

401 for a missing or revoked key; 403 as above.

List the account’s forms

GET https://newsletterscriv.com/api/v1/forms

Read-only. Returns every signup form on the key’s account so your integration can let the author pick a form by name instead of pasting an id—this is how the NewsletterScriv WordPress plugin fills its form menus. A valid key returns 200, so it doubles as a connection test.

curl https://newsletterscriv.com/api/v1/forms \
  -H "X-Api-Key: nsk_live_..."

Response: { account: { name }, forms: [{ id, name, audienceId, audienceName, type }] }. 401 for a missing or revoked key.

Create a draft campaign

POST https://newsletterscriv.com/api/v1/campaigns

Creates a draftin the author’s dashboard—and that is all it can do. This endpoint cannot send, schedule, or edit anything: the author opens the draft, reviews it, and sends from the dashboard, where their sending safeguards live. The From name and address always come from the audience’s settings, never from the request.

Field	Type	Notes
`subject`	string	The email’s subject line.
`bodyText`	string	Plain text; blank lines separate paragraphs. Merge tags like `{{firstName\|friend}}` work.
`name`	string	Internal name in the campaign list. Defaults to “Untitled campaign”.
`preheader`	string	Inbox preview text.
`audienceId`	string	Optional when the key has a default audience.

curl -X POST https://newsletterscriv.com/api/v1/campaigns \
  -H "X-Api-Key: nsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September newsletter",
    "subject": "Three things I learned writing book four",
    "bodyText": "Hello {{firstName|friend}},\n\nThe first draft is done..."
  }'

Response: { ok: true, id, status: "draft", editUrl }—editUrl opens the draft in the dashboard editor. Fields like status or a schedule are ignored if sent; a draft is the only thing this endpoint can make.

Landing pages

GET https://newsletterscriv.com/api/v1/landing-pages · POST https://newsletterscriv.com/api/v1/landing-pages · GET https://newsletterscriv.com/api/v1/landing-pages/<id> · PATCH https://newsletterscriv.com/api/v1/landing-pages/<id>

Create, edit, and publish the author’s landing pages (/l/<slug>). Pages are created unpublished; send { "published": true } to PATCH to put one live. These calls go through the same checks as the page builder: the plan’s landing-page limit, a hosted signup form from the same audience (required to publish), slugs that are unique across NewsletterScriv (a taken slug returns 409), and the builder’s content clean-up (text only, no HTML; https images only; long text clipped). There is no DELETE.

Field	Type	Notes
`audienceId`	string	Create only. Optional when the key has a default audience.
`title`	string	Dashboard name and slug source. Defaults to the headline.
`slug`	string	Optional. Made from the title (and kept unique) when omitted.
`formId`	string	A hosted form on the audience (see `type` in the forms list). Defaults to the audience’s first hosted form.
`headline`, `tagline`, `body`, `imageUrl`, `signupHeading`, `signupBody`, `buttonLabel`	string	Simple content. On PATCH they edit the current design in place.
`spec`	object	Advanced: the whole design in the builder’s stored format (theme + sections). Not combined with the simple fields.
`published`	boolean	PATCH only.

curl -X POST https://newsletterscriv.com/api/v1/landing-pages \
  -H "X-Api-Key: nsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Free novella",
    "headline": "Get the prequel free",
    "tagline": "A cozy mystery to start the series",
    "body": "Join my readers and I\u2019ll send it today.",
    "imageUrl": "https://example.com/hero.jpg",
    "formId": "frm_..."
  }'

Response: { ok: true, landingPage: { id, slug, title, published, formId, publicUrl, editUrl, spec, … } }. 403 plan_limit at the plan’s page limit; 404 for an audience, page, or form not on the key’s account; 409 form_required when publishing without a form.

Connect an AI assistant (MCP)

POST https://newsletterscriv.com/api/mcp

The same account-scoped operations as this API—plus profile, audiences, campaigns metadata, aggregate send stats, books, magnets, and landing pages—exposed as an MCP server (streamable HTTP, stateless). Authors wire NewsletterScriv into Claude, Cursor, ChatGPT, or another MCP-capable assistant. Campaigns are drafts only, never sent (there is no send_campaign tool). Landing pages can be listed, created, edited, and published; new pages start unpublished, and the tool descriptions tell the assistant to check with the author before publishing. No tool deletes anything. Fourteen tools in all; the self-test below names them.

Two auth modes:

API key (Claude Code / Cursor): Authorization: Bearer nsk_live_… or X-Api-Key—never put the key in the URL.
OAuth 2.1 (ChatGPT-class): Authorization Code + PKCE. Discover via https://newsletterscriv.com/.well-known/oauth-protected-resource; authorize at https://newsletterscriv.com/api/mcp/oauth/authorize; token at https://newsletterscriv.com/api/mcp/oauth/token; Dynamic Client Registration at https://newsletterscriv.com/api/mcp/oauth/register. Resource indicator: https://newsletterscriv.com/api/mcp.

In-app setup guide (signed in): Account settings → MCP setup. For Claude Code:

claude mcp add --transport http newsletterscriv https://newsletterscriv.com/api/mcp \
  --header "Authorization: Bearer nsk_live_..."

GET https://newsletterscriv.com/api/mcpwith a Bearer / X-Api-Key header is a self-test—it names the account and tools. Opening that URL in a browser without a key shows plain-English setup help (JSON when Accept: application/json, with a WWW-Authenticate challenge pointing at OAuth metadata).

BookFunnel webhook receiver

POST https://newsletterscriv.com/api/integrations/bookfunnel?key=nsk_live_…&audienceId=…

Accepts BookFunnel’s outbound webhook payload as-is (JSON or form parameters)—the author pastes this URL straight into BookFunnel’s Integrations panel, no middleware. The key rides in the URL because BookFunnel’s webhook config can’t send headers. audienceId is required on the URL (or as the key’s default)—BookFunnel cannot send one. Only the new_subscriber (opt-in) event subscribes anyone; book_claimed is acknowledged and ignored. Every signup is tagged BookFunnel and BookFunnel page <page_id>, so a per-magnet automation can trigger on the page tag; add &tag=… (repeatable) to the URL to apply tags you name yourself. GET the same URL for a config self-test—it names the audience it will feed and the tags it applies. Setup guide: Using BookFunnel with NewsletterScriv.

Building a native integration?

If you run a platform authors love and want “paste your NewsletterScriv key” to be all your setup asks of them, we’d like that too—write to support@newsletterscriv.com.