beehiiv: what this connector can do

Member·9 minutes to read

What this page is for

docs/connectors/beehiiv-api.md is the setup guide for whoever runs your organisation's Botseon deployment: registering the beehiiv OAuth app and entering its credentials. This page is the other half: what beehiiv lets a bot do once it is connected to your workspace, what you need on the beehiiv side, what it asks you for, what can go wrong, and how to take the connection away again, in Botseon and at beehiiv.

Read your publications, posts, subscribers and segments, draft a post, and add, tag or unsubscribe a subscriber. A bot never publishes, schedules or sends a post: everything it writes is a draft that waits for you in beehiiv's editor.

The catalogue also has a beehiiv tile for beehiiv's own hosted MCP server. That is a separate plugin with beehiiv's own tool list; this page is about the beehiiv connector.

Before you start

A beehiiv workspace, and a beehiiv account that can sign in to it. You sign in to beehiiv yourself when you connect; Botseon never sees your password.
Your organisation's beehiiv app. beehiiv only lets registered apps ask for access, and an app is registered by asking beehiiv Support. Whoever runs your deployment does that once and enters it (setup guide). Until they have, Authenticate says the connector is not set up.
The right plan for drafts. beehiiv lets an app create a post only on the Pro and Enterprise plans. On another plan every tool works except beehiiv-api.create_post_draft, which beehiiv refuses.
Nothing else to create: there is no key to copy and no setting to change in beehiiv first.

Steps

Open Plugins from the sidebar, find beehiiv (the connector, not the MCP server tile) and press Add.
On the plugin's page, press Authenticate next to the account. You are sent to beehiiv: sign in, check the list of access it asks for (the read scopes), and allow it. beehiiv sends you back and the account shows Connected. To let bots make changes too, press Allow sending on the same account and allow the write scopes at beehiiv.
Press Choose bots on the account and tick the bots that may use it.
Ask the bot. Reads answer straight away; every change shows an approval card first.

A worked example

You ask: "Draft this week's issue of The Example Letter from my notes, and add ada@example.com as a subscriber tagged 'workshop'."

The bot calls beehiiv-api.list_publications to find the publication's id.
It calls beehiiv-api.create_post_draft. An approval card names the post's title; you approve, and beehiiv answers with the new draft's id and a preview link. The post is a draft.
It calls beehiiv-api.add_subscriber. The card names the e-mail address and says the action may send mail outside your organisation, because beehiiv can e-mail a new subscriber its opt-in confirmation. You approve.
It calls beehiiv-api.add_subscription_tags with workshop, after a card naming the subscriber.

What a bot can do with it

Read — beehiiv tells a bot things, nothing changes

Tool	What it does
`beehiiv-api.identify_workspace`	Name the beehiiv workspace this connection belongs to.
`beehiiv-api.list_publications`	List the publications (newsletters) this connection can reach.
`beehiiv-api.list_posts`	List a publication's posts, optionally only drafts, published or archived ones.
`beehiiv-api.get_post`	Read one post: its title, status, dates and, on request, its web content.
`beehiiv-api.list_subscriptions`	List a publication's subscribers, optionally by status, a page at a time.
`beehiiv-api.get_subscription`	Look up one subscriber by email address, with their tags and custom fields.
`beehiiv-api.list_segments`	List a publication's segments and how many subscribers each holds.

Write — beehiiv lets a bot change things

Tool	What it does
`beehiiv-api.create_post_draft`	Create a draft post from a title and HTML body. It is never published or scheduled.
`beehiiv-api.add_subscriber`	Add a subscriber to a publication; beehiiv may email them its opt-in confirmation.
`beehiiv-api.update_subscription`	Set or clear a subscriber's custom field values.
`beehiiv-api.add_subscription_tags`	Add tags to a subscriber, creating any tag the publication does not have yet.
`beehiiv-api.unsubscribe`	Unsubscribe a subscriber from the publication.

Adding a subscriber never re-subscribes someone who unsubscribed and never sends beehiiv's welcome e-mail. There is no tool that deletes a subscriber or a post.

The permissions it asks for, in plain words

Every call a bot makes through this connector is tagged with what kind of thing it is. Only the tags below ever apply here.

read — Looks something up. Nothing changes, and nothing is sent anywhere. A bot never has to ask first for this.
write — Changes something inside the connected account — creates, edits or files something. Asks you first, unless you have told Botseon to always allow that exact action.
external_send — Sends something to someone outside your organisation. Here: adding a subscriber, because beehiiv may e-mail that person. Always asks you first while a conversation carries outside content.
delete — Removes or cancels something a person will notice. Here: unsubscribing someone. Always asks you first; it can never be set to always allow.

The access you allow at beehiiv's consent screen, and why each is needed:

beehiiv scope	Asked for when	Why
`identify:read`	always	to show which workspace is connected
`publications:read`	always	to list your publications
`posts:read`	always	to list and read posts
`subscriptions:read`	always	to list subscribers and look one up
`segments:read`	always	to list segments
`posts:write`	you allow changes	to create a draft post
`subscriptions:write`	you allow changes	to add, tag, update and unsubscribe subscribers

What can go wrong

What you see	What it means	What to do
Reconnect needed (the account shows Needs auth)	beehiiv no longer accepts the connection: it was revoked at beehiiv, or the sign-in expired and could not be renewed	press Authenticate again
"this connection is not authorised for that action"	the account was connected for reading only	press Allow sending on the account
"beehiiv refused the request …"	beehiiv said no: most often creating a post on a plan below Pro, or a publication your beehiiv account cannot reach	check the plan and your access in beehiiv; the connection itself is fine
"beehiiv is rate-limiting this connection"	beehiiv allows 30 requests a minute on the free plan, 180 on Lite, 500 on Pro and 800 on Enterprise, per connection	the bot waits for the minute to reset and tries again
"beehiiv could not find that resource"	the publication, post or subscriber does not exist, or this connection cannot see it	check the id or e-mail
"beehiiv could not finish creating that post"	beehiiv built the draft in the background and that failed	ask the bot to create it again
"beehiiv reported a server error"	a problem on beehiiv's side	try again later

A post a bot has just drafted can show as pending for a few seconds while beehiiv builds it.

Limits

Read your publications, posts, subscribers and segments, draft a post, and add, tag or unsubscribe a subscriber. Nothing outside that list is possible through this connector, however a bot is asked to use it: it cannot publish, schedule or send a post, delete anything, change billing, or touch automations, webhooks or tiers.

Each list call reads one page of at most 100 rows. Publications, posts and segments page by number, up to page 100; subscribers page with the next-page marker beehiiv returns. A subscriber can carry up to 20 new tags per call, and a publication up to 100 tags in all.

Disconnecting

In Botseon

Open Plugins from the sidebar, press this connector's card to open its detail page, and under Accounts press Remove next to the account, or Uninstall to remove the plugin and every account connected to it at once. Either one revokes the stored connection immediately: nothing more is read or changed through it from that moment on. Install a plugin walks through the same screen step by step.

At beehiiv

Removing the account in Botseon also asks beehiiv to revoke the token (beehiiv's revoke endpoint), when your deployment's beehiiv app is configured with its revoke URL. To be sure the access is gone, or to revoke it without Botseon, sign in to beehiiv and remove your organisation's app from the workspace's connected or authorised apps in Settings. If you ever gave a bot a beehiiv API key some other way, delete that key under Settings → Workspace Settings → API.

What Botseon keeps, and how your data is used

Whatever a bot reads or writes through this connector becomes part of your conversations and the record of that run — the same records, and the same retention schedule, as everything else a bot works on. That includes subscribers' e-mail addresses when a bot reads them. Botseon is the processor for that content; your organisation decides what it may read and remember, and can delete it sooner than the schedule would on its own.

Your data is sent to a model provider only to produce the bot's answer, and for nothing else — it is not used to train any model. The Privacy Policy's Models and How long we keep it sections have the full detail, including exactly how long each kind of record is kept for.