> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Beehiiv 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. **Authentication:** Bearer Token **Categories:** Communication, Marketing **Tools:** 60: 38 read, 17 write, 5 destructive **Users sign in with:** Access token **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BEEHIIV) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Beehiiv connection In **AgentKit > Connections**, create a Beehiiv connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript 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.actions const connector = 'beehiiv' const identifier = 'user_123' // Generate an authorization link for the user const { 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 call const result = await actions.executeTool({ connector, identifier, toolName: 'beehiiv_identify_workspace', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_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.actions connection_name = "beehiiv" identifier = "user_123" # Generate an authorization link for the user link_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 call result = actions.execute_tool( tool_input={}, tool_name="beehiiv_identify_workspace", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user opens the link once and enters their Beehiiv credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'beehiiv_get_author', toolInput: { author_id: '', publication_id: '', }, connector: 'beehiiv', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="beehiiv_get_author", tool_input={ "author_id": "", "publication_id": "", }, connection_name="beehiiv", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `beehiiv_get_author` Get Author · Read-only Get one author by id. Returns the author id, name, bio, image url and social links. Use beehiiv_list_authors to find an author id. Requires a publication_id and an author_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `author_id` (`string`, required): The author identifier. This accepts a prefixed author ID, full name, or first name. Use beehiiv_list_authors to find IDs. Example: author_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"author_id":"","publication_id":""}` ### `beehiiv_get_automation` Get Automation · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `automation_id` (`string`, required): The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): Optional list of expandable objects. Allowed values: stats. Example: stats. One of: `stats`. Example input: `{"automation_id":"","publication_id":""}` ### `beehiiv_get_automation_journey` Get Automation Journey · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `automation_id` (`string`, required): The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000. - `journey_id` (`string`, required): The prefixed automation journey id Use beehiiv_list_automation_journeys to find IDs. Example: aj_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"automation_id":"","journey_id":"","publication_id":""}` ### `beehiiv_get_condition_set` Get Condition Set · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `condition_set_id` (`string`, required): The UUID of the condition set object Use beehiiv_list_condition_sets to find IDs. Example: condition_set_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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`. Example input: `{"condition_set_id":"","publication_id":""}` ### `beehiiv_get_custom_field` Get Custom Field · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `custom_field_id` (`string`, required): The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"custom_field_id":"","publication_id":""}` ### `beehiiv_get_engagements` Get Publication Engagements · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The ID of the beehiiv publication this request applies to. Starts with pub_. Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `email_type` (`string`, optional): 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: `all`, `post`, `message`. - `granularity` (`string`, optional): The granularity at which to report the engagement metrics. Defaults to day if not provided. Allowed values: day, week, month. Example: day. One of: `day`, `week`, `month`. - `number_of_days` (`integer`, optional): 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_date` (`string`, optional): The starting date for the engagement metrics in YYYY-MM-DD format. Defaults to 1 day ago if not provided. Example: 2025-01-01. Example input: `{"publication_id":""}` ### `beehiiv_get_newsletter_list` Get Newsletter List · Read-only Get one newsletter list by id. Returns the list id, name, slug, description, status, subscriber count and email settings. Use beehiiv_list_newsletter_lists to find a list id. Requires a publication_id and a newsletter_list_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `newsletter_list_id` (`string`, required): The prefixed ID of the newsletter list object Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"newsletter_list_id":"","publication_id":""}` ### `beehiiv_get_poll` Get Poll · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `poll_id` (`string`, required): The prefixed ID of the poll object Use beehiiv_list_polls to find IDs. Example: poll_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `stats`, `poll_responses`, `trivia_answer`. Example input: `{"poll_id":"","publication_id":""}` ### `beehiiv_get_post` Get Post · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `post_id` (`string`, required): The prefixed ID of the post object Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `stats`, `free_web_content`, `free_email_content`, `free_rss_content`, `premium_web_content`, `premium_email_content`, `recipients`. - `premium_tiers` (`string`, optional): 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. Example input: `{"post_id":"","publication_id":""}` ### `beehiiv_get_post_aggregate_stats` Get Post Aggregate Stats · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `audience` (`string`, optional): Optionally filter the results by audience Allowed values: free, premium, all. Example: free. One of: `free`, `premium`, `all`. Default: `all`. - `authors` (`string`, optional): Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive). Example: Filtering for authors: ["John Doe","Jane Smith"] will return results of posts that have either John Doe or Jane Smith as authors. This tool sends a single value per call. Example: Jane Doe. - `content_tags` (`string`, optional): Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it. Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags. This tool sends a single value per call. Example: sales. - `hidden_from_feed` (`string`, optional): Optionally filter the results by the hidden_from_feed attribute of the post. all - Does not restrict results by hidden_from_feed. true - Only return posts hidden from the feed. false - Only return posts that are visible on the feed. Allowed values: all, true, false. Example: false. One of: `all`, `true`, `false`. Default: `all`. - `platform` (`string`, optional): Optionally filter the results by platform. web - Posts only published to web. email - Posts only published to email. both - Posts published to email and web. all - Does not restrict results by platform. Allowed values: web, email, both, all. Example: email. One of: `web`, `email`, `both`, `all`. Default: `all`. - `status` (`string`, optional): Optionally filter the results by the status of the post. draft - not been scheduled. confirmed - The post will be active after the scheduled_at. archived - The post is no longer active. all - Does not restrict results by status. Allowed values: draft, confirmed, archived, all. Example: active. One of: `draft`, `confirmed`, `archived`, `all`. Default: `all`. Example input: `{"publication_id":""}` ### `beehiiv_get_post_template` Get Post Template · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `post_template_id` (`string`, required): 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_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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_content`, `free_email_content`, `free_rss_content`, `premium_web_content`, `premium_email_content`. Example input: `{"post_template_id":"","publication_id":""}` ### `beehiiv_get_publication` Get Publication · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `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`. Example input: `{"publication_id":""}` ### `beehiiv_get_referral_program` Get Referral Program · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_get_segment` Get Segment · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `segment_id` (`string`, required): The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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`. Example input: `{"publication_id":"","segment_id":""}` ### `beehiiv_get_subscription_by_email` Get Subscription by Email · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `email` (`string`, required): The ID of the subscriber object. Example: reader@example.com. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `stats`, `custom_fields`, `referrals`, `tags`, `newsletter_lists`. Example input: `{"email":"","publication_id":""}` ### `beehiiv_get_subscription_by_id` Get Subscription by ID · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `subscription_id` (`string`, required): The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `stats`, `custom_fields`, `referrals`, `tags`, `newsletter_lists`. Example input: `{"publication_id":"","subscription_id":""}` ### `beehiiv_get_subscription_export` Get Subscription Export · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `export_id` (`string`, required): The prefixed ID of the Subscription Export object Use beehiiv_list_subscription_exports to find IDs. Example: export_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"export_id":"","publication_id":""}` ### `beehiiv_get_tier` Get Tier · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `tier_id` (`string`, required): The prefixed ID of the tier object Use beehiiv_list_tiers to find IDs. Example: tier_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): Optional list of expandable objects. stats - Returns statistics about the tier(s). prices - Returns prices for the tier(s). Example: stats. Example input: `{"publication_id":"","tier_id":""}` ### `beehiiv_identify_workspace` Identify Workspace · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `beehiiv_list_authors` List Authors · Read-only List the authors of a publication. Returns each author id, name, bio, image url and social links, plus pagination fields. Use beehiiv_get_author for one author. Use an author id with team_author_ids when creating a post. Use beehiiv_list_publications first to get the publication_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `limit` (`integer`, optional): 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. - `name` (`string`, optional): Optionally filter authors by full name or first name (case-insensitive). Example: Founders. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_automation_emails` List Automation Emails · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `automation_id` (`string`, required): The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): 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. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): Deprecated: Use cursor instead. Pagination returns the results in pages. Limited to 100 pages maximum. Example: 1. Example input: `{"automation_id":"","publication_id":""}` ### `beehiiv_list_automation_journeys` List Automation Journeys · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `automation_id` (`string`, required): The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). Example: 1. - `status` (`string`, optional): Optionally filter the results by the automation journey's status. Allowed values: in_progress, completed, exited_early, all. Example: active. One of: `in_progress`, `completed`, `exited_early`, `all`. Default: `all`. Example input: `{"automation_id":"","publication_id":""}` ### `beehiiv_list_automations` List Automations · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): Optional list of expandable objects. Allowed values: stats. Example: stats. One of: `stats`. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_condition_sets` List Condition Sets · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): 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. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. - `purpose` (`string`, optional): 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`. Example input: `{"publication_id":""}` ### `beehiiv_list_custom_fields` List Custom Fields · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"publication_id":""}` ### `beehiiv_list_newsletter_list_subscriptions` List Newsletter List Subscriptions · Read-only List the subscribers enrolled in a newsletter list. Returns each membership id, subscription id, status and subscribe and unsubscribe times, plus pagination fields. Use beehiiv_add_subscription_to_newsletter_list to enroll a subscriber. Requires a newsletter_list_id from beehiiv_list_newsletter_lists. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `newsletter_list_id` (`string`, required): The prefixed ID of the newsletter list object Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): 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. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"newsletter_list_id":"","publication_id":""}` ### `beehiiv_list_newsletter_lists` List Newsletter Lists · Read-only List the newsletter lists of a publication. Returns each list id, name, slug, status, subscriber count and email settings, plus pagination fields. Use beehiiv_get_newsletter_list for one list. Use beehiiv_list_publications first to get the publication_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_poll_responses` List Poll Responses · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `poll_id` (`string`, required): The prefixed ID of the poll object Use beehiiv_list_polls to find IDs. Example: poll_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): Cursor-based pagination (recommended): Use this opaque cursor token to fetch the next page of results. Example: eyJpZCI6MTIzfQ. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): 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`. - `limit` (`integer`, optional): 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_by` (`string`, optional): The field that the results are sorted by. Defaults to created. Allowed values: created. Example: created. One of: `created`. Default: `created`. - `page` (`integer`, optional): Offset-based pagination (deprecated): Page number for offset-based pagination. Example: 1. - `post_id` (`string`, optional): 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. Example input: `{"poll_id":"","publication_id":""}` ### `beehiiv_list_polls` List Polls · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): 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. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): 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: `stats`, `poll_responses`, `trivia_answer`. - `limit` (`integer`, optional): 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_by` (`string`, optional): 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: `created`, `name`. Default: `created`. - `page` (`integer`, optional): 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_id` (`string`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_post_templates` List Post Templates · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `limit` (`integer`, optional): 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` (`string`, optional): The direction of the request. Defaults to asc. Allowed values: asc, desc. Example: asc. One of: `asc`, `desc`. Default: `asc`. - `order_by` (`string`, optional): The field to order by. Defaults to created. Example: created. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_posts` List Posts · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `audience` (`string`, optional): Optionally filter the results by audience Allowed values: free, premium, all. Example: free. One of: `free`, `premium`, `all`. Default: `all`. - `authors` (`string`, optional): Optionally filter posts by their authors. Adding an author name will return any post with that author associated to it (case-insensitive). Example: Filtering for authors: ["John Doe","Jane Smith"] will return results of posts that have either John Doe or Jane Smith as authors. This tool sends a single value per call. Example: Jane Doe. - `content_tags` (`string`, optional): Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it. Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags. This tool sends a single value per call. Example: sales. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): 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: `stats`, `free_web_content`, `free_email_content`, `free_rss_content`, `premium_web_content`, `premium_email_content`, `recipients`. - `hidden_from_feed` (`string`, optional): Optionally filter the results by the hidden_from_feed attribute of the post. all - Does not restrict results by hidden_from_feed. true - Only return posts hidden from the feed. false - Only return posts that are visible on the feed. Allowed values: all, true, false. Example: false. One of: `all`, `true`, `false`. Default: `all`. - `limit` (`integer`, optional): 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_by` (`string`, optional): 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: `created`, `publish_date`, `displayed_date`. Default: `created`. - `page` (`integer`, optional): 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. - `platform` (`string`, optional): Optionally filter the results by platform. web - Posts only published to web. email - Posts only published to email. both - Posts published to email and web. all - Does not restrict results by platform. Allowed values: web, email, both, all. Example: email. One of: `web`, `email`, `both`, `all`. Default: `all`. - `premium_tiers` (`string`, optional): 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. - `slugs` (`string`, optional): 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. - `status` (`string`, optional): Optionally filter the results by the status of the post. draft - not been scheduled. confirmed - The post will be active after the scheduled_at. archived - The post is no longer active. all - Does not restrict results by status. Allowed values: draft, confirmed, archived, all. Example: active. One of: `draft`, `confirmed`, `archived`, `all`. Default: `all`. Example input: `{"publication_id":""}` ### `beehiiv_list_publications` List Publications · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): 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: `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`. - `limit` (`integer`, optional): 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_by` (`string`, optional): 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: `created`, `name`. Default: `created`. - `page` (`integer`, optional): 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. Example input: `{}` ### `beehiiv_list_segment_members` List Segment Subscribers · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `segment_id` (`string`, required): The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000. - `expand` (`string`, optional): 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: `stats`, `custom_fields`, `referrals`, `tags`, `subscription_premium_tiers`. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":"","segment_id":""}` ### `beehiiv_list_segment_subscriber_ids` List Segment Subscriber IDs · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `segment_id` (`string`, required): The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":"","segment_id":""}` ### `beehiiv_list_segments` List Segments · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): 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`. - `limit` (`integer`, optional): 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_by` (`string`, optional): 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: `created`, `last_calculated`. Default: `created`. - `page` (`integer`, optional): 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. - `status` (`string`, optional): Optionally filter the results by the segment's status. Allowed values: pending, processing, completed, failed, all. Example: active. One of: `pending`, `processing`, `completed`, `failed`, `all`. Default: `all`. - `type` (`string`, optional): Optionally filter the results by the segment's type. Allowed values: dynamic, static, manual, all. Example: dynamic. One of: `dynamic`, `static`, `manual`, `all`. Default: `all`. Example input: `{"publication_id":""}` ### `beehiiv_list_subscription_exports` List Subscription Exports · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `cursor` (`string`, optional): 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. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_list_subscriptions` List Subscriptions · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `creation_date` (`string`, optional): Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date. Example: 2025/01/15. - `cursor` (`string`, optional): 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. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `email` (`string`, optional): Optional email address to find a subscription. This param must be an exact match and is case insensitive. Example: reader@example.com. - `expand` (`string`, optional): 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: `stats`, `custom_fields`, `referrals`, `newsletter_lists`. - `limit` (`integer`, optional): 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_by` (`string`, optional): 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: `created`. Default: `created`. - `page` (`integer`, optional): 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_ids` (`string`, optional): Optionally filter the results by one or multiple premium tier ids. Example: premium_00000000-0000-0000-0000-000000000000. - `premium_tiers` (`string`, optional): Optionally filter the results by one or multiple premium tiers. Example: Gold. - `status` (`string`, optional): Optionally filter the results by a status Allowed values: validating, invalid, pending, active, inactive, all. Example: active. One of: `validating`, `invalid`, `pending`, `active`, `inactive`, `all`. Default: `all`. - `tier` (`string`, optional): Optionally filter the results by a their tier Allowed values: free, premium, all. Example: premium. One of: `free`, `premium`, `all`. Default: `all`. Example input: `{"publication_id":""}` ### `beehiiv_list_tiers` List Tiers · Read-only 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. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `direction` (`string`, optional): 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: `asc`, `desc`. Default: `asc`. - `expand` (`string`, optional): Optional list of expandable objects. stats - Returns statistics about the tier(s). prices - Returns prices for the tier(s). Example: stats. - `limit` (`integer`, optional): 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. - `page` (`integer`, optional): 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. Example input: `{"publication_id":""}` ### `beehiiv_add_subscription_tags` Add Subscription Tags · Write Add one or more tags to a subscriber. Returns the updated subscription. Use this to label subscribers for segmentation. Use beehiiv_update_subscription_by_id for other subscriber changes. Requires a subscription_id from beehiiv_list_subscriptions. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The ID of the beehiiv publication this request applies to. Starts with pub_. Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `subscription_id` (`string`, required): The ID of the subscription. Starts with sub_. Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. - `tags` (`array`, optional): Tags that can be used to group subscribers. Example: ["vip","customer"]. Example input: `{"publication_id":"","subscription_id":""}` ### `beehiiv_add_subscription_to_automation` Add Subscription to Automation · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `automation_id` (`string`, required): The prefixed ID of the automation object Use beehiiv_list_automations to find IDs. Example: aut_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `double_opt_override` (`string`, optional): 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. - `email` (`string`, optional): The email address associated with the subscription. Example: reader@example.com. - `subscription_id` (`string`, optional): The prefixed ID of the subscription. Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. Example input: `{"automation_id":"","publication_id":""}` ### `beehiiv_add_subscription_to_newsletter_list` Add Subscription to Newsletter List · Write Subscribe an existing subscriber to a newsletter list by subscription id or email. Returns the new list membership with its status and subscribe time. Use beehiiv_list_newsletter_list_subscriptions to see current members. Requires a newsletter_list_id from beehiiv_list_newsletter_lists. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `newsletter_list_id` (`string`, required): The prefixed ID of the newsletter list object Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `email` (`string`, optional): The email address of the subscription to subscribe. Either subscription_id or email must be provided. Example: reader@example.com. - `subscription_id` (`string`, optional): The prefixed ID of the subscription to subscribe. Either subscription_id or email must be provided. Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. Example input: `{"newsletter_list_id":"","publication_id":""}` ### `beehiiv_bulk_create_subscriptions` Bulk Create Subscriptions · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `subscriptions` (`array`, required): 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}]. Example input: `{"publication_id":"","subscriptions":[{"email":"a@example.com"},{"email":"b@example.com","send_welcome_email":true}]}` ### `beehiiv_create_custom_field` Create Custom Field · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `display` (`string`, required): Display name of the custom field as shown in beehiiv. Example: Company. - `kind` (`string`, required): The type of value being stored in the custom field. Allowed values: string, integer, boolean, date, datetime, list, double. Example: string. One of: `string`, `integer`, `boolean`, `date`, `datetime`, `list`, `double`. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"display":"","kind":"string","publication_id":""}` ### `beehiiv_create_newsletter_list` Create Newsletter List · Write Create a newsletter list with a name and optional description, slug and email settings. Returns the new list. Use beehiiv_update_newsletter_list to change a list later. Use beehiiv_list_publications first to get the publication_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): The name of the newsletter list. Example: Founders. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `auto_subscribe` (`boolean`, optional): Whether new subscribers are automatically subscribed to this list. Example: true. - `description` (`string`, optional): A description of the newsletter list. Example: Short description. - `email_settings` (`object`, optional): Email delivery settings as an object, such as email_subject_line, email_preview_text, from_address, sender_name and reply_to_address. Example: {"email_subject_line":"This week at Acme","email_preview_text":"Five things to read"}. - `headers` (`object`, optional): Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}. - `show_in_preference_center` (`boolean`, optional): Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Defaults to false. Example: true. - `slug` (`string`, optional): A unique slug for the newsletter list. Auto-generated from the name if not provided. Example: weekly-digest. - `utm_campaign` (`string`, optional): The utm_campaign appended to links in posts sent to this list. Example: launch. - `utm_medium` (`string`, optional): The utm_medium appended to links in posts sent to this list. Example: social. - `utm_params_enabled` (`boolean`, optional): Whether UTM parameters are appended to links in posts sent to this list. Omit to inherit from the publication. Example: true. - `utm_source` (`string`, optional): The utm_source appended to links in posts sent to this list. Example: twitter. Example input: `{"name":"","publication_id":""}` ### `beehiiv_create_post` Create Post · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `title` (`string`, required): The title of the post. Example: Weekly Digest. - `blocks` (`array`, optional): Advanced structured content as an array of block objects, each with a type and its content. Prefer body_content (HTML) unless you need block-level control. Example: [{"type":"paragraph","plaintext":"Hello"}]. - `body_content` (`string`, optional): The content of the post as a single raw HTML string. The HTML is wrapped in an htmlSnippet block internally. Note that and tags are removed during sanitization — use inline styles for all visual styling. Either this field OR the blocks field must be provided. Example:

Hello

Welcome to this week's issue. . - `content_tags` (`array`, optional): The content tags to use for this post. If not provided, the default value will be used. Example: ["sales"]. - `custom_fields` (`object`, optional): Custom field values as an object of field name to value. Example: {"Company":"Acme"}. - `custom_link_tracking_enabled` (`boolean`, optional): If true, custom link tracking will be enabled for this post. If not provided, the default value will be used. Example: true. - `email_capture_type_override` (`string`, optional): The email capture type to use for this post. If not provided, the default value will be used. Allowed values: none, gated, popup. Example: popup. One of: `none`, `gated`, `popup`. - `email_settings` (`object`, optional): Email delivery settings as an object, such as email_subject_line, email_preview_text, from_address, sender_name and reply_to_address. Example: {"email_subject_line":"This week at Acme","email_preview_text":"Five things to read"}. - `guest_author_ids` (`array`, optional): The prefixed IDs of the guest authors to associate with this post. Guest authors must belong to the publication. Obtain IDs from the List Authors endpoint. When provided, replaces all existing guest authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"]. - `headers` (`object`, optional): Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}. - `newsletter_list_id` (`string`, optional): The prefixed ID of the newsletter list to associate with this post. When provided, the post will only be sent to subscribers of this list. Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `override_scheduled_at` (`string`, optional): If you wish to display a date other than the scheduled_at date in the email, you can provide a date here. This will not affect the actual publish date of the post. Example: 2025-06-01T09:00:00Z. - `post_template_id` (`string`, optional): The ID of the template to use for the post. If not provided, the default template will be used. Use beehiiv_list_post_templates to find IDs. Example: post_template_00000000-0000-0000-0000-000000000000. - `recipients` (`object`, optional): Audience targeting for the post, given as an object with a web section and an email section, each listing the tiers that can receive the post. Example: {"web":{"tiers":["free","premium"]},"email":{"tiers":["free"]}}. - `scheduled_at` (`string`, optional): The time in which the post will be published. If not provided, the post will be published immediately unless status is set to draft. A draft post cannot be scheduled. Example: 2025-06-01T09:00:00Z. - `seo_settings` (`object`, optional): Search and social metadata as an object, such as default_title, default_description, og_title, og_description, twitter_title and twitter_description. Example: {"default_title":"Weekly Digest","default_description":"Our best reads"}. - `social_share` (`string`, optional): The social share type to use for this post. If not provided, the default value will be used. Allowed values: comments_and_likes_only, with_comments_and_likes, top, none. Example: top. One of: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`. - `status` (`string`, optional): The status of the post. If not provided, the default (draft) value will be used and the post will not be scheduled or published. Explicitly pass confirmed to have the post publish immediately (if no scheduled_at is provided) or at the scheduled_at time. Allowed values: draft, confirmed. Example: active. One of: `draft`, `confirmed`. - `subtitle` (`string`, optional): The subtitle of the post. Example: What happened this week. - `team_author_ids` (`array`, optional): The prefixed IDs of the team members to associate with this post as authors. Team authors must have access to the publication. Note the List Authors endpoint only returns team members who already have a byline on a published post in this publication, so it will not surface IDs for a team member's first assignment. When provided, replaces all existing team authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"]. - `thumbnail_image_url` (`string`, optional): The URL of the thumbnail image to use for the post. If not provided, the default value will be used. Example: https://example.com/cover.jpg. - `utm_campaign` (`string`, optional): The utm_campaign appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: launch. - `utm_medium` (`string`, optional): The utm_medium appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: social. - `utm_params_enabled` (`boolean`, optional): Whether UTM parameters are appended to links in this post. Omit to inherit from the newsletter list, then the publication. Example: true. - `utm_source` (`string`, optional): The utm_source appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: twitter. - `web_settings` (`object`, optional): Web page settings as an object, such as slug, hide_from_feed, display_title_on_web, display_subtitle_on_web and display_thumbnail_on_web. Example: {"slug":"weekly-digest","hide_from_feed":false}. Example input: `{"publication_id":"","title":""}` ### `beehiiv_create_subscription` Create Subscription · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `email` (`string`, required): The email address of the subscription. Example: reader@example.com. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `automation_ids` (`array`, optional): 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_id` (`string`, optional): The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication. Example: comp_00000000-0000-0000-0000-000000000000. - `custom_fields` (`array`, optional): Custom field 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_override` (`string`, optional): 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_ids` (`array`, optional): 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_ids` (`array`, optional): An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with premium_tiers to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["premium_00000000-0000-0000-0000-000000000000"]. - `premium_tiers` (`array`, optional): An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with premium_tier_ids to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["Gold"]. - `reactivate_existing` (`boolean`, optional): 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_code` (`string`, optional): This should be a subscribers referral_code. This gives referral credit for the new subscription. Example: ABC123. - `referring_site` (`string`, optional): The website that the subscriber was referred from. Example: https://example.com. - `send_welcome_email` (`boolean`, optional): Whether to send the publication welcome email to the new subscriber. Example: true. - `skip_newsletter_list_auto_subscribe` (`boolean`, optional): When true, the subscriber will not be auto-subscribed to newsletter lists configured with auto-subscribe. Defaults to false. Example: true. - `stripe_customer_id` (`string`, optional): The Stripe customer ID for this subscription. Example: cus_123456789. - `tier` (`string`, optional): The tier for this subscription. Allowed values: free, premium. Example: premium. One of: `free`, `premium`. - `utm_campaign` (`string`, optional): The acquisition campaign of the subscription. Example: launch. - `utm_content` (`string`, optional): The acquisition content; typically used for A/B testing or ad variations. Example: cta. - `utm_medium` (`string`, optional): The medium of the subscription. Example: social. - `utm_source` (`string`, optional): The source of the subscription. Example: twitter. - `utm_term` (`string`, optional): The acquisition term; typically the keyword or search term. Example: newsletter. Example input: `{"email":"<email>","publication_id":"<publication_id>"}` ### `beehiiv_create_subscription_export` Create Subscription Export · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `variant` (`string`, required): Which column set the export uses Allowed values: full, basic. Example: full. One of: `full`, `basic`. - `segment_id` (`string`, optional): 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. Example input: `{"publication_id":"<publication_id>","variant":"full"}` ### `beehiiv_create_tier` Create Tier · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): Name. Example: Founders. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `description` (`string`, optional): Description text. Example: Short description. - `prices_attributes` (`array`, optional): 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"}]. Example input: `{"name":"<name>","publication_id":"<publication_id>"}` ### `beehiiv_recalculate_segment` Recalculate Segment · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `segment_id` (`string`, required): The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000. Example input: `{"publication_id":"<publication_id>","segment_id":"<segment_id>"}` ### `beehiiv_update_custom_field` Update Custom Field · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `custom_field_id` (`string`, required): The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `display` (`string`, optional): Display name of the custom field as shown in beehiiv. Example: Company. Example input: `{"custom_field_id":"<custom_field_id>","publication_id":"<publication_id>"}` ### `beehiiv_update_newsletter_list` Update Newsletter List · Write Update a newsletter list name, description, status or email settings. Returns the updated list. Use beehiiv_create_newsletter_list for a new list. Set status to archived to retire a list without deleting it. Requires a newsletter_list_id from beehiiv_list_newsletter_lists. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `newsletter_list_id` (`string`, required): The prefixed ID of the newsletter list object Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `auto_subscribe` (`boolean`, optional): Whether new subscribers are automatically subscribed to this list. Example: true. - `description` (`string`, optional): A description of the newsletter list. Example: Short description. - `email_settings` (`object`, optional): Email delivery settings as an object, such as email_subject_line, email_preview_text, from_address, sender_name and reply_to_address. Example: {"email_subject_line":"This week at Acme","email_preview_text":"Five things to read"}. - `headers` (`object`, optional): Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}. - `name` (`string`, optional): The name of the newsletter list. Example: Founders. - `show_in_preference_center` (`boolean`, optional): Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Archived lists cannot be shown; archiving a list hides it. Example: true. - `slug` (`string`, optional): A unique slug for the newsletter list. Example: weekly-digest. - `status` (`string`, optional): The status of the newsletter list. Valid values are active and archived. Setting draft is not permitted. Allowed values: active, archived. Example: active. One of: `active`, `archived`. - `utm_campaign` (`string`, optional): The utm_campaign appended to links in posts sent to this list. Example: launch. - `utm_medium` (`string`, optional): The utm_medium appended to links in posts sent to this list. Example: social. - `utm_params_enabled` (`boolean`, optional): Whether UTM parameters are appended to links in posts sent to this list. When left unset on the list, falls back to the publication. Example: true. - `utm_source` (`string`, optional): The utm_source appended to links in posts sent to this list. Example: twitter. Example input: `{"newsletter_list_id":"<newsletter_list_id>","publication_id":"<publication_id>"}` ### `beehiiv_update_post` Update Post · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `post_id` (`string`, required): The prefixed ID of the post to update Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `blocks` (`array`, optional): Advanced structured content as an array of block objects, each with a type and its content. Prefer body_content (HTML) unless you need block-level control. Example: [{"type":"paragraph","plaintext":"Hello"}]. - `body_content` (`string`, optional): 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>Welcome to this week's issue. . - `content_merge_strategy` (`string`, optional): 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: `replace`, `append_to_template`, `append`, `prepend`. - `content_tags` (`array`, optional): The content tags for this post. When provided, this replaces all existing content tags on the post. Example: ["sales"]. - `custom_link_tracking_enabled` (`boolean`, optional): If true, custom link tracking will be enabled for this post. Example: true. - `email_capture_type_override` (`string`, optional): The email capture type to use for this post. Allowed values: none, gated, popup. Example: popup. One of: `none`, `gated`, `popup`. - `email_settings` (`object`, optional): Email delivery settings as an object, such as email_subject_line, email_preview_text, from_address, sender_name and reply_to_address. Example: {"email_subject_line":"This week at Acme","email_preview_text":"Five things to read"}. - `guest_author_ids` (`array`, optional): The prefixed IDs of the guest authors to associate with this post. Guest authors must belong to the publication. When provided, replaces all existing guest authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"]. - `headers` (`object`, optional): Custom email headers as an object of header name to value. Example: {"X-Campaign":"spring"}. - `newsletter_list_id` (`string`, optional): The prefixed ID of the newsletter list to associate with this post. When provided, 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_at` (`string`, optional): 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. - `recipients` (`object`, optional): Audience targeting for the post, given as an object with a web section and an email section, each listing the tiers that can receive the post. Example: {"web":{"tiers":["free","premium"]},"email":{"tiers":["free"]}}. - `scheduled_at` (`string`, optional): The time at which the post will be published. Cannot be updated after the post has already been sent. Example: 2025-06-01T09:00:00Z. - `seo_settings` (`object`, optional): Search and social metadata as an object, such as default_title, default_description, og_title, og_description, twitter_title and twitter_description. Example: {"default_title":"Weekly Digest","default_description":"Our best reads"}. - `social_share` (`string`, optional): The social share type to use for this post. Allowed values: comments_and_likes_only, with_comments_and_likes, top, none. Example: top. One of: `comments_and_likes_only`, `with_comments_and_likes`, `top`, `none`. - `status` (`string`, optional): 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: `draft`, `confirmed`. - `subtitle` (`string`, optional): The subtitle of the post. Example: What happened this week. - `team_author_ids` (`array`, optional): The prefixed IDs of the team members to associate with this post as authors. Team authors must have access to the publication. When provided, replaces all existing team authors on the post. Example: ["author_00000000-0000-0000-0000-000000000000"]. - `thumbnail_image_url` (`string`, optional): The URL of the thumbnail image to use for the post. Example: https://example.com/cover.jpg. - `title` (`string`, optional): The title of the post. Example: Weekly Digest. - `utm_campaign` (`string`, optional): The utm_campaign appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: launch. - `utm_medium` (`string`, optional): The utm_medium appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: social. - `utm_params_enabled` (`boolean`, optional): Whether UTM parameters are appended to links in this post. When left unset on the post, falls back to the newsletter list, then the publication. Example: true. - `utm_source` (`string`, optional): The utm_source appended to links in this post. Falls back to the newsletter list, then the publication, then a generated default. Example: twitter. - `web_settings` (`object`, optional): Web page settings as an object, such as slug, hide_from_feed, display_title_on_web, display_subtitle_on_web and display_thumbnail_on_web. Example: {"slug":"weekly-digest","hide_from_feed":false}. Example input: `{"post_id":"<post_id>","publication_id":"<publication_id>"}` ### `beehiiv_update_subscription_by_email` Update Subscription by Email · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `email` (`string`, required): The new email address for the subscription. Example: reader@example.com. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `complimentary_gift_id` (`string`, optional): The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication. Example: comp_00000000-0000-0000-0000-000000000000. - `custom_fields` (`array`, optional): Custom field changes as an array of objects with a name and a value; add "delete": true to clear a field. Example: [{"name":"Company","value":"Acme"}]. - `newsletter_list_ids` (`array`, optional): An array of newsletter list prefixed IDs to subscribe this subscription to. Adds to the subscription's existing list memberships; it does not replace them. The newsletter lists must belong to the same publication. Cannot be combined with unsubscribe. Example: ["list_00000000-0000-0000-0000-000000000000"]. - `premium_tier_ids` (`array`, optional): An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with premium_tiers to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["premium_00000000-0000-0000-0000-000000000000"]. - `premium_tiers` (`array`, optional): An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with premium_tier_ids to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["Gold"]. - `stripe_customer_id` (`string`, optional): The Stripe Customer ID of the subscription (not required). Example: cus_123456789. - `tier` (`string`, optional): Optional parameter to set the tier for this subscription. Allowed values: free, premium. Example: premium. One of: `free`, `premium`. - `unsubscribe` (`boolean`, optional): A boolean value specifying whether to unsubscribe this subscription from the publication (not required). Example: false. - `unsubscribe_newsletter_list_ids` (`array`, optional): An array of newsletter list prefixed IDs to unsubscribe this subscription from. Unsubscribing from a list the subscription is not on is a no-op. The newsletter lists must belong to the same publication, and the same list cannot appear in newsletter_list_ids. Example: ["list_00000000-0000-0000-0000-000000000000"]. Example input: `{"email":"<email>","publication_id":"<publication_id>"}` ### `beehiiv_update_subscription_by_id` Update Subscription by ID · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `subscription_id` (`string`, required): The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. - `complimentary_gift_id` (`string`, optional): The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication. Example: comp_00000000-0000-0000-0000-000000000000. - `custom_fields` (`array`, optional): Custom field changes as an array of objects with a name and a value; add "delete": true to clear a field. Example: [{"name":"Company","value":"Acme"}]. - `email` (`string`, optional): The new email address for the subscription. Example: reader@example.com. - `newsletter_list_ids` (`array`, optional): An array of newsletter list prefixed IDs to subscribe this subscription to. Adds to the subscription's existing list memberships; it does not replace them. The newsletter lists must belong to the same publication. Cannot be combined with unsubscribe. Example: ["list_00000000-0000-0000-0000-000000000000"]. - `premium_tier_ids` (`array`, optional): An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with premium_tiers to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["premium_00000000-0000-0000-0000-000000000000"]. - `premium_tiers` (`array`, optional): An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with premium_tier_ids to include tiers from both (duplicates are removed). Takes precedence over the tier parameter. Example: ["Gold"]. - `stripe_customer_id` (`string`, optional): The Stripe Customer ID of the subscription (not required). Example: cus_123456789. - `tier` (`string`, optional): Optional parameter to set the tier for this subscription. Allowed values: free, premium. Example: premium. One of: `free`, `premium`. - `unsubscribe` (`boolean`, optional): A boolean value specifying whether to unsubscribe this subscription from the publication (not required). Example: false. - `unsubscribe_newsletter_list_ids` (`array`, optional): An array of newsletter list prefixed IDs to unsubscribe this subscription from. Unsubscribing from a list the subscription is not on is a no-op. The newsletter lists must belong to the same publication, and the same list cannot appear in newsletter_list_ids. Example: ["list_00000000-0000-0000-0000-000000000000"]. Example input: `{"publication_id":"<publication_id>","subscription_id":"<subscription_id>"}` ### `beehiiv_update_tier` Update Tier · Write 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. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `tier_id` (`string`, required): The prefixed ID of the tier object Use beehiiv_list_tiers to find IDs. Example: tier_00000000-0000-0000-0000-000000000000. - `description` (`string`, optional): Description text. Example: Short description. - `name` (`string`, optional): Name. Example: Founders. - `prices_attributes` (`array`, optional): 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"}]. Example input: `{"publication_id":"<publication_id>","tier_id":"<tier_id>"}` ### `beehiiv_delete_custom_field` Delete Custom Field · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `custom_field_id` (`string`, required): The ID of the Custom Fields object Use beehiiv_list_custom_fields to find IDs. Example: custom_field_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"custom_field_id":"<custom_field_id>","publication_id":"<publication_id>"}` ### `beehiiv_delete_newsletter_list` Delete Newsletter List · Destructive Delete a newsletter list by id. Returns an empty success response. Use beehiiv_update_newsletter_list with status archived to keep the list. Deleting cannot be undone. Requires a newsletter_list_id from beehiiv_list_newsletter_lists. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `newsletter_list_id` (`string`, required): The prefixed ID of the newsletter list object Use beehiiv_list_newsletter_lists to find IDs. Example: list_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"newsletter_list_id":"<newsletter_list_id>","publication_id":"<publication_id>"}` ### `beehiiv_delete_post` Delete Post · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `post_id` (`string`, required): The prefixed ID of the post object Use beehiiv_list_posts to find IDs. Example: post_00000000-0000-0000-0000-000000000000. - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. Example input: `{"post_id":"<post_id>","publication_id":"<publication_id>"}` ### `beehiiv_delete_segment` Delete Segment · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `segment_id` (`string`, required): The prefixed ID of the segment object Use beehiiv_list_segments to find IDs. Example: seg_00000000-0000-0000-0000-000000000000. Example input: `{"publication_id":"<publication_id>","segment_id":"<segment_id>"}` ### `beehiiv_delete_subscription` Delete Subscription · Destructive 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. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `publication_id` (`string`, required): The prefixed ID of the publication object Use beehiiv_list_publications to find IDs. Example: pub_00000000-0000-0000-0000-000000000000. - `subscription_id` (`string`, required): The prefixed ID of the subscription object Use beehiiv_list_subscriptions to find IDs. Example: sub_00000000-0000-0000-0000-000000000000. Example input: `{"publication_id":"<publication_id>","subscription_id":"<subscription_id>"}` ## Related Other Communication connectors ([all 73](/agentkit/connectors/?category=communication)): - [Crisp](/agentkit/connectors/crisp/): Scalekit connector, API key, 50 tools - [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools - [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |