The Beehiiv connector lets your AI agent act in each user's Beehiiv account. Each user connects their own Beehiiv access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.
- Tools
- 60
- What they doRead · write · destructive
- 38 · 17 · 538 read17 write5 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Beehiiv connection
In AgentKit > Connections, create a Beehiiv connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'beehiiv'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Beehiiv:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'beehiiv_identify_workspace',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "beehiiv"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Beehiiv:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="beehiiv_identify_workspace",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Beehiiv credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbeehiiv_get_automationGet one automation by id.Read-onlyGet Automation
Get one automation by id. Returns the automation id, name, status, description, trigger events and stats. Use beehiiv_list_automations to find an automation id. Requires a publication_id and an automation_id.
Inputs
automation_idstringrequired- The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optional list of expandable objects. Allowed values: stats. Example: stats.one of
stats
beehiiv_get_automation_journeyGet one subscriber journey within an automation.Read-onlyGet Automation Journey
Get one subscriber journey within an automation. Returns the journey id, subscription id, email, status and start and completion times. Use beehiiv_list_automation_journeys to find a journey id. Requires an automation_id and a journey_id.
Inputs
automation_idstringrequired- The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000.
journey_idstringrequired- The prefixed automation journey id Use beehiiv_list_automation_journeys to find IDs. Example: aj_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_get_condition_setGet one condition set by id.Read-onlyGet Condition Set
Get one condition set by id. Returns the condition set id, name, status, purpose, timestamps and stats. Use beehiiv_list_condition_sets to find an id. Requires a publication_id and a condition_set_id.
Inputs
condition_set_idstringrequired- The UUID of the condition set object Use beehiiv_list_condition_sets to find IDs. Example: condition_set_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the response to include additional data. stats - Calculates and returns the active subscriber count for this condition set synchronously. Allowed values: stats. This tool sends a single value per call. Example: stats.one of
stats
beehiiv_get_custom_fieldGet one custom field by id.Read-onlyGet Custom Field
Get one custom field by id. Returns the field id, kind, display name, creation time and options. Use beehiiv_list_custom_fields to find a field id. Requires a publication_id and a custom_field_id.
Inputs
custom_field_idstringrequired- The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_get_engagementsGet daily or aggregate email engagement metrics for a publication over a date range.Read-onlyGet Publication Engagements
Get daily or aggregate email engagement metrics for a publication over a date range. Returns opens, unique opens, clicks and unique clicks per period. Use this for engagement trends. Use beehiiv_get_post_aggregate_stats for post-level totals. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- 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.
directionstring- The direction that the results are sorted in. Defaults to asc. asc: Oldest to newest desc: Newest to oldest Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc email_typestring- Filter engagement metrics by email type. If omitted, all email engagement is included. post: Only post emails. message: Only automated and system-generated emails. Allowed values: all, post, message. Example: all.one of
allpostmessage granularitystring- The granularity at which to report the engagement metrics. Defaults to day if not provided. Allowed values: day, week, month. Example: day.one of
dayweekmonth number_of_daysinteger- The number of days to return engagement metrics for, starting from start_date. Must be between 1 and 31. Defaults to 1 if not provided. Example: 7.
start_datestring- The starting date for the engagement metrics in YYYY-MM-DD format. Defaults to 1 day ago if not provided. Example: 2025-01-01.
beehiiv_get_pollGet one poll by id.Read-onlyGet Poll
Get one poll by id. Returns the poll id, name, question, type, status, choices, stats and response totals. Use beehiiv_list_polls to find a poll id. Requires a publication_id and a poll_id.
Inputs
poll_idstringrequired- The prefixed ID of the poll object Use beehiiv_list_polls to find IDs. Example: poll_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the response to include additional data. stats - Returns aggregate vote counts per choice and total completions. poll_responses - Returns up to 10 most recent subscriber responses. Use /polls/{pollId}/responses for paginated access to all responses. trivia_answer - Returns the correct answer for trivia-type polls. Allowed values: stats, poll_responses, trivia_answer. This tool sends a single value per call. Example: stats.one of
statspoll_responsestrivia_answer
beehiiv_get_postGet one post by id, optionally with stats or content in each format.Read-onlyGet Post
Get one post by id, optionally with stats or content in each format. Returns the post id, title, status, publish date, authors, web url and any expanded data. Use beehiiv_list_posts to find a post id. Use beehiiv_get_post_aggregate_stats for totals across posts. Use beehiiv_list_publications first to get the publication_id.
Inputs
post_idstringrequired- The prefixed ID of the post object Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the results by adding additional information. stats - Adds statistics about the post(s). free_web_content - Adds the web HTML rendered to a free reader. free_email_content - Adds the email HTML rendered to a free reader. free_rss_content - Adds the RSS feed HTML. premium_web_content - Adds the web HTML rendered to a premium reader. premium_email_content - Adds the email HTML rendered to a premium reader. Allowed values: stats, free_web_content, free_email_content, free_rss_content, premium_web_content, premium_email_content, recipients. This tool sends a single value per call. Example: stats.one of
statsfree_web_contentfree_email_contentfree_rss_contentpremium_web_contentpremium_email_contentrecipients premium_tiersstring- Scope any expanded content output to the specified premium tiers. This takes in an array of Display Names of the premium tiers. Note: This is case insensitive. This tool sends a single value per call. Example: Gold.
beehiiv_get_post_aggregate_statsGet aggregate email, web and click statistics across posts in a publication, filtered by audience, platform or status.Read-onlyGet 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.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
audiencestring- Optionally filter the results by audience Allowed values: free, premium, all. Example: free.one of
freepremiumalldefaultall authorsstring- 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_tagsstring- 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_feedstring- 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
alltruefalsedefaultall platformstring- 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
webemailbothalldefaultall statusstring- 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
draftconfirmedarchivedalldefaultall
beehiiv_get_post_templateGet one post template by id.Read-onlyGet Post Template
Get one post template by id. Returns the template id, name, description, default authors, tags and email settings. Use beehiiv_list_post_templates to find a template id. Requires a publication_id and a post_template_id.
Inputs
post_template_idstringrequired- The prefixed ID of the post template object Use beehiiv_list_post_templates to find IDs. Example: post_template_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the result by adding the rendered HTML of the template. free_web_content - Adds the web HTML rendered to a free reader. free_email_content - Adds the email HTML rendered to a free reader. free_rss_content - Adds the RSS feed HTML. premium_web_content - Adds the web HTML rendered to a premium reader. premium_email_content - Adds the email HTML rendered to a premium reader. Allowed values: free_web_content, free_email_content, free_rss_content, premium_web_content, premium_email_content. This tool sends a single value per call. Example: stats.one of
free_web_contentfree_email_contentfree_rss_contentpremium_web_contentpremium_email_content
beehiiv_get_publicationGet one beehiiv publication by id, optionally with stats.Read-onlyGet Publication
Get one beehiiv publication by id, optionally with stats. Returns the publication id, name, organization name, creation time and referral program flag. Use beehiiv_list_publications to browse all publications. Requires a publication_id from beehiiv_list_publications.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the results by adding additional information like subscription counts and engagement stats. Allowed values: stats, stat_active_subscriptions, stat_active_premium_subscriptions, stat_active_free_subscriptions, stat_average_open_rate, stat_average_click_rate, stat_total_sent, stat_total_unique_opened, stat_total_clicked. This tool sends a single value per call. Example: stats.one of
statsstat_active_subscriptionsstat_active_premium_subscriptionsstat_active_free_subscriptionsstat_average_open_ratestat_average_click_ratestat_total_sentstat_total_unique_openedstat_total_clicked
beehiiv_get_referral_programGet the referral program configuration of a publication.Read-onlyGet Referral Program
Get the referral program configuration of a publication. Returns the program id, reward details, auto fulfill setting and referral count. Use this to check whether referrals are set up before reading referral data on subscribers. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_get_segmentGet one segment by id.Read-onlyGet Segment
Get one segment by id. Returns the segment id, name, type, status, last calculated time, subscriber count and stats. Use beehiiv_list_segments to find a segment id. Requires a publication_id and a segment_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
segment_idstringrequired- The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the response to include additional data. stats - Requests the most recently calculated statistics for a segment. Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation. Allowed values: stats. This tool sends a single value per call. Example: stats.one of
stats
beehiiv_get_subscription_by_emailLook up one subscriber by email address, optionally with stats, custom fields, referrals or newsletter lists.Read-onlyGet Subscription by Email
Look up one subscriber by email address, optionally with stats, custom fields, referrals or newsletter lists. Returns the subscription id, email, status, tier and any expanded data. Use beehiiv_get_subscription_by_id when you already have the subscription id. Use beehiiv_list_publications first to get the publication_id.
Inputs
emailstringrequired- The ID of the subscriber object. Example: reader@example.com.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optional list of expandable objects. subscription_premium_tiers - Returns an array of tiers the subscription is associated with. referrals - Returns an array of subscriptions with limited data - id, email, and status. These are the subscriptions that were referred by this subscription. stats - Returns statistics about the subscription(s). custom_fields - Returns an array of custom field values that have been set on the subscription. tags - Returns an array of tags that have been set on the subscription. newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to. Allowed values: stats, custom_fields, referrals, tags, newsletter_lists. Example: stats.one of
statscustom_fieldsreferralstagsnewsletter_lists
beehiiv_get_subscription_by_idGet one subscriber by subscription id, optionally with stats, custom fields, referrals or newsletter lists.Read-onlyGet Subscription by ID
Get one subscriber by subscription id, optionally with stats, custom fields, referrals or newsletter lists. Returns the subscription id, email, status, tier and any expanded data. Use beehiiv_get_subscription_by_email when you only know the email address. Requires a subscription_id from beehiiv_list_subscriptions.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
subscription_idstringrequired- The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.
expandstring- Optional list of expandable objects. subscription_premium_tiers - Returns an array of tiers the subscription is associated with. referrals - Returns an array of subscriptions with limited data - id, email, and status. These are the subscriptions that were referred by this subscription. stats - Returns statistics about the subscription(s). custom_fields - Returns an array of custom field values that have been set on the subscription. tags - Returns an array of tags that have been set on the subscription. newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to. Allowed values: stats, custom_fields, referrals, tags, newsletter_lists. Example: stats.one of
statscustom_fieldsreferralstagsnewsletter_lists
beehiiv_get_subscription_exportGet the status of a subscriber export.Read-onlyGet Subscription Export
Get the status of a subscriber export. Returns the export id, status, failure reason and, once complete, the download url. Use beehiiv_create_subscription_export to start one. Use beehiiv_list_subscription_exports to find past exports. Requires an export_id.
Inputs
export_idstringrequired- The prefixed ID of the Subscription Export object Use beehiiv_list_subscription_exports to find IDs. Example: export_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_get_tierGet one premium tier by id.Read-onlyGet Tier
Get one premium tier by id. Returns the tier id, name, status, description, stats and prices. Use beehiiv_list_tiers to find a tier id. Requires a publication_id and a tier_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
tier_idstringrequired- The prefixed ID of the tier object Use beehiiv_list_tiers to find IDs. Example: tier_00000000-0000-0000-0000-000000000000.
expandstring- Optional list of expandable objects. stats - Returns statistics about the tier(s). prices - Returns prices for the tier(s). Example: stats.
beehiiv_identify_workspaceIdentify the workspace that owns the API key.Read-onlyIdentify Workspace
Identify the workspace that owns the API key. Returns the workspace id, name and owner email. Use this to confirm which account a connection is authenticated as.
Inputs
This tool takes no inputs.
beehiiv_list_automation_emailsList the emails sent by an automation, with per-email stats.Read-onlyList Automation Emails
List the emails sent by an automation, with per-email stats. Returns each email id, subject line, preview text, status, send times and stats, plus pagination fields. Use beehiiv_get_automation for the automation itself. Requires an automation_id from beehiiv_list_automations.
Inputs
automation_idstringrequired- The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. Obtain it from the next_cursor field of a previous response. Example: eyJpZCI6MTIzfQ.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Deprecated: Use cursor instead. Pagination returns the results in pages. Limited to 100 pages maximum. Example: 1.
beehiiv_list_automation_journeysList the subscriber journeys running through an automation.Read-onlyList Automation Journeys
List the subscriber journeys running through an automation. Returns each journey id, subscriber email, status and start and completion times, plus pagination fields. Use beehiiv_get_automation_journey for one journey. Requires an automation_id from beehiiv_list_automations.
Inputs
automation_idstringrequired- The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). Example: 1.
statusstring- Optionally filter the results by the automation journey's status. Allowed values: in_progress, completed, exited_early, all. Example: active.one of
in_progresscompletedexited_earlyalldefaultall
beehiiv_list_automationsList the email automations in a publication.Read-onlyList Automations
List the email automations in a publication. Returns each automation id, name, status, description, trigger events and stats, plus pagination fields. Use beehiiv_get_automation for one automation. Use beehiiv_list_automation_journeys to see who is in it. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
expandstring- Optional list of expandable objects. Allowed values: stats. Example: stats.one of
stats limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_list_condition_setsList the saved condition sets of a publication, used to target content or segments.Read-onlyList Condition Sets
List the saved condition sets of a publication, used to target content or segments. Returns each condition set id, name, status, purpose and timestamps, plus pagination fields. Use beehiiv_get_condition_set for one condition set. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. Example: eyJpZCI6MTIzfQ.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Offset-based pagination (deprecated): Page number for offset-based pagination. Please migrate to cursor-based pagination using the cursor parameter. If not specified, results 1-10 from page 1 will be returned. Example: 1.
purposestring- Filter condition sets by purpose. When not specified, all active condition sets are returned. Allowed values: dynamic_content. Example: dynamic_content.one of
dynamic_content
beehiiv_list_custom_fieldsList the custom fields defined on a publication.Read-onlyList Custom Fields
List the custom fields defined on a publication. Returns each field id, kind, display name, creation time and options, plus pagination fields. Use this to find field names before setting custom_fields on a subscriber. Use beehiiv_get_custom_field for one field. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_list_poll_responsesList the individual responses to a poll.Read-onlyList Poll Responses
List the individual responses to a poll. Returns each response id, subscription id, chosen option, feedback text and the post it came from, plus pagination fields. Use beehiiv_get_poll for aggregate results. Requires a poll_id from beehiiv_list_polls.
Inputs
poll_idstringrequired- The prefixed ID of the poll object Use beehiiv_list_polls to find IDs. Example: poll_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. Example: eyJpZCI6MTIzfQ.
directionstring- The direction that the results are sorted in. Defaults to asc. asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optionally expand the response to include additional data. post - Returns the post title and publication date for the post where each response was collected. Allowed values: post. This tool sends a single value per call. Example: stats.one of
post limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created. Allowed values: created. Example: created.one of
createddefaultcreated pageinteger- Offset-based pagination (deprecated): Page number for offset-based pagination. Example: 1.
post_idstring- Filter to only return responses collected via the specified post. Accepts a prefixed post ID (e.g. post_abc123). Example: post_00000000-0000-0000-0000-000000000000.
beehiiv_list_pollsList the polls in a publication.Read-onlyList Polls
List the polls in a publication. Returns each poll id, name, question, type, status, choices and response totals, plus pagination fields. Use beehiiv_get_poll for one poll. Use beehiiv_list_poll_responses for individual answers. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. Example: eyJpZCI6MTIzfQ.
directionstring- The direction that the results are sorted in. Defaults to asc. asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optionally expand the response to include additional data. stats - Returns aggregate vote counts per choice and total completions. poll_responses - Returns up to 10 most recent subscriber responses. Use /polls/{pollId}/responses for paginated access to all responses. trivia_answer - Returns the correct answer for trivia-type polls. Allowed values: stats, poll_responses, trivia_answer. This tool sends a single value per call. Example: stats.one of
statspoll_responsestrivia_answer limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created. created - The time the poll was created. name - The name of the poll. Allowed values: created, name. Example: created.one of
creatednamedefaultcreated pageinteger- Offset-based pagination (deprecated): Page number for offset-based pagination. Please migrate to cursor-based pagination using the cursor parameter. If not specified, results 1-10 from page 1 will be returned. Example: 1.
post_idstring- Filter to only return polls that were embedded in the specified post. Accepts a prefixed post ID (e.g. post_abc123). Example: post_00000000-0000-0000-0000-000000000000.
beehiiv_list_post_templatesList the post templates available in a publication.Read-onlyList Post Templates
List the post templates available in a publication. Returns each template id, name, description and timestamps, plus pagination fields. Use beehiiv_get_post_template for one template. Pass a template id as post_template_id when creating a post. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
orderstring- The direction of the request. Defaults to asc. Allowed values: asc, desc. Example: asc.one of
ascdescdefaultasc order_bystring- The field to order by. Defaults to created. Example: created.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_list_postsList posts in a publication, filtered by status, audience, platform, tags, slugs or authors.Read-onlyList Posts
List posts in a publication, filtered by status, audience, platform, tags, slugs or authors. Returns each post id, title, subtitle, status, publish date, slug, thumbnail and web url, plus pagination fields. Use this to browse or filter posts. Use beehiiv_get_post for one post with full content. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
audiencestring- Optionally filter the results by audience Allowed values: free, premium, all. Example: free.one of
freepremiumalldefaultall authorsstring- 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_tagsstring- 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.
directionstring- The direction that the results are sorted in. Defaults to asc asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optionally expand the results by adding additional information. stats - Adds statistics about the post(s). free_web_content - Adds the web HTML rendered to a free reader. free_email_content - Adds the email HTML rendered to a free reader. free_rss_content - Adds the RSS feed HTML. premium_web_content - Adds the web HTML rendered to a premium reader. premium_email_content - Adds the email HTML rendered to a premium reader. Allowed values: stats, free_web_content, free_email_content, free_rss_content, premium_web_content, premium_email_content, recipients. This tool sends a single value per call. Example: stats.one of
statsfree_web_contentfree_email_contentfree_rss_contentpremium_web_contentpremium_email_contentrecipients hidden_from_feedstring- 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
alltruefalsedefaultall limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created created - The time in which the post was first created. publish_date - The time the post was set to be published. displayed_date - The time displayed in place of the publish_date. If no displayed_date was set, it will default to the publish_date Allowed values: created, publish_date, displayed_date. Example: created.one of
createdpublish_datedisplayed_datedefaultcreated pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
platformstring- 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
webemailbothalldefaultall premium_tiersstring- Optionally filter posts by audience based on premium tiers. This takes in an array of Display Names of the premium tiers. It will also scope any expanded content output to the specified premium tiers. Note: This is case insensitive. This tool sends a single value per call. Example: Gold.
slugsstring- Optionally filter posts by their slugs. Adding a slug will return any post with that exact slug associated to it. Example: Filtering for slugs: ["my-first-post","another-post"] will return results of posts that have either my-first-post or another-post as their slug. This tool sends a single value per call. Example: weekly-digest.
statusstring- 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
draftconfirmedarchivedalldefaultall
beehiiv_list_publicationsList the beehiiv publications the API key can access, optionally with stats.Read-onlyList Publications
List the beehiiv publications the API key can access, optionally with stats. Returns each publication id, name, organization name, creation time and referral program flag, plus pagination fields. Use this first to get the publication_id that every other beehiiv tool needs. Use beehiiv_get_publication for one publication.
Inputs
directionstring- The direction that the results are sorted in. Defaults to asc asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optionally expand the results by adding additional information like subscription counts and engagement stats. Allowed values: stats, stat_active_subscriptions, stat_active_premium_subscriptions, stat_active_free_subscriptions, stat_average_open_rate, stat_average_click_rate, stat_total_sent, stat_total_unique_opened, stat_total_clicked. This tool sends a single value per call. Example: stats.one of
statsstat_active_subscriptionsstat_active_premium_subscriptionsstat_active_free_subscriptionsstat_average_open_ratestat_average_click_ratestat_total_sentstat_total_unique_openedstat_total_clicked limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created created - The time in which the publication was first created. name - The name of the publication. Allowed values: created, name. Example: created.one of
creatednamedefaultcreated pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_list_segment_membersList the subscribers who belong to a segment.Read-onlyList Segment Subscribers
List the subscribers who belong to a segment. Returns each subscriber id, email, status, tier and UTM fields, plus pagination fields. Use beehiiv_list_segment_subscriber_ids when you only need ids. Requires a segment_id from beehiiv_list_segments.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
segment_idstringrequired- The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
expandstring- Optionally expand the response to include additional data. stats - Returns statistics about the subscription(s). custom_fields - Returns custom field values set on the subscription. referrals - Returns referrals made by the subscription. tags - Returns tags associated with the subscription. subscription_premium_tiers - Returns premium tier(s) the subscription is subscribed to. Allowed values: stats, custom_fields, referrals, tags, subscription_premium_tiers. This tool sends a single value per call. Example: stats.one of
statscustom_fieldsreferralstagssubscription_premium_tiers limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_list_segment_subscriber_idsList only the subscription ids of the subscribers in a segment.Read-onlyList Segment Subscriber IDs
List only the subscription ids of the subscribers in a segment. Returns an array of subscription ids with pagination fields. Use beehiiv_list_segment_members when you need subscriber details such as email. Requires a segment_id from beehiiv_list_segments.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
segment_idstringrequired- The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_list_segmentsList subscriber segments in a publication, optionally filtered by type or status.Read-onlyList Segments
List subscriber segments in a publication, optionally filtered by type or status. Returns each segment id, name, type, status, last calculated time and subscriber count, plus pagination fields. Use beehiiv_get_segment for one segment. Use beehiiv_list_segment_members for the subscribers in a segment. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
directionstring- The direction that the results are sorted in. Defaults to asc asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optionally expand the response to include additional data. stats - Requests the most recently calculated statistics for a segment. Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation. Allowed values: stats. This tool sends a single value per call. Example: stats.one of
stats limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created created - The time in which the segment was first created. last_calculated - The time that the segment last completed calculation. Measured in seconds since the Unix epoch. Allowed values: created, last_calculated. Example: created.one of
createdlast_calculateddefaultcreated pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
statusstring- Optionally filter the results by the segment's status. Allowed values: pending, processing, completed, failed, all. Example: active.one of
pendingprocessingcompletedfailedalldefaultall typestring- Optionally filter the results by the segment's type. Allowed values: dynamic, static, manual, all. Example: dynamic.one of
dynamicstaticmanualalldefaultall
beehiiv_list_subscription_exportsList past subscriber exports of a publication.Read-onlyList Subscription Exports
List past subscriber exports of a publication. Returns each export id, variant, status, timestamps and download url, plus pagination fields. Use beehiiv_get_subscription_export for one export. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the [Pagination Guide](/welcome/pagination) for more details. Example: eyJpZCI6MTIzfQ.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Offset-based pagination (deprecated): Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the cursor parameter. If not specified, results 1-10 from page 1 will be returned. See the [Pagination Guide](/welcome/pagination) for migration guidance. Example: 1.
beehiiv_list_subscriptionsList subscribers of a publication, filtered by status, tier, email or creation date, with cursor or page pagination.Read-onlyList Subscriptions
List subscribers of a publication, filtered by status, tier, email or creation date, with cursor or page pagination. Returns each subscription id, email, status, tier, creation time and UTM fields, plus pagination fields. Use this to browse subscribers. Use beehiiv_get_subscription_by_email for a single known email. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
creation_datestring- Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date. Example: 2025/01/15.
cursorstring- Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. When provided, pagination will use cursor-based method which is more efficient and consistent than offset-based pagination. See the [Pagination Guide](/welcome/pagination) for more details. Example: eyJpZCI6MTIzfQ.
directionstring- The direction that the results are sorted in. Defaults to asc asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc emailstring- Optional email address to find a subscription. This param must be an exact match and is case insensitive. Example: reader@example.com.
expandstring- Optional list of expandable objects. subscription_premium_tiers - Returns an array of tiers the subscription is associated with. referrals - Returns an array of subscriptions with limited data - id, email, and status. These are the subscriptions that were referred by this subscription. stats - Returns statistics about the subscription(s). custom_fields - Returns an array of custom field values that have been set on the subscription. newsletter_lists - Returns an array of newsletter list prefixed IDs the subscription is actively subscribed to. Allowed values: stats, custom_fields, referrals, newsletter_lists. Example: stats.one of
statscustom_fieldsreferralsnewsletter_lists limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
order_bystring- The field that the results are sorted by. Defaults to created created - The time in which the subscription was first created. Allowed values: created. Example: created.one of
createddefaultcreated pageinteger- Offset-based pagination (deprecated): Page number for offset-based pagination. This method is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination using the cursor parameter. If not specified, results 1-10 from page 1 will be returned. See the [Pagination Guide](/welcome/pagination) for migration guidance. Example: 1.
premium_tier_idsstring- Optionally filter the results by one or multiple premium tier ids. Example: premium_00000000-0000-0000-0000-000000000000.
premium_tiersstring- Optionally filter the results by one or multiple premium tiers. Example: Gold.
statusstring- Optionally filter the results by a status Allowed values: validating, invalid, pending, active, inactive, all. Example: active.one of
validatinginvalidpendingactiveinactivealldefaultall tierstring- Optionally filter the results by a their tier Allowed values: free, premium, all. Example: premium.one of
freepremiumalldefaultall
beehiiv_list_tiersList the premium tiers of a publication.Read-onlyList Tiers
List the premium tiers of a publication. Returns each tier id, name, status, description, stats and prices, plus pagination fields. Use beehiiv_get_tier for one tier. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
directionstring- The direction that the results are sorted in. Defaults to asc asc - Ascending, sorts from smallest to largest. desc - Descending, sorts from largest to smallest. Allowed values: asc, desc. Example: desc.one of
ascdescdefaultasc expandstring- Optional list of expandable objects. stats - Returns statistics about the tier(s). prices - Returns prices for the tier(s). Example: stats.
limitinteger- A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Example: 25.
pageinteger- Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). If not specified, results 1-10 from page 1 will be returned. Example: 1.
beehiiv_add_subscription_to_automationEnroll a subscriber in an automation by email or subscription id.WriteAdd Subscription to Automation
Enroll a subscriber in an automation by email or subscription id. Returns the new journey with its id, status and start time. Use beehiiv_list_automations to find an automation that accepts manual enrollment. Requires an automation_id from beehiiv_list_automations.
Inputs
automation_idstringrequired- The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
double_opt_overridestring- Override the publication's default double opt-in settings for this subscription. Possible values are: - "on" — The subscriber will receive a double opt-in confirmation email and will need to confirm their subscription prior to being marked as active. - "off" — The subscriber will be marked as active immediately and will not receive a double opt-in confirmation email. - "not_set" — The publication's default double opt-in settings will be applied to this subscription. Example: on.
emailstring- The email address associated with the subscription. Example: reader@example.com.
subscription_idstring- The prefixed ID of the subscription. Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.
beehiiv_bulk_create_subscriptionsQueue the creation of many subscribers in one request.WriteBulk Create Subscriptions
Queue the creation of many subscribers in one request. Returns a message and an import id for the queued job. Use beehiiv_create_subscription for a single subscriber. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
subscriptionsarrayrequired- Subscribers to create, as an array of subscription objects. Each needs an email and may also set reactivate_existing, send_welcome_email, utm fields, tier, custom_fields and newsletter_list_ids. Example: [{"email":"a@example.com"},{"email":"b@example.com","send_welcome_email":true}].
beehiiv_create_custom_fieldCreate a custom field on a publication with a data kind and display name.WriteCreate Custom Field
Create a custom field on a publication with a data kind and display name. Returns the new field id, kind, display name and options. Use beehiiv_update_custom_field to rename a field later. Use beehiiv_list_publications first to get the publication_id.
Inputs
displaystringrequired- Display name of the custom field as shown in beehiiv. Example: Company.
kindstringrequired- The type of value being stored in the custom field. Allowed values: string, integer, boolean, date, datetime, list, double. Example: string.one of
stringintegerbooleandatedatetimelistdouble publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_create_postCreate a post in a publication as a draft or scheduled issue, with HTML or block content.WriteCreate Post
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.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
titlestringrequired- The title of the post. Example: Weekly Digest.
blocksarray- 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_contentstring- 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><p>Welcome to this week's issue.</p>.
content_tagsarray- The content tags to use for this post. If not provided, the default value will be used. Example: ["sales"].
custom_fieldsobject- Custom field values as an object of field name to value. Example: {"Company":"Acme"}.
custom_link_tracking_enabledboolean- 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_overridestring- 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
nonegatedpopup email_settingsobject- 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_idsarray- 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"].
headersobject- Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}.
newsletter_list_idstring- 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_atstring- 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_idstring- 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.
recipientsobject- 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_atstring- 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_settingsobject- 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_sharestring- 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_onlywith_comments_and_likestopnone statusstring- 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
draftconfirmed subtitlestring- The subtitle of the post. Example: What happened this week.
team_author_idsarray- 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_urlstring- 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_campaignstring- 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_mediumstring- 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_enabledboolean- Whether UTM parameters are appended to links in this post. Omit to inherit from the newsletter list, then the publication. Example: true.
utm_sourcestring- 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_settingsobject- 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_subscriptionSubscribe an email address to a publication, with optional tier, tags, UTM data, custom fields, automations and newsletter lists.WriteCreate Subscription
Subscribe an email address to a publication, with optional tier, tags, UTM data, custom fields, automations and newsletter lists. Returns the new subscription id, email, status and tier, plus any warnings. Use beehiiv_bulk_create_subscriptions for many emails at once. Use beehiiv_update_subscription_by_id to change an existing subscriber. Use beehiiv_list_publications first to get the publication_id.
Inputs
emailstringrequired- The email address of the subscription. Example: reader@example.com.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
automation_idsarray- Enroll the subscriber into automations after their subscription has been created. Requires the automations to have an active Add by API trigger. Example: ["aut_00000000-0000-0000-0000-000000000000"].
complimentary_gift_idstring- 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_fieldsarray- Custom field values to set on the subscriber, as an array of objects with a name (the custom field name) and a value. Example: [{"name":"Company","value":"Acme"}].
double_opt_overridestring- Override the publication's default double opt-in settings for this subscription. Possible values are: - "on" — The subscriber will receive a double opt-in confirmation email and will need to confirm their subscription prior to being marked as active. - "off" — The subscriber will be marked as active immediately and will not receive a double opt-in confirmation email. - "not_set" — The publication's default double opt-in settings will be applied to this subscription. Example: on.
newsletter_list_idsarray- An array of newsletter list prefixed IDs to subscribe the new subscription to. The newsletter lists must belong to the same publication. Example: ["list_00000000-0000-0000-0000-000000000000"].
premium_tier_idsarray- 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_tiersarray- 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"].
reactivate_existingboolean- Whether or not to reactivate the subscription if they have already unsubscribed. This option should be used only if the subscriber is knowingly resubscribing. Example: true.
referral_codestring- This should be a subscribers referral_code. This gives referral credit for the new subscription. Example: ABC123.
referring_sitestring- The website that the subscriber was referred from. Example: https://example.com.
send_welcome_emailboolean- Whether to send the publication welcome email to the new subscriber. Example: true.
skip_newsletter_list_auto_subscribeboolean- When true, the subscriber will not be auto-subscribed to newsletter lists configured with auto-subscribe. Defaults to false. Example: true.
stripe_customer_idstring- The Stripe customer ID for this subscription. Example: cus_123456789.
tierstring- The tier for this subscription. Allowed values: free, premium. Example: premium.one of
freepremium utm_campaignstring- The acquisition campaign of the subscription. Example: launch.
utm_contentstring- The acquisition content; typically used for A/B testing or ad variations. Example: cta.
utm_mediumstring- The medium of the subscription. Example: social.
utm_sourcestring- The source of the subscription. Example: twitter.
utm_termstring- The acquisition term; typically the keyword or search term. Example: newsletter.
beehiiv_create_subscription_exportStart an export of subscribers as a downloadable file, optionally limited to a segment.WriteCreate Subscription Export
Start an export of subscribers as a downloadable file, optionally limited to a segment. Returns the export id, variant and status; an existing recent export may be reused. Use beehiiv_get_subscription_export with the returned id to get the download url when it completes. Use beehiiv_list_publications first to get the publication_id.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
variantstringrequired- Which column set the export uses Allowed values: full, basic. Example: full.one of
fullbasic segment_idstring- Optional prefixed ID of a segment to scope the export to. When omitted the export covers the whole publication. A segment that does not exist, or belongs to another publication, answers 404. Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
beehiiv_create_tierCreate a premium tier with a name, description and price points.WriteCreate Tier
Create a premium tier with a name, description and price points. Returns the new tier with its prices. Use beehiiv_update_tier to change a tier later. Use beehiiv_list_publications first to get the publication_id.
Inputs
namestringrequired- Name. Example: Founders.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
descriptionstring- Description text. Example: Short description.
prices_attributesarray- Price points for the tier as an array of price objects, each with currency, amount_cents, interval and optionally enabled, interval_display, cta and features. Example: [{"currency":"usd","amount_cents":1000,"interval":"month"}].
beehiiv_recalculate_segmentQueue a recalculation of a segment so its membership reflects current subscribers.WriteRecalculate Segment
Queue a recalculation of a segment so its membership reflects current subscribers. Returns a confirmation message. Use this before reading a segment whose last calculated time is stale. Requires a segment_id from beehiiv_list_segments.
- Idempotent
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
segment_idstringrequired- The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
beehiiv_update_custom_fieldRename a custom field by changing its display name.WriteUpdate Custom Field
Rename a custom field by changing its display name. Returns the updated field. Use beehiiv_create_custom_field for a new field. The kind of an existing field cannot be changed. Requires a custom_field_id from beehiiv_list_custom_fields.
Inputs
custom_field_idstringrequired- The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
displaystring- Display name of the custom field as shown in beehiiv. Example: Company.
beehiiv_update_postUpdate fields of an existing post, such as title, content, schedule, status or email and web settings.WriteUpdate Post
Update fields of an existing post, such as title, content, schedule, status or email and web settings. Returns the updated post, or an accepted status when the update is processed asynchronously. Use beehiiv_create_post for a new post. Use content_merge_strategy to control how new body content combines with existing content. Requires a post_id from beehiiv_list_posts.
Inputs
post_idstringrequired- The prefixed ID of the post to update Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
blocksarray- 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_contentstring- Raw HTML to replace the post's current content. The HTML is wrapped in an htmlSnippet block internally. Note that and tags are removed during sanitization — use inline styles for all visual styling. Cannot be provided together with blocks. Example: <h2>Hello</h2><p>Welcome to this week's issue.</p>.
content_merge_strategystring- Controls how provided blocks interact with the post's existing content. Defaults to replace. Use append_to_template to preserve template header blocks when updating posts that were created from a template. Allowed values: replace, append_to_template, append, prepend. Example: append.one of
replaceappend_to_templateappendprepend content_tagsarray- The content tags for this post. When provided, this replaces all existing content tags on the post. Example: ["sales"].
custom_link_tracking_enabledboolean- If true, custom link tracking will be enabled for this post. Example: true.
email_capture_type_overridestring- The email capture type to use for this post. Allowed values: none, gated, popup. Example: popup.one of
nonegatedpopup email_settingsobject- 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_idsarray- The prefixed IDs of the guest authors to associate with this post. Guest authors must belong to the publication. When provided, replaces all existing guest authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"].
headersobject- Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}.
newsletter_list_idstring- The prefixed ID of the newsletter list to associate with this post. When provided, updates the newsletter list association. Pass null to remove the association. Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000.
override_scheduled_atstring- A display date that overrides the scheduled_at date shown in the email. Does not affect the actual publish date. Example: 2025-06-01T09:00:00Z.
recipientsobject- 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_atstring- The time at which the post will be published. Cannot be updated after the post has already been sent. Example: 2025-06-01T09:00:00Z.
seo_settingsobject- 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_sharestring- The social share type to use for this post. Allowed values: comments_and_likes_only, with_comments_and_likes, top, none. Example: top.one of
comments_and_likes_onlywith_comments_and_likestopnone statusstring- Transition the post's status. Use confirmed to schedule or publish a draft post. Only the draft → confirmed transition is supported — a confirmed post cannot be moved back to draft. Allowed values: draft, confirmed. Example: active.one of
draftconfirmed subtitlestring- The subtitle of the post. Example: What happened this week.
team_author_idsarray- The prefixed IDs of the team members to associate with this post as authors. Team authors must have access to the publication. When provided, replaces all existing team authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"].
thumbnail_image_urlstring- The URL of the thumbnail image to use for the post. Example: https://example.com/cover.jpg.
titlestring- The title of the post. Example: Weekly Digest.
utm_campaignstring- 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_mediumstring- 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_enabledboolean- Whether UTM parameters are appended to links in this post. When left unset on the post, falls back to the newsletter list, then the publication. Example: true.
utm_sourcestring- 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_settingsobject- 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_update_subscription_by_emailUpdate a subscriber by email address, such as tier, custom fields, newsletter lists or unsubscribe status.WriteUpdate Subscription by Email
Update a subscriber by email address, such as tier, custom fields, newsletter lists or unsubscribe status. Returns the updated subscription and any warnings. Use beehiiv_update_subscription_by_id when you already have the subscription id. Use beehiiv_list_publications first to get the publication_id.
- Idempotent
Inputs
emailstringrequired- The new email address for the subscription. Example: reader@example.com.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
complimentary_gift_idstring- 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_fieldsarray- 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"}].
newsletter_list_idsarray- 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_idsarray- 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_tiersarray- 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_idstring- The Stripe Customer ID of the subscription (not required). Example: cus_123456789.
tierstring- Optional parameter to set the tier for this subscription. Allowed values: free, premium. Example: premium.one of
freepremium unsubscribeboolean- A boolean value specifying whether to unsubscribe this subscription from the publication (not required). Example: false.
unsubscribe_newsletter_list_idsarray- 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"].
beehiiv_update_subscription_by_idUpdate a subscriber by subscription id, such as tier, custom fields, newsletter lists or unsubscribe status.WriteUpdate 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.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
subscription_idstringrequired- The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.
complimentary_gift_idstring- 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_fieldsarray- 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"}].
emailstring- The new email address for the subscription. Example: reader@example.com.
newsletter_list_idsarray- 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_idsarray- 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_tiersarray- 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_idstring- The Stripe Customer ID of the subscription (not required). Example: cus_123456789.
tierstring- Optional parameter to set the tier for this subscription. Allowed values: free, premium. Example: premium.one of
freepremium unsubscribeboolean- A boolean value specifying whether to unsubscribe this subscription from the publication (not required). Example: false.
unsubscribe_newsletter_list_idsarray- 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"].
beehiiv_update_tierUpdate a premium tier name, description or price points.WriteUpdate Tier
Update a premium tier name, description or price points. Returns the updated tier. Use beehiiv_create_tier for a new tier. Include a price id in prices_attributes to edit an existing price. Requires a tier_id from beehiiv_list_tiers.
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
tier_idstringrequired- The prefixed ID of the tier object Use beehiiv_list_tiers to find IDs. Example: tier_00000000-0000-0000-0000-000000000000.
descriptionstring- Description text. Example: Short description.
namestring- Name. Example: Founders.
prices_attributesarray- Price points for the tier as an array of price objects, each with currency, amount_cents, interval and optionally enabled, interval_display, cta and features. Example: [{"currency":"usd","amount_cents":1000,"interval":"month"}].
beehiiv_delete_custom_fieldDelete a custom field and the values stored in it.DestructiveDelete Custom Field
Delete a custom field and the values stored in it. Returns a confirmation message. Use beehiiv_update_custom_field if you only want to rename it. Deleting cannot be undone. Requires a custom_field_id from beehiiv_list_custom_fields.
- Idempotent
Inputs
custom_field_idstringrequired- The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_delete_postDelete a post by id, which also archives it for readers.DestructiveDelete Post
Delete a post by id, which also archives it for readers. Returns the post id and its resulting state. Use beehiiv_update_post with status archived if you only want to hide a post. Requires a post_id from beehiiv_list_posts.
- Idempotent
Inputs
post_idstringrequired- The prefixed ID of the post object Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000.
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
beehiiv_delete_segmentDelete a segment by id without deleting its subscribers.DestructiveDelete Segment
Delete a segment by id without deleting its subscribers. Returns a confirmation message. Use beehiiv_list_segments to confirm the segment first. Deleting cannot be undone. Requires a segment_id from beehiiv_list_segments.
- Idempotent
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
segment_idstringrequired- The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000.
beehiiv_delete_subscriptionPermanently delete a subscriber from a publication by subscription id.DestructiveDelete Subscription
Permanently delete a subscriber from a publication by subscription id. Returns a confirmation message. Use beehiiv_update_subscription_by_id with unsubscribe true to keep the subscriber record. Deleting cannot be undone. Requires a subscription_id from beehiiv_list_subscriptions.
- Idempotent
Inputs
publication_idstringrequired- The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000.
subscription_idstringrequired- The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000.
No tools match.
