Reference · Guides

Send articles to Beehiiv

Wire a publication to your own Beehiiv newsletter once, then turn any article into an email-safe Beehiiv draft per article, on demand. Esy never sends email — you review and send inside Beehiiv, so a daily publishing cadence never blasts your subscribers.

Before you start

A publication in Compose (any publication works — the newsletter channel is independent of the web destination, so even a publication with no website qualifies).
A Beehiiv account with an API key and your Beehiiv publication id (pub_…) — both in the Beehiiv dashboard under Settings → API.

Check your Beehiiv plan first

Beehiiv gates its create-post API by plan tier (Enterprise, in beta on their side). Connecting and verifying work on any plan; creating drafts requires a plan that includes API post creation. If yours doesn’t, the draft step returns exactly that message.

Steps

Connect Beehiiv to the publication
In Compose, open your publication → Connect tab → Newsletter (Beehiiv). Paste your Beehiiv publication id and API key, then hit Connect Beehiiv. The key is encrypted at rest and never shown again — you can replace it later, but not read it back.
Verify the connection
Click Verify. Esy makes a live round-trip to Beehiiv with your stored key — success shows your newsletter’s name; failure tells you precisely what’s wrong (bad key, wrong publication id, unreachable).
Write and file an article
Author normally in Compose and file the article into the connected publication in Details. Publishing to the web stays exactly as before — and never emails anyone.
Create the Beehiiv draft
In the editor’s Details panel, a Newsletter section appears (only for connected publications). Click Send to newsletter…, set the subject line (prefilled from the title) and preview text, and hit Create Beehiiv draft.
Review and send in Beehiiv
The section flips to Draft created with a Review & send in Beehiiv link. Open the draft in Beehiiv, check the rendering, pick your audience, and send from there — that final step always stays in Beehiiv.

What the draft contains

Esy transforms the article into email-safe body HTML and Beehiiv wraps it in your newsletter’s own template. The notable degradations:

In the article	In the email
Text, headings, lists, quotes, links	Rendered normally (escaped; only web/mailto links kept).
Images	Kept — constrained to the email column width.
Video	A thumbnail linking to the published article (inboxes can’t play video).
Citations	Numbered [n] references plus a Sources list at the end.

Doing it over the API

The Compose UI is a thin layer over one endpoint — pipelines can create drafts directly. Subject falls back to the stored value, then the article title; whatever is used persists on the document for the next draft.

create a draftjson

POST /v1/documents/{documentId}/newsletter/draft
{
  "subject": "How to get started with AI",
  "previewText": "A practical on-ramp — no jargon, no math."
}

// 200
{
  "status": "draft",
  "beehiivPostId": "post_8f0c2a1e-…",
  "draftedAt": "2026-07-03T14:02:11.004Z",
  "reviewUrl": "https://app.beehiiv.com/posts"
}

Troubleshooting

Symptom	Cause & fix
Verify fails with a 401 message	Beehiiv rejected the API key — re-copy it from Beehiiv Settings → API and use Replace key.
Verify fails with a 404 message	The publication id doesn’t belong to that key. Check you copied the pub_… id from the same Beehiiv workspace as the key.
Draft creation says it may not be available on this plan	Beehiiv’s create-post API is plan-gated (Enterprise). Connect/verify still work; upgrade the Beehiiv plan to create drafts via API.
No Newsletter section in the Details panel	The article isn’t filed into a publication with a Beehiiv connection — file it in Details, and connect Beehiiv in the publication’s Connect tab.
Video shows as an image in the email	Expected — email clients can’t play video, so it degrades to a poster linking to the article (or Mux’s hosted player for newsletter-only publications).

For the integration model, security posture, and full endpoint list, see the Beehiiv integration reference.