A beehiiv MCP for the whole subscriber list, not just the post
Connect one beehiiv API key and 48 nodes land on the canvas: publications, posts with aggregate stats and preview URLs, subscriptions by id or by email with asynchronous bulk create and update, segments with recalculation and both member views, custom fields, newsletter lists and their memberships, tier reads, and engagement as a real time series. An AI agent can look up a subscriber, enrol them on the right newsletter list, and report how last week's sends performed, without anyone opening the beehiiv dashboard.
What the beehiiv MCP connector does
The beehiiv connector for Mattering Automations is 48 nodes: 25 read nodes and 23 action nodes, built against beehiiv's live OpenAPI specification. It covers publications, the post surface with aggregate stats, preview URLs, templates and test sends, subscriptions addressed by id or by email with tags and an asynchronous bulk surface that reports per row failures, segments including manual and dynamic creation with on demand recalculation, custom fields, newsletter lists and their membership records, tier reads, and windowed publication engagement statistics. One API key authenticates all of it, sent as a bearer token.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP capable assistant can use them, alongside Matter, the AI assistant built into the platform. An agent can find someone with beehiiv: Get Subscription By Email, put them on the right list with beehiiv: Subscribe To Newsletter List, and summarise a week of opens and clicks from beehiiv: Get Publication Engagements, all without touching the two nodes that can publish.
One structural decision shapes the whole connector and is worth explaining rather than hiding. A beehiiv API key is scoped to a WORKSPACE, and beehiiv documents its publication list endpoint as returning all publications associated with your API key, plural. A workspace routinely holds several publications: an operator running two titles from one account is the ordinary case, and a consultant's key can legitimately see publications belonging to different organizations. So the publication is not part of the credential. You connect one credential, and all 47 publication scoped nodes carry a publication field that is a picker sourced from beehiiv: List Publications, showing each publication by name with its owning organization underneath. Choose the publication by name once, and every id picker underneath it, posts, segments, custom fields, newsletter lists and tiers, narrows to that publication automatically.
Plan gating is stated rather than implied, because a widely repeated belief about it is out of date. The API is available on beehiiv's free Launch plan, which lists API access excluding the Send API. The Send API is the carve out: beehiiv's own API reference states that updating a post is available to publications on the Max and Enterprise plans, while the create-post endpoint is documented as in beta and available only to Enterprise users, and beehiiv's support article says Max and Enterprise for both, so its own documentation disagrees with itself here, and in this connector those two endpoints are beehiiv: Create Post and beehiiv: Update Post. Everything else here, every read plus the subscriber, segment, custom field, newsletter list and tag writes, runs on the free plan. Do not plan a publishing workflow on a Launch account, and do not assume the API needs a paid plan at all.
One connection, three surfaces
- Visual automations. Drag beehiiv nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every beehiiv node, ready to drop on the canvas
48 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 25
beehiiv: Get Aggregate Post Stats
Get one combined stats block across every post matching the filters: email recipients, delivered, opens, unique opens, open rate, clicks, unique clicks, verified clicks, click rate, unsubscribes and spam reports, plus web views and clicks, a per-URL click breakdown, and free-to-premium upgrades. These are totals over the matched posts rather than a time series: the endpoint takes no date range, so the numbers cannot be partitioned by day and the two rates are already computed across the whole set. For a per-period series use beehiiv: Get Publication Engagements.
beehiiv: Get Bulk Subscription Update
Get one bulk subscription update job. This is the polling node for the two asynchronous bulk writes: loop on it until data.data.status is complete or failed, then read data.data.error_log for the individual rows that did not apply. A job can report complete while individual rows failed, so check the error log rather than the status alone.
beehiiv: Get Custom Field
Get one custom field definition: its kind, display name, creation time and, for a list field, its allowed options. Use it to confirm a field's kind before writing a value, since beehiiv rejects a value that does not match.
beehiiv: Get Newsletter List
Get one newsletter list with its name, slug, description, status, auto-subscribe flag, active subscriber count and timestamps.
beehiiv: Get Newsletter List Subscription
Get one newsletter list membership record by its own id, with the membership status and the subscribed and unsubscribed timestamps. Useful for confirming an enrolment took effect. When only the subscriber is known rather than the membership id, list the memberships and match on subscription_id.
beehiiv: Get Post
Get one post with its metadata, recipient targeting and, on request, its stats and rendered HTML. This is also the polling node for asynchronous post creation: a post created through the Send API is built in the background, so this can answer HTTP 202 with a processing body while it is still being built (wait and retry, honouring Retry-After), or HTTP 404 with error code POST_CREATION_FAILED, which means the post will never appear and the create call must be fixed and repeated.
beehiiv: Get Post Preview URL
Generate a URL that renders a post as a chosen audience would see it. Sends nothing to anyone, which makes it the safe way to eyeball a post before it goes out. The returned preview_url opens the post inside the beehiiv app and needs a logged-in beehiiv session with access to the publication; it is not an HTML-returning endpoint and not a public link.
beehiiv: Get Publication
Get one publication with its name, owning organization, referral-program flag and creation time. Ask for the stats expansion to add LIFETIME-TO-DATE counters: active subscriptions split free and premium, total sent, total unique opened, total clicked, and the historical average open and click rates. Those are running totals for the whole publication rather than a period, so they must never be added together across snapshots. For a real time series use beehiiv: Get Publication Engagements.
beehiiv: Get Publication Engagements
Get email engagement as a TIME SERIES: one row per period with total opens, unique opens, total clicks, unique clicks and the bot-filtered verified click counts. This is the only endpoint in this catalog that takes a date range, so it is the one to chart; every other stats surface here returns lifetime or per-post totals. The window is a start date plus a day COUNT rather than a start and an end, capped at 31 days per request, and defaults to yesterday alone. All dates and times are UTC. Two arithmetic rules, both declared machine-readably on this node: the total_ counters are additive across periods, and the unique_ counters are NOT - unique subscribers over two weeks is not the sum of two weekly figures. Nothing here is a rate, so there is no rate to average incorrectly.
beehiiv: Get Segment
Get one segment with its type, calculation status, member count, last calculation time and active flag. Use it to wait on a freshly created dynamic segment, which comes back pending and only lists members once its status reaches completed. A dynamic segment that has gone unused for a while is marked inactive and stops being recalculated automatically.
beehiiv: Get Subscription
Get one subscription by its prefixed sub_ id, with status, tier, acquisition attribution and referral code. Expansions add per-subscriber stats (emails received, open rate, click-through rate), custom field values, tags, referrals and premium tier membership.
beehiiv: Get Subscription By Email
Get one subscription by email address rather than by id. This is the node for the common shape where the address arrives from a form, a CRM or an upstream node and no beehiiv id is in hand. beehiiv requires the address to be URL encoded in the path and the runner does that for you. Matching is exact and case insensitive.
beehiiv: Get Tier
Get one premium tier with its name, status and description, and on request its active subscription count and its prices with currency, amount in cents, billing interval and features. A tier's status reflects whether it has any active prices, so an archived tier is one nobody can currently buy.
beehiiv: List Bulk Subscription Updates
List the publication's bulk subscription update jobs with each job's type, status, parameters, timestamps, failure reason and per-row error log. Use it to audit what a workflow has been doing to a list, or to find a job whose id was lost. The endpoint takes no pagination parameters at all.
beehiiv: List Custom Fields
List every custom field defined on a publication, with each field's id, kind and display name, plus the allowed options when the kind is list. The DISPLAY name is the handle used when setting a value on a subscription or filtering a dynamic segment, so run this first whenever a workflow writes custom fields. This endpoint takes no parameters at all, not even pagination.
beehiiv: List Newsletter List Subscriptions
List who is on a newsletter list, as membership records carrying the newsletter list id, the subscription id, the membership status and the subscribed and unsubscribed timestamps. Note these rows carry NO email address: join data.data[].subscription_id back through beehiiv: Get Subscription when a human-readable list is needed. Prefer cursor pagination here; offset paging is deprecated.
beehiiv: List Newsletter Lists
List a publication's newsletter lists with name, slug, description, status, active subscriber count and whether new subscribers join automatically. Newsletter lists are how one publication runs several distinct sends without splitting into separate publications; the ids returned here target a post at one list on beehiiv: Create Post.
beehiiv: List Post Templates
List the post templates available to a publication, each with its id and name. Those ids feed the post_template_id field on beehiiv: Create Post, which is how a workflow builds a post that already matches the publication's house layout.
beehiiv: List Posts
List a publication's posts with title, subject line, slug, status, publish date, audience and platform. Filter by status (draft, confirmed, archived), audience, platform, content tags, slugs, author names or premium tiers. Ask for the stats expansion to include per-post open, click, unsubscribe and spam counters, and the content expansions to include rendered HTML; those return whole documents per post, so request them only when the workflow reads them.
beehiiv: List Publications
List every publication the API key can reach, with each publication's id, name, owning organization and optional lifetime stats. This is the node every other beehiiv node leans on: a key is scoped to a WORKSPACE rather than to one publication, so the pub_ id this returns is what fills the publication picker everywhere else. It is also the cheapest way to confirm a credential works, because it needs no configuration at all.
beehiiv: List Segment Subscriber IDs
List a segment's members as a bare array of subscription ids, with no subscriber detail. This is the cheap half of the segment membership pair and the one to loop over: the ids drop straight into beehiiv: Bulk Update Subscription Status or beehiiv: Bulk Update Subscriptions. Note the rows here are STRINGS rather than objects, so the path is data.data[] with no field after it.
beehiiv: List Segment Subscribers
List a segment's members as full subscription objects: email, status, tier, acquisition attribution and, on request, stats, custom field values, tags, referrals and premium tier membership. Use this when the workflow needs subscriber DETAIL. When it only needs ids - to count them, or to feed a bulk update - use beehiiv: List Segment Subscriber IDs instead, which returns the same membership in a far lighter payload.
beehiiv: List Segments
List a publication's segments with name, type, calculation status, last calculation time and member count. Ask for the stats expansion to add the segment's aggregate open rate, clickthrough rate, delivered and sent totals, referral counts and premium share. Note when those stats were computed: beehiiv recalculates dynamic segment stats once a day around 07:00 UTC, and manual and static segments only compute once at creation, so a fresh number needs beehiiv: Recalculate Segment first.
beehiiv: List Subscriptions
List a publication's subscriptions with email, status, tier, acquisition attribution (utm source, medium, channel, campaign, term, content, referring site) and referral code. Filter by status, free or premium tier, specific premium tiers, an exact email address, or a single creation date. Expansions add per-subscriber stats, custom field values, tags, referrals and newsletter list membership. This is the lister behind the subscription picker on every other node. Prefer cursor pagination: offset paging is deprecated and blocked past page 100.
beehiiv: List Tiers
List a publication's premium tiers with name, status and description, plus optional active-subscription counts and price details (currency, amount in cents, billing interval and feature list). The tier ids returned here are what the subscription and post nodes want wherever premium targeting is involved, which is why this lister ships even though tier writes were left out of this wave.
Action nodes 23
beehiiv: Add Subscription Tags
Add one or more tags to a subscription, for grouping subscribers without building a segment. A tag that does not yet exist on the publication is created automatically, which means a typo silently creates a new tag rather than erroring. beehiiv caps a publication at 100 unique tags. The API offers no tag lister and no tag removal endpoint, so tags are free text here and removing one is a dashboard job (see the coverage notes at the foot of this file).
beehiiv: Bulk Create Subscriptions
Create many subscriptions in one request instead of one call per address, which is what keeps an import inside beehiiv's 180-requests-per-minute organization limit. ASYNCHRONOUS: the response is an acknowledgement carrying an import_id, not a result, and none of the subscribers exist yet when it returns. Each element takes the same fields as beehiiv: Create Subscription, so the same warning applies at scale - send_welcome_email and automation_ids reach real inboxes and cannot be recalled.
beehiiv: Bulk Update Subscription Status
Set the same status on many subscriptions at once - the narrow, cheap sibling of Bulk Update Subscriptions for the one case that is only ever a status change. ASYNCHRONOUS in the same way: poll beehiiv: Get Bulk Subscription Update with the returned job id. Reversible, because a status can be set back, but it moves every id in the list at once, so check the list is what you meant before running it.
beehiiv: Bulk Update Subscriptions
Update many subscriptions in one request, each with its own changes: tier, Stripe customer, custom field values (including deleting a value), complimentary access, or unsubscribe. Maximum 1000 rows per call. ASYNCHRONOUS: the response carries a data.subscription_update_id for a job that has not run yet, so poll beehiiv: Get Bulk Subscription Update until its status is complete or failed and read its error_log for the rows that did not apply.
beehiiv: Create Custom Field
Define a new custom field on a publication so subscriptions can carry that attribute. Choose the kind carefully: it decides which values beehiiv accepts and which filter operators a dynamic segment can use against the field, and the update endpoint can only change the display name, so a wrong kind means deleting and recreating.
beehiiv: Create Newsletter List
Create a newsletter list on a publication. It is created active, and its slug is generated from the name when not supplied. Think about auto_subscribe before setting it: with it on, every NEW subscriber to the publication joins this list and will receive anything sent to it.
beehiiv: Create Post
Create a post. DESTRUCTIVE because this is how beehiiv SENDS: a post created with status confirmed and no scheduled_at publishes immediately, which dispatches real email to real subscribers and cannot be recalled or unsent. beehiiv ships no separate send endpoint to gate separately, so the status field on this one node is the trigger; keep it at draft while building and confirm or schedule only when the content is final. This is a Send API endpoint: beehiiv documents it as available to publications on the Max and Enterprise plans, so it returns a plan error on Launch and Scale. Creation is asynchronous, so the response carries the post's stable id while the post is still being built; poll beehiiv: Get Post before assuming it exists. Provide content as EITHER blocks OR body_content, never both.
beehiiv: Create Segment
Create a segment, either manual or dynamic depending on the input shape. A manual segment from explicit subscription ids or email addresses is processed synchronously and comes back completed; note beehiiv IGNORES email addresses that are not already subscribers rather than creating them, so add them first with beehiiv: Create Subscription. A dynamic segment filtered on custom field values is processed in the background and comes back pending, so poll beehiiv: Get Segment before listing its members. Reversible: a segment can be deleted without touching the subscribers in it.
beehiiv: Create Subscription
Subscribe an email address to a publication, optionally setting acquisition attribution, custom field values, premium tiers, newsletter list membership and automation enrolment in the same call. Reversible: an unwanted subscription can be unsubscribed or deleted afterwards. Two fields DO reach a real inbox and cannot be recalled once sent, so set them deliberately: send_welcome_email sends the publication's welcome email, and automation_ids enrols the new subscriber into automations that may email them immediately (each automation needs an active Add by API trigger). reactivate_existing revives someone who previously unsubscribed and should only be used when they knowingly resubscribed.
beehiiv: Delete Custom Field
Delete a custom field from a publication. DESTRUCTIVE: this removes the field definition AND the value every subscription had stored in it, across the whole list, with no undo and no export step. Any dynamic segment filtering on the field loses its filter, and re-creating a field with the same name brings back an empty column, not the old data. Export first if the values matter.
beehiiv: Delete Newsletter List
Delete a newsletter list. DESTRUCTIVE: the list and the membership records attached to it go with no undo, so who had opted in to this particular list is not recoverable and recreating a list with the same name starts it empty. Subscribers keep their publication-level subscription. When the goal is simply to stop using a list, archive it with beehiiv: Update Newsletter List instead, which is reversible. Any post still targeting this list loses its audience.
beehiiv: Delete Post
Delete or archive a post. DESTRUCTIVE and asymmetric, in beehiiv's own words: a post still in draft is PERMANENTLY DELETED with no undo and no trash, while a confirmed post is archived instead and its status becomes archived. Deleting cannot unsend anything that has already gone out. The post picker groups by status, so check which case you are in before running this.
beehiiv: Delete Segment
Delete a segment. DESTRUCTIVE because there is no undo and no trash: the segment definition, and for a manual segment the membership list that was uploaded into it, are gone and must be rebuilt by hand. The blast radius stops there, though - beehiiv states plainly that deleting a segment does not affect the subscriptions in it, so nobody is unsubscribed or removed. Check nothing schedules a post against this segment before running it.
beehiiv: Delete Subscription
Permanently delete a subscription. DESTRUCTIVE and irreversible in beehiiv's own words: this cannot be undone and ALL data associated with the subscription is deleted with it, including its history, custom field values and referral credit. Deleting a premium subscription also stops billing it. beehiiv itself recommends unsubscribing instead wherever possible, which beehiiv: Update Subscription does with the unsubscribe flag while keeping the record. Use this node for genuine erasure requests, not for list hygiene.
beehiiv: Recalculate Segment
Ask beehiiv to recalculate a segment now rather than waiting for its schedule. This is the node to run before reading members or stats when freshness matters, because dynamic segment stats otherwise refresh only once a day around 07:00 UTC. Recalculation is asynchronous: the response is an acknowledgement, so poll beehiiv: Get Segment until its status returns to completed. Harmless to repeat, and it changes no subscriber.
beehiiv: Send Post Test Email
Send a test copy of a post to one or more named email addresses. DESTRUCTIVE by the fleet's classing rather than beehiiv's: the addresses belong to real people, the mail leaves immediately, and nothing can recall it. The blast radius is far smaller than publishing, but the property that decides the flag is the same one Mollie and Razorpay are classed on: a run reaches a human with no second approval. The response reports how many test sends the publication has left today and when that limit resets; exceeding it returns HTTP 422. To LOOK at a post without sending anything, use beehiiv: Get Post Preview URL instead.
beehiiv: Subscribe To Newsletter List
Enrol an EXISTING subscription onto a newsletter list, identified either by subscription id or by email address. This does not create anybody: an address that is not already a subscriber will not be added, so create the subscription first, or pass newsletter_list_ids on beehiiv: Create Subscription to do both in one call. Reversible with beehiiv: Unsubscribe From Newsletter List.
beehiiv: Unsubscribe From Newsletter List
Take a subscriber off ONE newsletter list while leaving their publication subscription intact - the granular preference change, not an unsubscribe from everything. Addressed by SUBSCRIPTION id, which is the id a workflow actually holds, rather than by the membership record's own id. Reversible with beehiiv: Subscribe To Newsletter List. beehiiv documents unsubscribing as the only update this endpoint currently supports.
beehiiv: Update Custom Field
Rename a custom field. The display name is the only thing this endpoint changes - the kind is fixed at creation and the stored values are untouched. Renaming is reversible, but it is not free: anything referring to the field by display name, including dynamic segment filters and workflows that write values, must be updated to match.
beehiiv: Update Newsletter List
Update a newsletter list's name, description, slug, auto-subscribe behaviour or status. Only the fields supplied change. Setting status to archived is the reversible way to retire a list: it stops being used while its membership survives, which is what beehiiv: Delete Newsletter List does not offer. Changing the slug breaks any link already published against the old one.
beehiiv: Update Post
Update a post. DESTRUCTIVE for the same reason Create Post is: moving status from draft to confirmed publishes the post, which dispatches real email to real subscribers and cannot be recalled. Only the fields supplied are changed, and omitting both blocks and body_content preserves the existing content. scheduled_at cannot be changed once the post has already been sent. This is a Send API endpoint: beehiiv documents it as available to publications on the Max and Enterprise plans.
beehiiv: Update Subscription
Update one subscription by id: change the email address, move it between free and premium tiers, set custom field values, attach a Stripe customer, or unsubscribe it. Reversible, and this is the node to prefer over Delete Subscription: setting unsubscribe true stops the mail while keeping the record, its history and its custom fields, so it can be reversed later. Only the fields supplied are changed.
beehiiv: Update Subscription By Email
Update one subscription addressed by email rather than by id, for the common shape where the address arrives from a form or a CRM and no beehiiv id is in hand. Same effects as beehiiv: Update Subscription, including unsubscribe as the reversible alternative to deletion. Note the two email fields do different jobs: the address in the path selects the subscription, and new_email replaces it.
Connecting beehiiv takes one credential
beehiiv authenticates every request with a single API key sent as an Authorization bearer header. Keys are created inside the beehiiv app under the workspace's API settings, and a key belongs to that workspace rather than to one publication, which is why this connector never asks for a publication id on the credential. There is nothing else to supply: no region, no account subdomain, no second field. Two things to check before you design a workflow around the whole catalog. First, plan gating: the API is available on the free Launch plan, which lists API access excluding the Send API, while creating and updating a post is documented by beehiiv as available to publications on the Max and Enterprise plans, so beehiiv: Create Post and beehiiv: Update Post are the two nodes a Launch or Scale account cannot run. Second, volume: beehiiv documents a limit of 180 requests per minute per organization, not per key and not per publication, and returns HTTP 429 with rate limit headers when you exceed it, so a fan out loop over a large subscriber list is the realistic way to hit it. Prefer the bulk nodes.
Sign in to beehiiv, open the workspace's API settings, and create an API key. Copy the value.
In Mattering Automations, open Connectors, click Add Connector, choose beehiiv, and create a credential with that key.
Click Test Connection. Mattering calls beehiiv's publications endpoint, which takes no path parameters and no required query parameters at all: a list, even a short one, proves the key, and a 401 comes back with beehiiv's structured error envelope.
All 48 beehiiv nodes appear in the canvas palette. Run beehiiv: List Publications first. It is the node every other node depends on: its ids fill the publication picker, and choosing a publication there is what narrows every picker underneath it.
Common uses for the beehiiv MCP
Grow the list from wherever a signup actually happens
beehiiv: Create Subscription subscribes an email address to a publication and can set acquisition attribution, custom field values, premium tiers, newsletter list membership and automation enrolment in the same call, which is how a form, a CRM record or an agent's decision becomes a real subscriber. Two of its fields reach a real inbox and the node says so plainly: the welcome email flag, which this connector defaults to off rather than relying on your beehiiv setting, and automation enrolment, which can email immediately. beehiiv: Bulk Create Subscriptions is the node for an import, because one request instead of one call per address is what keeps a load inside beehiiv's per organization request limit.
Segment and tag without leaving the workflow
beehiiv: Create Segment builds either a manual segment from explicit ids or addresses, or a dynamic one from a filter, and beehiiv: Recalculate Segment refreshes it on demand rather than waiting for its schedule, which matters because dynamic segments recalculate on beehiiv's timetable rather than yours. beehiiv: List Segment Subscriber IDs is the cheap half of the membership pair and the one to loop over; beehiiv: List Segment Subscribers returns the full subscriber objects when you actually need the detail. beehiiv: Add Subscription Tags groups subscribers without building a segment at all. One thing to build carefully around: a tag that does not exist yet is created by writing it, so a typo silently makes a new tag rather than failing.
Report on sends as a time series, not a lifetime blob
beehiiv: Get Publication Engagements is the one genuinely windowed read here: one row per period with total opens, unique opens, total clicks, unique clicks and the bot filtered verified click counts, over a start date and a number of days, at day, week or month granularity. beehiiv: Get Aggregate Post Stats gives one combined block across every post matching a filter, and beehiiv: Get Post adds per post stats on request. A scheduled workflow can write the series into a Mattering database and open a task only when a number moves further than it should have. One caution when you store it: the total counts add up across periods, but the unique counts do not, because the same reader opening on two days is one unique open per day and one, not two, across the pair.
Keep beehiiv and your CRM saying the same thing
beehiiv: Get Subscription By Email is the node for the common shape where an address arrives from a form, a CRM or an upstream step and no beehiiv id is in hand. beehiiv: Update Subscription By Email writes back the same way, so a workflow can change an address, move someone between free and premium tiers, set custom field values, or unsubscribe them, without ever holding a beehiiv id. beehiiv: List Custom Fields is worth running first when you write values, because custom fields are addressed by their DISPLAY name when writing on a subscription while the field CRUD nodes address them by id, and renaming a field silently breaks anything that referenced the old name.
Assemble a post and stop before it sends
beehiiv: List Post Templates and beehiiv: Get Post Preview URL are the safe half of the post surface: the preview generates a URL rendering the post as a chosen audience would see it, and sends nothing to anyone, which makes it the right way to eyeball a draft from a workflow. beehiiv: List Posts and beehiiv: Get Post read what exists, filtered by status, audience or platform. The line to draw is at beehiiv: Create Post and beehiiv: Update Post, because beehiiv has no separate send endpoint at all: sending is a side effect of the status field, so a post created or moved to confirmed with no schedule publishes immediately and dispatches real email that cannot be recalled. Both are flagged destructive, both need beehiiv's Max or Enterprise plan, and beehiiv: Create Post defaults its status to draft here on purpose.
Run an import that tells you which rows failed
The bulk nodes are asynchronous, and treating them as synchronous is the trap. beehiiv: Bulk Create Subscriptions returns an import id and beehiiv: Bulk Update Subscriptions and beehiiv: Bulk Update Subscription Status return a job id, none of them finished at the moment they answer. beehiiv: Get Bulk Subscription Update is the polling node: loop on it until the status reads complete or failed. Then read the per row error log rather than the status alone, because a job can report complete while individual rows failed, and the log is the only place that says which. beehiiv: List Bulk Subscription Updates keeps an audit trail of what a workflow has been doing to the list.
Example: A weekly newsletter report that files its own follow up
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a weekly schedule fires.
beehiiv: List Publications runs once so the rest of the workflow is scoped to the right publication by name rather than by a pasted id.
beehiiv: Get Publication Engagements pulls the last seven days as a time series, with the granularity set to day. beehiiv caps the window at 31 days and rejects a longer request rather than truncating it, so keep the span inside that.
beehiiv: Get Aggregate Post Stats reads the combined figures for the posts that went out in the same window, which is the denominator the engagement series should be read against.
beehiiv: List Segments with the stats expansion reports how each audience slice is behaving. Run beehiiv: Recalculate Segment first for any dynamic segment where freshness matters, since dynamic segments recalculate on beehiiv's own schedule rather than at read time.
The rows land in a Mattering database next to last week's, and a task opens for a person only when a number moves outside its usual band. Nothing in this workflow can publish, because it never touches beehiiv: Create Post or beehiiv: Update Post.
beehiiv MCP questions, answered
What beehiiv operations are supported?
48 nodes: 25 read nodes and 23 action nodes. Publications, both list and get. Posts, with list, get, create, update, delete, aggregate stats, preview URL, test send and the template lister. Subscriptions, with list, get by id, get by email, create, update by id, update by email, delete, add tags, bulk create, bulk update, bulk status update and the two job polling reads. Segments, with list, get, create, delete, recalculate and both member views. Custom fields, newsletter lists and their memberships, and tier reads. Plus the one windowed engagement statistics endpoint. That is a deliberately scoped core of beehiiv's roughly 95 documented operations rather than the whole API: automations and journeys, webhook endpoint management, tier writes, polls, podcasts, the ad network, authors, complimentary access, condition sets, data deletion requests and the referral program are not built here yet.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively.
beehiiv publishes its own MCP server. Why use this connector?
It does, and it is worth knowing what each one is for. beehiiv runs an MCP server on its developer documentation site and points AI clients such as Claude Code and Cursor at it, which makes it a good companion when you are writing code against the beehiiv API and want the reference in your editor. This connector is the operations side instead: 48 nodes that run as steps on an automation canvas, on a schedule or from a trigger with nobody present, chained with every other connector in one workflow, with the credential held once in a shared workspace rather than in each person's local client config, and with the destructive nodes flagged so you can gate them. If your job is to write beehiiv code, use beehiiv's server. If your job is to keep a list in sync, report on sends, or let an agent act on subscribers, that is what this is.
Is the beehiiv API only available on a paid plan?
No, and this is the belief most worth correcting. The API is available on beehiiv's free Launch plan, which lists API access excluding the Send API. The Send API is the carve out: beehiiv's own API reference states that updating a post is available to publications on the Max and Enterprise plans, while the create-post endpoint is documented as in beta and available only to Enterprise users, and beehiiv's support article says Max and Enterprise for both, so its own documentation disagrees with itself here, and in this connector those two endpoints are beehiiv: Create Post and beehiiv: Update Post. Everything else, every read plus the subscriber, segment, custom field, newsletter list and tag writes, runs on Launch. What you should not do is design a publishing workflow and discover the gate at run time: check your plan before you build around those two nodes. Plan contents move, so confirm the current split on beehiiv's own pricing page.
Can an AI agent publish a post to my whole list by accident?
The publishing nodes are flagged destructive so you can gate them, and the mechanism is worth understanding because it is unusual. beehiiv has no separate send endpoint: sending is a side effect of the status field on a post, so beehiiv: Create Post with a confirmed status and no schedule publishes immediately, and beehiiv: Update Post moving a draft to confirmed does the same thing from the other direction. Real email goes to real subscribers and cannot be recalled. beehiiv: Create Post defaults its status to draft here on purpose. beehiiv: Send Post Test Email is flagged too, because a test still reaches named human inboxes. Keep agents on the read nodes, the subscriber nodes and the preview URL, and put anything that can publish behind an approval task.
Do I need a separate credential for each publication?
No. One credential per beehiiv workspace. A beehiiv API key is scoped to a workspace and beehiiv documents its publication list endpoint as returning all publications associated with that key, so the key selects the workspace and the publication is chosen per node instead. All 47 publication scoped nodes carry a publication picker sourced from beehiiv: List Publications, showing each one by name with its owning organization underneath, which matters when a key can see publications belonging to different organizations or when two clients both run a newsletter with the same name. That arrangement is also what makes for each publication, do this workflow buildable at all, since a workflow can template a node field but cannot switch credentials at run time.
What are beehiiv's rate limits?
beehiiv documents 180 requests per minute, counted per organization rather than per key or per publication. Exceeding it returns HTTP 429, and every response carries headers reporting the limit, what remains, and when the window resets. This connector does not retry or back off on your behalf: a 429 surfaces as a plain unsuccessful step so the workflow decides what to do. In practice the realistic way to hit the ceiling is a loop that fans out one call per subscriber, so prefer beehiiv: Bulk Create Subscriptions and beehiiv: Bulk Update Subscriptions for anything list sized. Rate limits get retuned quietly, so check beehiiv's own rate limiting guide if you are designing close to the line.
Why did a post I just created come back as not found?
Because post creation is asynchronous. beehiiv returns immediately with the post's stable id while the post is still being built in the background, so a get straight afterwards can answer 202, meaning it is still being created and you should honour the retry hint, or 404 with a creation failed code, meaning it will never appear and the request needs fixing before you try again. 202 is a success status, so a workflow that must wait should poll beehiiv: Get Post rather than chaining the next step directly onto the create. The bulk writes behave the same way, with beehiiv: Get Bulk Subscription Update as their poller, and a freshly created dynamic segment is a milder version of the same thing: it comes back pending and its members are listable only once processing finishes.
Why is there no delete node for tags?
Because beehiiv's API has none, and there is no tag lister either. Tags exist only by being written: beehiiv: Add Subscription Tags creates a tag on the publication implicitly the first time it is used, so a typo silently becomes a new tag and counts against beehiiv's cap of 100 unique tags per publication. Existing tags are readable only per subscriber, through the tags expansion on a subscription read. If you want a vocabulary you can enumerate and manage, segments and newsletter lists are the surfaces with real CRUD behind them, and both are fully built here.
Put beehiiv to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. beehiiv is a product of its respective owner; Mattering is an independent platform.