> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paid newsletter API

> Turn on a paid newsletter, set who reads each post, and read paid subscribers, MRR and conversion.

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:

```json theme={"system"}
{
  "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

```bash theme={"system"}
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

```bash theme={"system"}
# 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

```bash theme={"system"}
curl https://api.pocketsflow.com/newsletters/paid/stats \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

```json theme={"system"}
{
  "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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.