Integrations · Beehiiv

Beehiiv (newsletters)

Beehiiv is an optional email delivery channel on a publication, independent of the web destination. Author once in Compose; when an article is worth emailing, Esy transforms it into email-safe HTML and creates a draft in your own Beehiiv account. Nothing sends from Esy — you review and hit send in Beehiiv.

The model

A publication can publish through two independent channels. Wire either, or both — a newsletter-only publication (no website at all) is just one with the web fields left blank.

Channel	Wiring	“Publish” means
Web	`siteUrl` + `sectionPath` + revalidate webhook	The article goes live on your site.
Email	Beehiiv connection (your publication id + API key)	The article becomes a Beehiiv draft, per article and opt-in.

Opt-in per article, draft-first

Publishing to the web never emails anyone. “Send to newsletter” is a separate, per-article action that is off by default — publish daily for SEO without ever blasting subscribers — and it only ever creates a draft: sending stays a deliberate step inside Beehiiv.

What Esy sends to Beehiiv

The article’s editor content is transformed into conservative, email-safe HTML — Beehiiv wraps it in your newsletter’s template (header, footer, fonts, unsubscribe). Per-node rules:

Content	Email treatment
Headings, paragraphs, lists, quotes, links	Pass through, escaped. Only http(s)/mailto links survive.
Images	Absolute public URLs only, constrained to the email column width.
Video	Inboxes can’t play video — it becomes the poster image linking to the article on your site (or Mux’s hosted player for newsletter-only publications).
Citations	Flattened to numbered [n] references with a Sources list appended.
Anything else (embeds, scripts)	Dropped — never passed through raw.

The email’s subject line and preview text are collected when you create the draft (prefilled from the article title) and stored on the document, so a later re-draft reopens with the same values.

Security

The Beehiiv API key is write-only: submitted once, encrypted at rest, and never returned by any endpoint — responses expose only hasBeehiivKey.
The connection is owner-scoped and self-serve — it’s your own Beehiiv account and key, bound to your own publication.

Requirements

Beehiiv plan gating

Beehiiv gates its create-post API by plan tier (Enterprise, in beta on their side at time of writing). Connecting and verifying work on any plan; if draft creation isn’t available on yours, the error says exactly that. Check your Beehiiv plan before relying on the draft flow.

API surface

All endpoints are authenticated and owner-scoped.

POST/v1/publications/{id}/newsletterConnect (or re-connect) the Beehiiv channel: beehiivPublicationId + beehiivApiKey.

DELETE/v1/publications/{id}/newsletterDisconnect the email channel; the web destination is untouched.

POST/v1/publications/{id}/newsletter/verifyLive round-trip to Beehiiv proving the key and publication id resolve.

POST/v1/documents/{id}/newsletter/draftTransform the article and create a Beehiiv draft: { subject?, previewText? }.

The document records provenance: newsletterStatus ("" | "draft"), the Beehiiv post id, when the draft was created, and the subject/preview used.

Ready to wire it up? Follow the step-by-step Send articles to Beehiiv guide, and see Publications for the delivery-channel model.