Mattering Automations beehiiv integration
Connect beehiiv to Mattering Automations: publications, posts with stats and previews, subscriptions by id or by email with asynchronous bulk jobs, segments, custom fields, newsletter lists, tier reads and windowed engagement statistics as workflow steps, authenticated with one workspace scoped API key.
The Mattering Automations beehiiv integration puts 48 beehiiv nodes on your automation canvas: read publications, list and read posts with aggregate statistics and preview URLs, create and update subscriptions addressed by id or by email, add tags, run asynchronous bulk creates and updates with job polling, build and recalculate segments and read their members two ways, manage custom fields, manage newsletter lists and their memberships, read premium tiers, and pull engagement as a real time series.
The credential is a single API key, created inside the beehiiv app under the workspace's API settings and sent as an Authorization bearer header on every request. There is nothing else to supply: no region, no account subdomain, no second field. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
One thing is different here from most integrations, and it is easier to understand up front than to hit later. A beehiiv API key is scoped to a WORKSPACE rather than to a publication, and beehiiv documents its publication list endpoint as returning all publications associated with your API key. A workspace routinely holds several publications, and a consultant's key can legitimately see publications across different organizations. So the publication is not a credential field. You connect one credential, and all 47 publication scoped nodes carry their own Publication field, which is a picker listing your publications BY NAME with the owning organization shown underneath. Choose the publication once on a node and every id picker beneath it, posts, segments, custom fields, newsletter lists and tiers, narrows to that publication automatically.
Before you start
- A beehiiv account with a workspace you can create an API key in. The key is created inside the beehiiv app under the workspace's API settings.
- At least one publication, or the intent to create one in the beehiiv dashboard. Publications are not creatable through this integration, so an empty workspace has nothing for the Publication picker to offer.
- A beehiiv plan that covers the nodes you intend to use, and this is the one plan check that matters here. 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 integration those two endpoints are beehiiv: Create Post and beehiiv: Update Post. Every other node here, including all 25 reads and the subscriber, segment, custom field, newsletter list and tag writes, runs on Launch. Confirm the current split on beehiiv's own pricing page before you build a publishing workflow, since plan contents move.
- A sense of your call volume. beehiiv documents a limit of 180 requests per minute counted per organization, not per key and not per publication, and answers HTTP 429 when you exceed it. A loop that fans out one call per subscriber is the realistic way to reach that, so prefer beehiiv: Bulk Create Subscriptions and beehiiv: Bulk Update Subscriptions for anything list sized.
- A Mattering workspace with access to the Automations app.
Create a beehiiv API key
Mattering authenticates to beehiiv with a single API key, sent as an Authorization bearer header on every request. The key belongs to a workspace rather than to a publication, so the first decision is which workspace this credential should reach: the key selects the workspace, and the publication picker then offers everything inside it. There are no scopes to compose and no host to choose.
Connect beehiiv to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a beehiiv section should list the read and action nodes. Drop beehiiv: List Publications onto the canvas and run a test step. It is the integration's natural probe: it needs no parameters, and it returns every publication the key can reach with its id, name and owning organization. It is also the node every other node depends on, so if this works, the config panels work.
Now try a scoped node, because that is where the publication field matters. Drop beehiiv: List Subscriptions onto the canvas and open its Publication field: the picker should list your publications BY NAME with the owning organization shown underneath. Choose one and run the step. Two shapes to notice while you are here. The pagination fields sit BESIDE the data rather than inside a wrapper, so a total is read as data.total_results and rows as data.data[]. And Limit defaults to 10 on every beehiiv lister, so an unraised limit truncates a real publication quietly. Everything in this verify path is read only, so it cannot reach the destructive nodes and is safe to re run whenever you rotate the key.
Node reference
48 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 25
beehiiv: Get Aggregate Post Stats
beehiiv_get_post_aggregate_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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
Using the integration
On the automation canvas
beehiiv nodes chain with every other node. A form submission can become a subscriber with beehiiv: Create Subscription, a weekly schedule can read beehiiv: Get Publication Engagements into a Mattering database and open a task when engagement drifts, and beehiiv: Get Subscription By Email can look someone up from an address that arrived in an upstream step with no beehiiv id attached. One value does most of the wiring: the publication, chosen once from beehiiv: List Publications, which every other picker in the connector hangs off.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. An agent can find a reader with beehiiv: Get Subscription By Email, enrol them with beehiiv: Subscribe To Newsletter List, group them with beehiiv: Add Subscription Tags, and report on sends from beehiiv: Get Publication Engagements. The reads plus the subscriber writes are the comfortable surface to hand an agent; keep the publishing nodes behind approval steps. beehiiv publishes an MCP server of its own, and it is worth knowing which is which before you choose. 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 integration is the operations side of the same platform: 48 nodes usable as canvas steps as well as over MCP, running on a schedule or from a trigger with nobody present, chaining 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.
One credential, a publication chosen per node
This is the wrinkle worth ten seconds of attention. The credential covers a whole beehiiv workspace, but each scoped node carries its own Publication field, because a workspace routinely holds several publications and a key addresses all of them. The field is a picker sourced from beehiiv: List Publications: it shows names and puts the owning organization on the second line, which is what tells two clients' newsletters apart when both are called something generic. Every dependent picker threads that choice through, so choosing a publication is what makes the post, segment, custom field, newsletter list and tier pickers populate with the right things. The alternative, putting the publication on the credential, was rejected for a practical reason: it would force one stored secret per publication holding the same token, and it would make a for each publication workflow unbuildable, since a workflow can template a node field but cannot switch credentials at run time.
Subscribers, by id or by address
Most real workflows have an email address and no beehiiv id, so the by email pair matters. beehiiv: Get Subscription By Email and beehiiv: Update Subscription By Email do everything their id based siblings do without a lookup step in front. beehiiv: Create Subscription can set acquisition attribution, custom field values, premium tiers, newsletter list membership and automation enrolment in one call. Two of its fields reach a real inbox even though the node is not flagged destructive, and both are called out in the node itself: the welcome email flag, which this integration defaults to off rather than relying on your beehiiv setting, and automation enrolment, which can email immediately. The reactivation flag deserves the same care, since it revives someone who previously unsubscribed and should only be used when they knowingly resubscribed. beehiiv: Delete Subscription is the destructive one: beehiiv's own guidance is to unsubscribe rather than delete, because deleting cannot be undone and takes all the data attached to the subscription with it.
Custom fields, and the naming trap inside them
beehiiv: Create Custom Field defines an attribute a subscription can carry, and the kind you choose decides which values beehiiv accepts and which filters work later, so it is worth getting right at creation: beehiiv: Update Custom Field renames a field and nothing more, because the kind is fixed once set. The trap is how fields are addressed. The field CRUD nodes take an id, and custom field ids are bare identifiers with none of the prefixes the rest of beehiiv's ids carry. But writing a VALUE on a subscription, and filtering a dynamic segment, both address the field by its DISPLAY name. That means renaming a field silently breaks anything that referenced the old name, with no error to tell you. Run beehiiv: List Custom Fields before writing values so the workflow uses names that currently exist. beehiiv: Delete Custom Field is destructive for a matching reason: it removes the definition and every subscription's stored value for it, list wide, with no export step, and recreating the field gives you an empty column.
Segments and newsletter lists, and when to use which
A segment is a computed slice; a newsletter list is a thing people opt in to. beehiiv: Create Segment builds either a manual segment from explicit ids or addresses, or a dynamic one from a filter, and beehiiv: Recalculate Segment is the node to run before reading members or stats when freshness matters, because dynamic segments recalculate on beehiiv's own schedule rather than at read time and a dynamic segment left unused for a while stops recalculating at all. Two behaviours to build around: a manual segment silently drops email addresses that are not already subscribers rather than creating them, so create the subscriptions first, and beehiiv: List Segment Subscriber IDs is the cheap membership read to loop over while beehiiv: List Segment Subscribers returns the full objects. Newsletter lists are the opt in side: beehiiv: Create Newsletter List, beehiiv: Subscribe To Newsletter List and beehiiv: Unsubscribe From Newsletter List manage granular preferences without touching someone's publication subscription. Think about the auto subscribe setting before you turn it on, since it decides whether new subscribers join automatically. Archiving a list through beehiiv: Update Newsletter List is the reversible alternative to beehiiv: Delete Newsletter List, which takes the membership records with it.
Posts, and the fact that there is no send node
This is the single most important thing to understand about beehiiv's API, and looking for a send node and not finding one is how people end up publishing by accident. beehiiv has no separate send endpoint: sending is a side effect of the status field on a post. beehiiv: Create Post with a confirmed status and no schedule publishes immediately and dispatches real email to real subscribers, and beehiiv: Update Post moving a draft to confirmed does exactly the same thing. Both are flagged destructive here, beehiiv: Create Post defaults its status to draft on purpose, and both need beehiiv's Max or Enterprise plan because they are the Send API. beehiiv: Delete Post is asymmetric in beehiiv's own words: a draft is permanently deleted, a confirmed post is archived, and neither unsends anything already out. The safe half of this surface is genuinely useful on its own: beehiiv: Get Post Preview URL renders a post as a chosen audience would see it and sends nothing to anyone, beehiiv: List Post Templates supplies the template ids a create can start from, and beehiiv: Get Aggregate Post Stats reports across everything that matched a filter. Two authoring notes: style and link tags are stripped from post content during sanitization, so post HTML must use inline styles, and content tags and author id lists REPLACE rather than append on an update.
Asynchronous work: posts and bulk jobs
Three surfaces here answer before they have finished, and treating them as synchronous is the most common way a beehiiv workflow goes wrong. Post creation and update return immediately with the post's stable id while the post is still being built, so a read straight afterwards can answer 202, meaning still processing and honour the retry hint, or 404 with a creation failed code, meaning it will never appear and the request needs fixing. 202 is a success status, so poll beehiiv: Get Post rather than chaining the next step directly onto the create. Bulk writes are the same shape: beehiiv: Bulk Create Subscriptions returns an import id and the two bulk update nodes return a job id, and beehiiv: Get Bulk Subscription Update polls until the status reads complete or failed. 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 the audit trail. A freshly created dynamic segment is the mild third case: it comes back pending and its members are listable only once processing finishes.
Reading engagement numbers correctly
beehiiv: Get Publication Engagements is the one genuinely windowed read: one row per period with total opens, unique opens, total clicks, unique clicks and the bot filtered verified click counts, over a start date plus a number of days, at day, week or month granularity. beehiiv caps that span at 31 days and rejects a longer request rather than truncating it, so a backfill loops over months rather than asking for a year. When you store the rows, one distinction decides whether the totals you build are true: the total counts are additive across periods, and the unique counts are not, because the same reader opening on Monday and Tuesday is one unique open per day and one, not two, across the pair, and no arithmetic on stored periods recovers that. The rate figures elsewhere in the API, on posts and on subscriptions, are lifetime or per entity values rather than periods, so they are read rather than averaged. One date format warning worth carrying into the config panel: this node takes its start date as year, month, day separated by hyphens, while beehiiv: List Subscriptions takes its creation date filter with slashes, and each node says which it wants.
Troubleshooting
Test Connection fails with a 401
Create Post or Update Post fails and everything else works
A post was created but reading it back returns 202 or 404
A bulk job says complete but some subscribers are missing
Writing a custom field value silently does nothing
A list read only returned ten rows, or paging suddenly returned a 400
A segment's member count looks stale or wrong
A tag appeared that nobody created
A by email node fails on an address that definitely exists
Calls start failing with 429 partway through a run
Related
The beehiiv MCP
What connecting beehiiv unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
beehiiv is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.