Paid newsletter API

The paid newsletter (Growth plan and above) is fully available to API keys and MCP agents. Reads work on every plan. Writes that turn it on answer 403 with code: FEATURE_LOCKED when the plan does not include it:

{
  "error": "FEATURE_LOCKED",
  "code": "FEATURE_LOCKED",
  "upgradeRequired": true,
  "message": "This feature is part of a higher plan. Please upgrade your plan to use it.",
  "details": { "feature": "paidNewsletter", "requiredPlan": "tier2", "requiredPlanName": "Growth" }
}

Endpoints

Method	Path	MCP tool	What it does
`GET`	`/newsletters/paid`	`get_paid_newsletter`	Settings, membership offers, archive link and numbers
`PUT`	`/newsletters/paid`	`update_paid_newsletter`	Turn it on/off, pick the monthly / yearly offers, name it
`GET`	`/newsletters/paid/stats`	`get_newsletter_stats`	Paid subscribers, MRR, free → paid conversion
`POST`	`/newsletters/paid/sync`	`sync_paid_subscribers`	Re-sync the `paid` subscriber tag
`POST`	`/newsletters/posts/{id}/audience`	`set_post_audience`	Set a post’s audience, preview and archive options

POST /newsletters/posts and POST /newsletters/posts/{id} accept the same audience, sendPreviewToFree and publishToWeb fields.

Turn it on

curl -X PUT https://api.pocketsflow.com/newsletters/paid \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "monthlyOfferId": "665f1c2a9b3e4a0012ab34cd",
    "yearlyOfferId": "665f1c2a9b3e4a0012ab34ce",
    "title": "The Studio Letter"
  }'

Both offers must be your own subscription offers, billed monthly and yearly respectively, and in the same test / live mode.

Send a paid post

# 1. Create the post — the paywall marker ends the free preview
curl -X POST https://api.pocketsflow.com/newsletters/posts \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Issue 12",
    "subject": "Issue 12: pricing, part two",
    "preview": "What we changed and why",
    "contentHtml": "<p>Free intro…</p>{{paywall}}<p>The paid part…</p>",
    "sendToAll": true,
    "audience": "paid",
    "publishToWeb": true
  }'

# 2. Send it
curl -X POST https://api.pocketsflow.com/newsletters/posts/<id>/send \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Paid subscribers get the whole post. Free subscribers get everything above {{paywall}} (or an element with data-pf-paywall) plus a subscribe button that opens checkout for your membership. Set sendPreviewToFree: false to send to paid subscribers only. A paid post without a marker sends free subscribers only its subject, preview line and the button.

`audience`	Recipients
`everyone` (default)	Everyone the post targets, whole post
`free`	Only targeted subscribers without a paid membership
`paid`	Paid members: whole post. Free subscribers: preview + CTA

Sending a free / paid post answers 400 with code: PAID_NEWSLETTER_DISABLED while the paid newsletter is off.

Stats

curl https://api.pocketsflow.com/newsletters/paid/stats \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "paidSubscribers": 31,
  "freeSubscribers": 1204,
  "mrrCents": 25500,
  "currency": "USD",
  "conversionRate": 0.0251,
  "monthlyMembers": 24,
  "yearlyMembers": 7,
  "newPaidLast30Days": 9,
  "canceledLast30Days": 2
}

mrrCents counts active and trialing memberships; yearly plans count one twelfth. paidSubscribers also counts members in a payment retry window or paused.

Webhooks

Paid memberships are subscriptions to your membership offers, so the existing customer.subscription.* and invoice.* events cover them — filter on the offer id (subscriptionId).

Overview

API reference

Node.js SDK

Webhooks

Endpoints

Turn it on

Send a paid post

Stats

Webhooks

​Endpoints

​Turn it on

​Send a paid post

​Stats

​Webhooks

Endpoints

Turn it on

Send a paid post

Stats

Webhooks