beehiiv API + MCP (2026): v2 REST, official MCP, Send API on Max

beehiiv runs one REST generation only: v2, based at api.beehiiv.com/v2 and current since December 2, 2022. It covers roughly two dozen resource families, subscriptions, posts, segments, automations, webhooks, polls, podcasts and beehiiv’s own ad network, behind a bearer token and one organisation-wide budget of 180 requests per minute. The MCP story is the unusual part: beehiiv shipped a first-party server on March 24, 2026, opened read access to every plan including free Launch, and added write actions on June 16, 2026 – ahead of most newsletter platforms and most transactional ESPs alike.

At a glance

MCP integration in 2026

Model Context Protocol is how an AI client reaches a product’s data and actions without a bespoke integration. Most ESPs in 2026 have nothing first-party. beehiiv is one of the few exceptions, and its entitlement model is more generous than its own API gating would suggest.

Available MCP servers

One first-party server, two independent open-source wrappers and a Zapier bridge. Only the official server reaches beehiiv’s growth and monetisation surfaces; the rest wrap the public v2 REST API and inherit its plan gates and its 180/minute ceiling.

beehiiv API essentials

Everything here is REST over HTTPS returning JSON. beehiiv exposes no SMTP relay and no transactional endpoint, so the API is the entire programmable surface, see the SMTP settings tab for why that absence is architectural.

The resource model is publication-scoped and almost entirely uniform: /v2/publications/{publicationId}/{resource}. The first call any integration writes is therefore GET /v2/publications to resolve the ID, which looks like pub_ plus a UUID. A request outside a scoped key’s publications returns 404 Not Found, not a permission error, which sends developers hunting for a missing record when the problem is the key. Capability splits by plan: reading and subscriber management on free Launch, webhooks from Scale, dispatching a newsletter only on Max.

Authentication methods

Bearer API keys

The default path. Keys live under Settings › Workspace Settings › API and travel as Authorization: Bearer <token>. Two constraints bite first: “You must be a workspace Owner or Admin role to access your API keys”, and Stripe Identity verification is mandatory before a key can be generated at all. The key is displayed once, “This is the only time you will see this API key.” There is no reveal-later screen, only rotation.

OAuth2 with scopes

For anything distributed to other people’s publications, beehiiv’s guidance is unambiguous: “Building an integration? Use OAuth2 instead of API keys.” Grants are granular – posts:read, posts:write, subscriptions:write, publications:read, automations:read, segments:read, webhooks:write and others, so a reporting tool never holds write capability and revocation is per-install. An API key is fine for an internal script; for anything a customer installs, OAuth2 is the only defensible choice.

Rate limits

The workaround is arithmetic, not cleverness. At 100 records per page a 50,000-subscriber walk is 500 calls, nearly three minutes of polling during which nothing else on the account can run. Hence the separate Exports resource: fire an asynchronous export for anything bulk, and use Bulk Subscription Updates rather than one POST per record. Middleware that auto-detects X-RateLimit-Remaining sees nothing here, so backoff logic has to be explicit.

No hourly send rate, per-message recipient cap or message size limit appears in any official document, and Enterprise is described only as having “custom limits”.

Official SDKs

beehiiv maintains exactly one, and its beta warning should be taken literally. Everything else on a package registry is community work, however official the name looks.

Notable community SDKs

There is no official Python client. PyPI carries community packages including beehiiv and beehiiv-python-client, neither published by beehiiv, and beehiiv’s GitHub organisation holds no Python repository. For Python the honest recommendation is plain requests against a stable, offset-paginated REST API, as the example below does. Other ecosystems are served by Zapier, Make and Pipedream connectors rather than SDKs.

Endpoints reference

Roughly two dozen resource families, all nested under a publication except the publication list itself. The live reference is at developers.beehiiv.com/api-reference; the older /docs/v2/ tree returns 404, so any tutorial linking there is a documentation generation stale.

Five more families follow the same scheme: Tiers, Referral Program, Polls, Podcasts and Ad Network, a monetisation surface with no equivalent in a transactional API like Postmark or Amazon SES.

Code examples

Python: subscribe, paginate, send

Plain requests, because there is no official Python SDK. Note the explicit status on the send.

import os
import requests

BASE = "https://api.beehiiv.com/v2"
PUB_ID = os.environ["BEEHIIV_PUBLICATION_ID"]   # pub_xxxxxxxx-...
HEADERS = {
    "Authorization": f"Bearer {os.environ['BEEHIIV_API_KEY']}",
    "Content-Type": "application/json",
}


def add_subscriber(email):
    """Works on every plan, free Launch included."""
    r = requests.post(
        f"{BASE}/publications/{PUB_ID}/subscriptions",
        headers=HEADERS,
        json={"email": email, "reactivate_existing": False,
              "send_welcome_email": True, "utm_source": "website"},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]


def send_post(title, paragraphs):
    """THE SEND API. Max ($96/mo) or Enterprise only.

    Since 2026-08-06, omitting status creates a DRAFT.
    """
    r = requests.post(
        f"{BASE}/publications/{PUB_ID}/posts",
        headers=HEADERS,
        json={"title": title,
              "blocks": [{"type": "paragraph", "plaintext": p}
                         for p in paragraphs],
              "status": "confirmed"},
        timeout=60,
    )
    r.raise_for_status()   # 402/403 = plan lacks the Send API
    return r.json()["data"]

Node: retry-aware client with cursor-free pagination

The 429 branch reads RateLimit-Reset as epoch seconds and sleeps to that instant rather than guessing a delay, which matters when the whole organisation shares one bucket.

// beehiiv v2 REST. There is no SMTP transport to fall back on.
const BASE = "https://api.beehiiv.com/v2";
const PUB_ID = process.env.BEEHIIV_PUBLICATION_ID; // pub_xxxxxxxx-...
const headers = {
  Authorization: `Bearer ${process.env.BEEHIIV_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, init = {}) {
  const res = await fetch(`${BASE}${path}`, { ...init, headers });
  if (res.status === 429) {
    // 180 req/min per ORGANISATION; reset is Unix epoch seconds
    const reset = Number(res.headers.get("RateLimit-Reset"));
    const waitMs = Math.max(0, reset * 1000 - Date.now()) + 250;
    await new Promise((r) => setTimeout(r, waitMs));
    return call(path, init);
  }
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

// limit caps at 100, default is only 10 - always set it explicitly.
export async function* allSubscribers() {
  let page = 1;
  for (;;) {
    const body = await call(
      `/publications/${PUB_ID}/subscriptions?page=${page}&limit=100`
    );
    yield* body.data;
    if (page >= body.total_pages) return;
    page += 1;
  }
}

// THE SEND API - Max ($96/mo) or Enterprise. Omit status and you
// get a draft, silently, with a 201 and a real post ID.
export async function sendPost(title, paragraphs) {
  const { data } = await call(`/publications/${PUB_ID}/posts`, {
    method: "POST",
    body: JSON.stringify({
      title,
      blocks: paragraphs.map((p) => ({ type: "paragraph", plaintext: p })),
      status: "confirmed",
    }),
  });
  return data;
}

Common gotchas

Deprecations and changelog

• September 10, 2026 – Boosts is renamed paid recommendations. Email Boosts and Direct Links are discontinued; auto-clean is replaced by subscriber verification tags.
• August 6, 2026 – The pivotal developer release. The Send API expands from Enterprise-only to Max and gains preview URLs and audience confirmation; Click Triggers ship on Max and Enterprise; and posts created without an explicit status begin defaulting to draft.
• July 9, 2026 – “Recommendations Reimagined” launches the Recommendation Network alongside paid recommendations.
• June 16, 2026 – MCP write access arrives, billed as “The most-requested MCP feature”, across all paid plans. Read access opens to every plan including free Launch.
• April 30, 2026 – beehiiv MCP v2 ships with expanded availability.
• March 24, 2026 – beehiiv MCP launches read-only and paid-plans-only, positioned for subscriber analysis, SEO audits and churn detection.

Release notes live at product.beehiiv.com. No v2 endpoint has been deprecated to date; the breaking change of 2026 was a default value, not a removal, which is exactly why it caught so many integrations.

Frequently asked questions