Beehiiv connector for AI agents

Tools your newsletter agent reaches for on Beehiiv, scoped per user.

CALL ANY TOOL

60 tools for newsletters in Beehiiv: create and schedule posts, add and update subscribers, tag and segment readers, enroll them in automations, run exports, and read engagement and post stats.

beehiiv_add_subscription_tags

Add subscription tags

Add one or more tags to a subscriber. Returns the updated subscription. Use this to label subscribers for segmentation. Use beehiiv_update_subscription_by_id for other subscriber changes. Requires a subscription_id from beehiiv_list_subscriptions.

Parameters

Name

Type

Required

Description

publication_id

string

Required

The ID of the beehiiv publication this request applies to. Starts with pub_. Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.

subscription_id

string

Required

The ID of the subscription. Starts with sub_. Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.

tags

array

Optional

Tags that can be used to group subscribers. Example: ["vip","customer"].

beehiiv_add_subscription_to_newsletter_list

List add subscription to newsletter

beehiiv_bulk_create_subscriptions

Bulk create subscriptions

beehiiv_create_post

Post create

Create a post in a publication as a draft or scheduled issue, with HTML or block content. Returns the new post id and a preview url. Use beehiiv_update_post to change an existing post. Set status to confirmed with scheduled_at to schedule it. Use beehiiv_list_publications first to get the publication_id.

Parameters

Name

Type

Required

Description

publication_id

string

Required

The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.

title

string

Required

The title of the post. Example: Weekly Digest.

blocks

array

Optional

Advanced structured content as an array of block objects, each with a type and its content. Prefer body_content (HTML) unless you need block-level control. Example: [{"type":"paragraph","plaintext":"Hello"}].

body_content

string

Optional

The content of the post as a single raw HTML string. The HTML is wrapped in an htmlSnippet block internally. Note that and tags are removed during sanitization, use inline styles for all visual styling. Either this field OR the blocks field must be provided. Example: <h2>Hello</h2>Welcome to this week's issue. .

content_tags

array

Optional

The content tags to use for this post. If not provided, the default value will be used. Example: ["sales"].

custom_fields

object

Optional

Custom field values as an object of field name to value. Example: {"Company":"Acme"}.

custom_link_tracking_enabled

boolean

Optional

If true, custom link tracking will be enabled for this post. If not provided, the default value will be used. Example: true.

email_capture_type_override

string

Optional

The email capture type to use for this post. If not provided, the default value will be used. Allowed values: none, gated, popup. Example: popup. One of: `none`, `gated`, `popup`.

email_settings

object

Optional

Email delivery settings as an object, such as email_subject_line, email_preview_text, from_address, sender_name and reply_to_address. Example: {"email_subject_line":"This week at Acme","email_preview_text":"Five things to read"}.

guest_author_ids

array

Optional

The prefixed IDs of the guest authors to associate with this post. Guest authors must belong to the publication. Obtain IDs from the List Authors endpoint. When provided, replaces all existing guest authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"].

headers

object

Optional

Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}.

newsletter_list_id

string

Optional

The prefixed ID of the newsletter list to associate with this post. When provided, the post will only be sent to subscribers of this list. Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000.

override_scheduled_at

string

Optional

If you wish to display a date other than the scheduled_at date in the email, you can provide a date here. This will not affect the actual publish date of the post. Example: 2025-06-01T09:00:00Z.

post_template_id

string

Optional

The ID of the template to use for the post. If not provided, the default template will be used. Use beehiiv_list_post_templates to find IDs. Example: post_template_00000000-0000-0000-0000-000000000000.

recipients

object

Optional

Audience targeting for the post, given as an object with a web section and an email section, each listing the tiers that can receive the post. Example: {"web":{"tiers":["free","premium"]},"email":{"tiers":["free"]}}.

scheduled_at

string

Optional

The time in which the post will be published. If not provided, the post will be published immediately unless status is set to draft. A draft post cannot be scheduled. Example: 2025-06-01T09:00:00Z.

seo_settings

object

Optional

Search and social metadata as an object, such as default_title, default_description, og_title, og_description, twitter_title and twitter_description. Example: {"default_title":"Weekly Digest","default_description":"Our best reads"}.

social_share

string

Optional

The social share type to use for this post. If not provided, the default value will be used. Allowed values: comments_and_likes_only, with_comments_and_likes, top, none. Example: top. One of: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`.

status

string

Optional

The status of the post. If not provided, the default (draft) value will be used and the post will not be scheduled or published. Explicitly pass confirmed to have the post publish immediately (if no scheduled_at is provided) or at the scheduled_at time. Allowed values: draft, confirmed. Example: active. One of: `draft`, `confirmed`.

subtitle

string

Optional

The subtitle of the post. Example: What happened this week.

team_author_ids

array

Optional

The prefixed IDs of the team members to associate with this post as authors. Team authors must have access to the publication. Note the List Authors endpoint only returns team members who already have a byline on a published post in this publication, so it will not surface IDs for a team member's first assignment. When provided, replaces all existing team authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"].

thumbnail_image_url

string

Optional

The URL of the thumbnail image to use for the post. If not provided, the default value will be used. Example: https://example.com/cover.jpg.

utm_campaign

string

Optional

The utm_campaign appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: launch.

utm_medium

string

Optional

The utm_medium appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: social.

utm_params_enabled

boolean

Optional

Whether UTM parameters are appended to links in this post. Omit to inherit from the newsletter list, then the publication. Example: true.

utm_source

string

Optional

The utm_source appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: twitter.

web_settings

object

Optional

Web page settings as an object, such as slug, hide_from_feed, display_title_on_web, display_subtitle_on_web and display_thumbnail_on_web. Example: {"slug":"weekly-digest","hide_from_feed":false}.

beehiiv_create_subscription_export

Export create subscription

beehiiv_delete_custom_field

Delete custom field

beehiiv_delete_newsletter_list

List delete newsletter

beehiiv_delete_post

Post delete

beehiiv_delete_segment

Delete segment

beehiiv_get_author

Get author

beehiiv_get_automation_journey

Get automation journey

beehiiv_get_custom_field

Get custom field

beehiiv_get_poll

Get poll

beehiiv_get_post_aggregate_stats

Get post aggregate stats

Get aggregate email, web and click statistics across posts in a publication, filtered by audience, platform or status. Returns the combined stats and the time they were computed. Use this for publication-wide totals. Use beehiiv_get_post with expand stats for a single post. Use beehiiv_list_publications first to get the publication_id.

Parameters

Name

Type

Required

Description

publication_id

string

Required

The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.

audience

string

Optional

Optionally filter the results by audience Allowed values: free, premium, all. Example: free. One of: `free`, `premium`, `all`. Default: `all`.

authors

string

Optional

Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive). Example: Filtering for authors: ["John Doe","Jane Smith"] will return results of posts that have either John Doe or Jane Smith as authors. This tool sends a single value per call. Example: Jane Doe.

content_tags

string

Optional

Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it. Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags. This tool sends a single value per call. Example: sales.

hidden_from_feed

string

Optional

Optionally filter the results by the hidden_from_feed attribute of the post. all - Does not restrict results by hidden_from_feed. true - Only return posts hidden from the feed. false - Only return posts that are visible on the feed. Allowed values: all, true, false. Example: false. One of: `all`, `true`, `false`. Default: `all`.

platform

string

Optional

Optionally filter the results by platform. web - Posts only published to web. email - Posts only published to email. both - Posts published to email and web. all - Does not restrict results by platform. Allowed values: web, email, both, all. Example: email. One of: `web`, `email`, `both`, `all`. Default: `all`.

status

string

Optional

Optionally filter the results by the status of the post. draft - not been scheduled. confirmed - The post will be active after the scheduled_at. archived - The post is no longer active. all - Does not restrict results by status. Allowed values: draft, confirmed, archived, all. Example: active. One of: `draft`, `confirmed`, `archived`, `all`. Default: `all`.

beehiiv_get_publication

Get publication

beehiiv_get_segment

Get segment

beehiiv_get_subscription_by_id

Get subscription by id

beehiiv_identify_workspace

Identify workspace

beehiiv_list_authors

List authors

beehiiv_list_automation_journeys

List automation journeys

beehiiv_list_condition_sets

List condition sets

beehiiv_list_newsletter_list_subscriptions

List newsletter list subscriptions

beehiiv_list_poll_responses

List poll responses

beehiiv_list_post_templates

List post templates

beehiiv_list_publications

List publications

beehiiv_list_segment_subscriber_ids

List segment subscriber ids

beehiiv_list_subscription_exports

List subscription exports

beehiiv_list_tiers

List tiers

beehiiv_update_custom_field

Update custom field

beehiiv_update_subscription_by_id

Update subscription by id

Update a subscriber by subscription id, such as tier, custom fields, newsletter lists or unsubscribe status. Returns the updated subscription and any warnings. Use beehiiv_update_subscription_by_email when you only know the email address. Requires a subscription_id from beehiiv_list_subscriptions.

Parameters

Name

Type

Required

Description

publication_id

string

Required

The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.

subscription_id

string

Required

The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.

complimentary_gift_id

string

Optional

The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication. Example: comp_00000000-0000-0000-0000-000000000000.

custom_fields

array

Optional

Custom field changes as an array of objects with a name and a value; add "delete": true to clear a field. Example: [{"name":"Company","value":"Acme"}].

string

Optional

The new email address for the subscription. Example: reader@example.com.

newsletter_list_ids

array

Optional

An array of newsletter list prefixed IDs to subscribe this subscription to. Adds to the subscription's existing list memberships; it does not replace them. The newsletter lists must belong to the same publication. Cannot be combined with unsubscribe. Example: ["list_00000000-0000-0000-0000-000000000000"].

premium_tier_ids

array

Optional

An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with premium_tiers to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["premium_00000000-0000-0000-0000-000000000000"].

premium_tiers

array

Optional

An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with premium_tier_ids to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["Gold"].

stripe_customer_id

string

Optional

The Stripe Customer ID of the subscription (not required). Example: cus_123456789.

tier

string

Optional

Optional parameter to set the tier for this subscription. Allowed values: free, premium. Example: premium. One of: `free`, `premium`.

unsubscribe

boolean

Optional

A boolean value specifying whether to unsubscribe this subscription from the publication (not required). Example: false.

unsubscribe_newsletter_list_ids

array

Optional

An array of newsletter list prefixed IDs to unsubscribe this subscription from. Unsubscribing from a list the subscription is not on is a no-op. The newsletter lists must belong to the same publication, and the same list cannot appear in newsletter_list_ids. Example: ["list_00000000-0000-0000-0000-000000000000"].

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// Beehiiv tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["beehiiv"], toolNames: [
    "beehiiv_list_posts",
    "beehiiv_get_post",
    "beehiiv_create_post"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Summarize last week's newsletter stats and draft next week's issue" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["beehiiv"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Summarize last week's newsletter stats and draft next week's issue" }],
  tools,
});

// Execute the tool call with the user's vaulted Beehiiv access token
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["beehiiv"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Summarize last week's newsletter stats and draft next week's issue" }],
  tools,
});

// Tool call runs with the user's vaulted Beehiiv access token
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["beehiiv"] }, pageSize: 100,
});

const agent = new Agent({
  name: "newsletter_agent",
  model: "gemini-2.5-pro",
  instruction: "Beehiiv tools scoped to this user",
  tools,
});

await agent.run("Summarize last week's newsletter stats and draft next week's issue");

Try these prompts

Copy any prompt into your agent. Each maps directly to a Beehiiv tool. Click to copy, paste into your agent, done.

Posts

Copy the prompt

Copied

Draft a post titled Weekly Product Notes and schedule it for Friday at 8am.

Copy the prompt

Copied

List the posts we published in the last 30 days.

Copy the prompt

Copied

Show the open and click stats for our most recent issue.

Subscribers

Copy the prompt

Copied

Subscribe jane@acme.com to our publication with the tag webinar.

Copy the prompt

Copied

Look up the subscriber alex@globex.com and show their status and tier.

Copy the prompt

Copied

Start an export of every subscriber in the Active Readers segment.

Automations and segments

Copy the prompt

Copied

List the automations in our publication and their status.

Copy the prompt

Copied

Enroll sam@initech.com in the Welcome Series automation.

Copy the prompt

Copied

Recalculate the Engaged 90 Days segment and list its members.

SEE HOW AUTH WORKS

Each user connects their own Beehiiv access token once, and Scalekit sends it with every call. Access tokens stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

Beehiiv

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

Beehiiv

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

Beehiiv

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

Beehiiv

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same per-user auth pattern across other marketing and email connectors.

GTM and RevOps Teams

Competitive intelligence briefing agent

Scans Gong calls for competitor mentions, matches each one to its Notion battlecard, and DMs every affected rep a single Slack digest per cycle. Every call runs as the PMM who owns the briefing, never a shared bot.

GTM and RevOps Teams

Outbound prospecting agent

Searches Apollo for prospects matching your ICP, scores and ranks them, drafts personalized outreach in Gmail, and logs every send to Google Sheets. Mail goes out as the rep, not from a shared inbox.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

A shared Beehiiv access token looks fine in a demo. In production every post and subscriber change looks like one service account, and you cannot tell which user triggered it. Scalekit resolves the credential of the actual user who triggered the agent, never a shared bot.

// shared token
audit → bot_service_account

// scalekit
audit → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

Beehiiv today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access Beehiiv as the user or through a shared access token?

As the user. Each user connects their own Beehiiv access token once, and Scalekit sends it with every call. Audit logs attribute every post and subscriber change to that user, not a shared service account.

Where is the Beehiiv access token stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. To rotate it, the user reconnects with a new access token. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in Beehiiv?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the post and stats tools without beehiiv_delete_subscription, which permanently removes a subscriber. Scalekit also enforces scope checks before every API call.

What happens when a user revokes Beehiiv access?

The connection is invalidated on the next tool call. Subsequent requests for that user fail closed with a clear error. Other users in the tenant remain unaffected. The event is logged for audit.

Which Beehiiv publications can the agent work with?

Every publication the user's access token can reach. beehiiv_list_publications returns them, and each post, subscriber, segment, and automation tool takes a publication id, so one agent can work across several newsletters.