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/subscribeNone

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.

Parameter	Type	In	Description
`slug`required	`string`	path	Newsletter slug (set when creating the newsletter)
`email`required	`string`	body	Subscriber email
`name`	`string`	body	Subscriber display name
`source`	`string`	body	Free-form source tag (e.g. "footer-form", "popup", "embed"). Recorded on the subscriber row.

Request

bash

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

json

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

GET/api/n/confirmNone

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.

Parameter	Type	In	Description
`token`required	`string`	query	JWT-signed token from the confirmation email link

GET/api/n/unsubscribeNone

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.

Parameter	Type	In	Description
`token`required	`string`	query	JWT-signed token from the unsubscribe link

Newsletters

Workflow Automations