Public Newsletter Flows

Public, unauthenticated endpoints used by the hosted subscribe page, embed widget, and one-click unsubscribe links. Subscribe → DOI confirm → unsubscribe lifecycle.

These endpoints are called by users (subscribers), not by your backend, and don't require an API key. They live under /api/n/... on the dashboard host (e.g. https://app.posthawk.dev/api/n/...) — NOT on the worker API.

Use cases:

Hosted subscribe page — Posthawk renders a public page at /n/[slug] for each newsletter where users can sign up. The page POSTs to /api/n/[slug]/subscribe.
Embed widget — drop a <script> tag on your site to embed the same form. Behind the scenes it uses the same subscribe endpoint.
DOI confirmation links — when double opt-in is enabled, the email Posthawk sends to confirm the subscription contains a link to /api/n/confirm?token=....
One-click unsubscribe — every email Posthawk sends includes List-Unsubscribe headers and an unsubscribe link in the footer pointing to /api/n/unsubscribe?token=....

These endpoints are abuse-protected (rate-limited per IP, suppression list checked, disposable email domains blocked) and DO NOT require any authentication header. They're safe to call from a frontend.

POST/api/n/:slug/subscribe

Subscribe an email address to a newsletter by slug. If the newsletter has DOI on, the subscriber starts as `pending` and a confirmation email is sent. If DOI is off, the subscriber goes straight to `active`. Idempotent — re-subscribing an existing email returns success without re-sending the confirmation.

Authorizations

No authentication required — this is a public endpoint.

Path Parameters

slugstringrequired

Newsletter slug (set when creating the newsletter)

Body

emailstringrequired

Subscriber email

namestringoptional

Subscriber display name

sourcestringoptional

Free-form source tag (e.g. "footer-form", "popup", "embed"). Recorded on the subscriber row.

POST /api/n/:slug/subscribe

curl -X POST https://app.posthawk.dev/api/n/weekly-digest/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "email": "subscriber@example.com",
    "name": "Jane",
    "source": "footer-form"
  }'

Response

{
  "success": true,
  "status": "pending",
  "message": "Check your email to confirm your subscription."
}

GET/api/n/confirm

Confirm a pending subscription via the token sent in the DOI email. Flips status to `active`. Renders an HTML confirmation page (success or error) — designed to be hit directly by clicking the email link.

Authorizations

No authentication required — this is a public endpoint.

Query Parameters

tokenstringrequired

JWT-signed token from the confirmation email link

GET /api/n/confirm

curl "https://app.posthawk.dev/api/n/confirm?token=your_token"

GET/api/n/unsubscribe

One-click unsubscribe. Marks the subscriber as `unsubscribed`, fires the `newsletter_unsubscribed` automation trigger, and renders a confirmation HTML page. Linked from the footer of every newsletter email and the List-Unsubscribe header.

Authorizations

No authentication required — this is a public endpoint.

Query Parameters

tokenstringrequired

JWT-signed token from the unsubscribe link

GET /api/n/unsubscribe

curl "https://app.posthawk.dev/api/n/unsubscribe?token=your_token"

Newsletters

Workflow Automations