Beehiiv MCP Server & CLI

Beehiiv MCP server and CLI for Claude Code, Codex and AI agents. 117 tools: 70 reads and 47 confirmed writes for publications, newsletters, subscriptions, automations, analytics, polls, referral programs, tiers, podcast feeds and webhooks.

One package gives you two ways in: beehiiv-mcp connects the tools to your AI app, and beehiiv-cli makes the same tools shell commands. Claude Desktop also has a bundled .mcpb extension.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Complete installation and private account setup are in INSTALL.md.

The terminal illustrates shipped tools and the draft workflow. It is a presentation preview, not a live account send.

You need a private Beehiiv API key or your own authorized OAuth integration. Endpoint plan/scope permissions apply; Send API creation requires eligible Pro/Enterprise access. The community wrapper preserves AGPL-3.0-or-later licensing; Beehiiv service charges remain separate. This is not a Beehiiv-endorsed product.

Beehiiv already has an official account MCP and a separate documentation MCP. A community task CLI also exists. The comparison below records their scopes; this package claims no broader coverage, and section 7 has its measured token costs.

Two ways to use it

Command line

npm install -g @thenavidm/beehiiv-mcp-cli@latest
beehiiv-cli
beehiiv-cli list-publications --help
beehiiv-cli schema create-post
beehiiv-cli list-publications --limit 5 --agent

Configure credentials privately first. Every write requires --confirm; --agent and --yes never authorize account changes.

MCP server, for your AI app

claude mcp add --scope user beehiiv -- npx -y @thenavidm/beehiiv-mcp-cli@latest

Then ask: "Show the publications I can access. Read the latest posts in the publication I choose." Full client/OS configuration is in INSTALL.md.

Which one

| Where you work | What to use | | --- | --- | | Claude Code, Codex, Cursor or another shell agent | MCP, CLI or both | | Claude Desktop chat | Local MCP or the desktop bundle | | Scripts/CI | CLI, or an MCP client | | Web clients that accept only remote MCP URLs | Official hosted Beehiiv MCP |

Features

| Capability | CLI command | MCP tool | | --- | --- | --- | | Allowed publications | beehiiv-cli list-publications | list_publications | | Newsletter posts | beehiiv-cli list-posts / get-post | list_posts / get_post | | Draft and update | beehiiv-cli create-post / update-post | create_post / update_post | | Subscriptions | beehiiv-cli list-subscriptions / create-subscription | list_subscriptions / create_subscription | | Automations | beehiiv-cli list-automations | list_automations | | Webhooks | beehiiv-cli create-webhook | create_webhook | | Private accounts | beehiiv-cli list-accounts | list_accounts | | Setup diagnosis | beehiiv-cli doctor | CLI utility |

Contents

| Number | Section | What it covers | | --- | --- | --- | | 1 | What you can ask it | Practical prompts and coverage | | 2 | Quick install | MCP, CLI and desktop | | 3 | Set up Beehiiv access | Credentials, OAuth and eligibility | | 4 | Connect your client | Clients and OS routes | | 5 | Check it works | Doctor and first read | | 6 | Output, flags and exit codes | Scripts, JSON and stable exit codes | | 7 | MCP or CLI and token cost | Measured in Claude Code and Codex, and how to spend less | | 8 | Every tool and argument | All 117 tools and arguments | | 9 | Newsletter and subscription workflows | Drafts, sending and audience work | | 10 | Pagination, exports and webhooks | Cursor/offset pagination and callbacks | | 11 | Several private accounts | Accounts versus publications | | 12 | Writing safely | Confirmation, read-only and retries | | 13 | How it works | Shared handlers and releases | | 14 | Your data | Hosts, private data and local files | | 15 | Environment variables | Credentials, safety and tuning | | 16 | Updates and removal | Updates and disconnecting | | 17 | Troubleshooting | Symptoms and remedies | | 18 | API coverage and comparisons | Official and community alternatives | | 19 | Versions | Versions and legacy migration | | 20 | FAQ | Accordion questions |

1. What you can ask it

• Show publications this credential can access.
• Summarize the latest five posts and their statistics.
• Find this subscriber in the intended publication.
• Draft the newsletter I requested and leave it unscheduled.
• Read the current subscriber list before the audience change I requested.
• Inspect referral rewards, segments, automations or private podcast subscriptions.

The snapshot contains 116 operations plus the local account helper: 117 tools, 70 reads and 47 confirmed writes. Areas include publications, posts, subscriptions, automations, custom fields, segments, polls, referral programs, tiers, webhooks, ad offers, analytics, newsletter lists, exports and privacy requests. Plan and OAuth scope requirements apply to each operation.

Checked: build/typecheck, 31 tests and real local discovery. Live account sends and desktop GUI installation remain unverified; section 7 has the measured token costs. API coverage does not imply full Beehiiv UI or official MCP feature parity.

2. Quick install

npm install -g @thenavidm/beehiiv-mcp-cli@latest
beehiiv-cli --version
beehiiv-cli
beehiiv-cli list-publications --help
beehiiv-cli schema create-post
beehiiv-cli login

Node 22 or newer is required for CLI/manual MCP installation. Discovery works before authentication. login explains private setup; it does not open a browser or save credentials. Download the desktop .mcpb from GitHub Releases. Full client/OS instructions are in INSTALL.md.

3. Set up Beehiiv access

API key for personal automation

1. Sign in to Beehiiv.
2. Open Settings > API under Workspace Settings.
3. Choose Create New API Key. Name the integration and restrict its publications where appropriate.
4. Save the newly shown key in private local settings. It cannot be viewed again after leaving the page.
5. Set BEEHIIV_API_KEY in the process/client that launches the package, then run doctor and a read.

Use the current key instructions. Keys use Bearer authentication. Requests to publications outside a restricted key's scope return 404, and workspace-wide data deletion returns 403. A password is not an API key. The package does not load .env files automatically. GUI clients may not inherit a terminal environment.

Your own OAuth integration

Register a client through Beehiiv support. Use your own client ID, exact registered callback, a verified random state and PKCE for public clients. Authorization uses https://app.beehiiv.com/oauth/authorize; exchange/refresh uses https://app.beehiiv.com/oauth/token with application/x-www-form-urlencoded. Confidential clients also supply their private client secret.

Request only the documented scopes needed by the user. The default identify:read scope does not authorize all account reads/writes. The tool catalog records upstream endpoint scope labels. The test-send endpoint is labeled only posts upstream; confirm its required granted action through current Beehiiv permissions rather than treating that label as an OAuth scope to request. identify_oauth_user requires an OAuth session. This package does not provide a hosted callback, borrow another CLI's OAuth app or implement the initial browser consent flow.

Save the authorized token response and your app settings to a private regular JSON file outside the repo:

{"access_token":"YOUR_ACCESS_TOKEN","refresh_token":"YOUR_REFRESH_TOKEN","client_id":"YOUR_OWN_APP_ID","client_secret":"YOUR_CONFIDENTIAL_APP_SECRET"}

Omit client_secret for a public client. Include the real issued created_at/expires_in metadata when available. Set BEEHIIV_TOKENS_FILE to the absolute path. Files must be regular, at most 64 KB; symlinks are refused. Protect POSIX files with mode 0600 and Windows folders with user-only ACLs. Refresh updates files atomically. Without a file, environment-based refreshed state lasts only in that process. OAuth access tokens take precedence over an API key.

Rate limits and disconnecting

Current API limits are Free 30, Lite 180, Pro 500 and Enterprise 800 requests/minute. The wrapper defaults to conservative 2,000 ms pacing per account. Configure a supported interval when your plan and shared credential traffic justify it. Other processes also count; a response header after an idle period alone is not a complete plan eligibility check.

Revoke the API key or authorized app in Beehiiv, remove private client settings and reconnect. Uninstalling the package does not revoke credentials, delete remote subscribers or unschedule posts.

4. Connect your client

The full commands and private configurations are in INSTALL.md. Common registrations, after privately configuring account credentials:

claude mcp add --scope user beehiiv -- npx -y @thenavidm/beehiiv-mcp-cli@latest
claude mcp list
codex mcp add beehiiv -- npx -y @thenavidm/beehiiv-mcp-cli@latest
codex mcp list

Claude Desktop can install the .mcpb release or use manual JSON. Cursor, Windsurf and Gemini CLI use their user MCP settings; VS Code supports secure prompted inputs; Zed uses context_servers. Local Cline/Roo-style clients accept the same stdio command through their MCP setup UI. A local stdio process is not a public HTTP connector for ChatGPT on the web. Beehiiv's official hosted MCP at https://mcp.beehiiv.com/mcp is the appropriate remote option there.

Desktop settings accept a sensitive API key or a private OAuth token-file path. OAuth integrations require the documented scopes and identify_oauth_user requires OAuth. Custom extension availability depends on your installed host and organization policy.

Let an agent guide setup

Help me install Beehiiv MCP Server & CLI using INSTALL.md. Check Node and the binary, let me configure my account credentials privately, then run discovery and doctor --network. Do not send email or change subscribers during setup.

For shell agents, make SKILL.md available through the client's supported skills location. npm installation does not register the skill automatically.

5. Check it works

beehiiv-cli --version
beehiiv-cli doctor
beehiiv-cli doctor --network
beehiiv-cli list-publications --limit 1 --agent
beehiiv-cli list-accounts --agent

The local doctor checks configuration. The network doctor reads allowed publications without returning private account content. It does not send email, reactivate a subscription or change an account. An empty permitted publication list can be valid. A successful read does not establish every endpoint's plan or scope permissions. Read-only discovery exposes 70 tools.

6. Output, flags and exit codes

Tool names become dashed commands: get_post becomes beehiiv-cli get-post. Both exact underscore tool names and dashed forms are accepted. Argument names have dashed aliases: post_id is --post-id. Use help and schema to discover each operation's current input.

beehiiv-cli tools
beehiiv-cli get-post --help
beehiiv-cli schema get-post
beehiiv-cli get-post --publication-id pub_00000000-0000-0000-0000-000000000000 --post-id post_00000000-0000-0000-0000-000000000000 --agent

| Flag | Behavior | | --- | --- | | --help | Current schema-derived arguments and defaults | | --json | Structured JSON output | | --compact | Compact JSON on one line | | --agent | Compact JSON and no prompts; never confirms a write | | --select a,b.c | Keep selected fields; dotted paths descend through objects and arrays | | --no-color | No terminal colors | | --no-input | No interactive prompts | | --yes | House noninteractive flag; never substitutes for --confirm | | --confirm | Explicit confirmation for the requested guarded operation | | --account NAME | Select a configured local account on API tools | | --payload JSON | Complete request body as one JSON object | | --payload-file PATH | Complete request body from a local regular JSON file, at most 5 MB |

Body flags and payload/payload_file are mutually exclusive. Path and query flags remain separate. Objects take JSON; array flags repeat once per array item. Do not pass an array to a flag that expects a single item:

beehiiv-cli list-subscriptions --publication-id pub_00000000-0000-0000-0000-000000000000 --limit 10 --agent
beehiiv-cli create-post --publication-id pub_00000000-0000-0000-0000-000000000000 --payload-file /absolute/private/path/newsletter.json --confirm --agent

Null and complete bodies

Use an actual JSON null in payload for nullable values. A shell --field null is a string. For example, a headers object can use null values to suppress inherited headers, per reviewed upstream prose. Discover the complete schema before editing nested fields.

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Unexpected error | | 2 | Invalid arguments or refused write, an unknown command or a hidden write | | 3 | Resource not found | | 4 | Authentication or permission failure | | 5 | Other API/transport failure | | 7 | Rate limited | | 10 | Missing or invalid private configuration |

Results go to stdout; errors are JSON on stderr. --select controls local result rendering, not the original API response. Arrays of objects use repeated JSON-item flags; payload/payload_file is easier for a complex post block tree.

7. MCP or CLI and token cost

Both surfaces are the same program with the same 117 tools. The difference is when the model pays for them. Measured in Claude Code:

| Cost | MCP server | CLI | |---|---|---| | Every message, with every tool loaded | 138,000 tokens | nothing | | Every message, Claude Code's default | 2,000 tokens | nothing | | When Beehiiv comes up | nothing more, or the tools it picks | 1,400 tokens for SKILL.md, once |

Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, and most of it is the four post tools: a post body can hold 33 kinds of block, each written once under $defs, about 40 KB per tool.

To spend less, BEEHIIV_READ_ONLY=1 leaves the 70 reads, and --select keeps only the fields you name from a result. Or install the CLI and add the server on the days it earns its place.

Measured on 2026-10-05 with Claude Code 2.1.286 on Claude Opus 5.5: one short prompt with and without the server connected, once with ENABLE_TOOL_SEARCH=false and once with the default, the difference read from the API's own usage figures. SKILL.md was measured the same way. Other apps and models count tokens a little differently.

Against 2.0.1, measured the same day: every tool loaded costs 138,012 tokens instead of 655,428, because 2.0.1 spelled each block's parts out wherever they appeared, twice per post tool, and 3.0.0 writes each repeated part once. Tool search is the same within 2 tokens (2,011 against 2,010), and SKILL.md costs 60 more, because it now says how approval works over MCP and lists every exit code. In Codex 0.159.3 on gpt-6.1-sol, the same task, "find the command that creates a draft post, and the flags it requires", read a median of 84,440 input tokens on 3.0.0 against 86,352 on 2.0.1 over the CLI, five runs each: every 3.0.0 run asked which (208 characters) where 2.0.1's read the full command list (9,966). Two 2.0.1 runs stopped on a provider capacity error, so the CLI medians use pairs 1, 4, 5, 6 and 7. Over MCP, Codex prints its own TypeScript rendering of the tool list and cuts it to about 10,000 tokens. That rendering is 907 tokens longer on 3.0.0, 61,486 against 60,579: in the part Codex kept, 2.0.1's reads unknown six times, for lists of segment and tier IDs nested four levels deep in the post tools, and 3.0.0's spells every type out. The input totals carry that difference, a median of 77,584 against 77,354.

8. Every tool and argument

The following tools and argument tables come from actual MCP discovery. API paths and OAuth scopes come from the pinned official snapshot. OAuth scopes apply to OAuth integrations; API keys instead use workspace/publication permissions. Body requirements are enforced at execution even when the complete body is supplied through payload.

| Tool | API | Mode | OAuth scope | | --- | --- | --- | --- | | list_ad_network_offers | GET /v2/publications/{publicationId}/ad_network/offers | Read | posts:read | | create_ad_network_offer | POST /v2/publications/{publicationId}/ad_network/offers | Write, confirms | posts:write | | ad_network_offers_advertisements | GET /v2/publications/{publicationId}/ad_network/offers/{offerId}/advertisements | Read | posts:read | | list_ad_network_reports | GET /v2/publications/{publicationId}/ad_network/reports | Read | posts:read | | ad_network_reports_summary | GET /v2/publications/{publicationId}/ad_network/reports/summaries | Read | posts:read | | ad_network_reports_account_summary | GET /v2/ad_network/reports/summaries | Read | posts:read | | list_advertisement_opportunities | GET /v2/publications/{publicationId}/advertisement_opportunities | Read | posts:read | | list_authors | GET /v2/publications/{publicationId}/authors | Read | Account permissions | | get_author | GET /v2/publications/{publicationId}/authors/{authorId} | Read | Account permissions | | add_subscriber_to_automation | POST /v2/publications/{publicationId}/automations/{automationId}/journeys | Write, confirms | automations:write | | list_automation_journeys | GET /v2/publications/{publicationId}/automations/{automationId}/journeys | Read | automations:read | | get_automation_journey | GET /v2/publications/{publicationId}/automations/{automationId}/journeys/{automationJourneyId} | Read | automations:read | | list_automations | GET /v2/publications/{publicationId}/automations | Read | automations:read | | get_automation | GET /v2/publications/{publicationId}/automations/{automationId} | Read | automations:read | | automations_list_emails | GET /v2/publications/{publicationId}/automations/{automationId}/emails | Read | Account permissions | | create_bulk_subscription | POST /v2/publications/{publicationId}/bulk_subscriptions | Write, confirms | subscriptions:write | | list_bulk_subscription_updates | GET /v2/publications/{publicationId}/bulk_subscription_updates | Read | subscriptions:read | | get_bulk_subscription_update | GET /v2/publications/{publicationId}/bulk_subscription_updates/{id} | Read | subscriptions:read | | replace_bulk_subscription_update | PUT /v2/publications/{publicationId}/subscriptions/bulk_actions | Write, confirms | subscriptions:write | | update_bulk_subscription_update | PATCH /v2/publications/{publicationId}/subscriptions/bulk_actions | Write, confirms | subscriptions:write | | bulk_subscription_updates_put_status | PUT /v2/publications/{publicationId}/subscriptions | Write, confirms | subscriptions:write | | bulk_subscription_updates_patch_status | PATCH /v2/publications/{publicationId}/subscriptions | Write, confirms | subscriptions:write | | create_subscription | POST /v2/publications/{publicationId}/subscriptions | Write, confirms | subscriptions:write | | list_subscriptions | GET /v2/publications/{publicationId}/subscriptions | Read | subscriptions:read | | list_complimentary_access | GET /v2/publications/{publicationId}/complimentary_access | Read | complimentary_access:read | | get_complimentary_access | GET /v2/publications/{publicationId}/complimentary_access/{complimentaryAccessId} | Read | complimentary_access:read | | list_condition_sets | GET /v2/publications/{publicationId}/condition_sets | Read | condition_sets:read | | get_condition_set | GET /v2/publications/{publicationId}/condition_sets/{conditionSetId} | Read | condition_sets:read | | create_custom_field | POST /v2/publications/{publicationId}/custom_fields | Write, confirms | custom_fields:write | | list_custom_fields | GET /v2/publications/{publicationId}/custom_fields | Read | custom_fields:read | | get_custom_field | GET /v2/publications/{publicationId}/custom_fields/{id} | Read | custom_fields:read | | update_custom_field | PUT /v2/publications/{publicationId}/custom_fields/{id} | Write, confirms | custom_fields:write | | patch_custom_field | PATCH /v2/publications/{publicationId}/custom_fields/{id} | Write, confirms | custom_fields:write | | delete_custom_field | DELETE /v2/publications/{publicationId}/custom_fields/{id} | Write, confirms | custom_fields:write | | create_data_deletion | POST /v2/publications/{publicationId}/data_privacy/deletion_requests | Write, confirms | data_deletion:write | | list_data_deletion | GET /v2/publications/{publicationId}/data_privacy/deletion_requests | Read | data_deletion:read | | get_data_deletion | GET /v2/publications/{publicationId}/data_privacy/deletion_requests/{id} | Read | data_deletion:read | | list_engagements | GET /v2/publications/{publicationId}/engagements | Read | publications:read | | list_exports | GET /v2/publications/{publicationId}/exports/subscriptions | Read | subscriptions:read | | create_export | POST /v2/publications/{publicationId}/exports/subscriptions | Write, confirms | subscriptions:write | | get_export | GET /v2/publications/{publicationId}/exports/subscriptions/{id} | Read | subscriptions:read | | list_newsletter_lists | GET /v2/publications/{publicationId}/newsletter_lists | Read | newsletter_lists:read | | create_newsletter_list | POST /v2/publications/{publicationId}/newsletter_lists | Write, confirms | newsletter_lists:write | | get_newsletter_list | GET /v2/publications/{publicationId}/newsletter_lists/{newsletterListId} | Read | newsletter_lists:read | | update_newsletter_list | PATCH /v2/publications/{publicationId}/newsletter_lists/{newsletterListId} | Write, confirms | newsletter_lists:write | | delete_newsletter_list | DELETE /v2/publications/{publicationId}/newsletter_lists/{newsletterListId} | Write, confirms | newsletter_lists:write | | create_newsletter_list_subscription | POST /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions | Write, confirms | newsletter_lists:write | | list_newsletter_list_subscriptions | GET /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions | Read | newsletter_lists:read | | get_newsletter_list_subscription | GET /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/{newsletterListSubscriptionId} | Read | newsletter_lists:read | | update_newsletter_list_subscription | PATCH /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/{newsletterListSubscriptionId} | Write, confirms | newsletter_lists:write | | newsletter_list_subscriptions_update_by_subscription_id | PATCH /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/by_subscription_id/{subscriptionId} | Write, confirms | newsletter_lists:write | | newsletter_list_subscriptions_create_import | POST /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/import | Write, confirms | newsletter_lists:write | | newsletter_list_subscriptions_get_import | GET /v2/publications/{publicationId}/newsletter_lists/{newsletterListId}/subscriptions/import | Read | newsletter_lists:read | | identify_oauth_user | GET /v2/users/identify | Read | identify:read | | podcasts_list_podcasts | GET /v2/publications/{publicationId}/podcasts | Read | podcasts:read | | podcasts_get_podcast | GET /v2/publications/{publicationId}/podcasts/{podcastShowId} | Read | podcasts:read | | podcasts_get_private_feed | GET /v2/publications/{publicationId}/podcasts/{podcastShowId}/private_feeds/{subscriptionId} | Read | podcasts:read | | podcasts_get_private_feed_by_email | GET /v2/publications/{publicationId}/podcasts/{podcastShowId}/private_feeds/by_email/{email} | Read | podcasts:read | | podcasts_send_private_feed_email | POST /v2/publications/{publicationId}/podcasts/{podcastShowId}/private_feeds/{subscriptionId}/emails | Write, confirms | podcasts:write | | podcasts_send_private_feed_email_by_email | POST /v2/publications/{publicationId}/podcasts/{podcastShowId}/private_feeds/by_email/{email}/emails | Write, confirms | podcasts:write | | podcasts_list_episodes | GET /v2/publications/{publicationId}/podcasts/{podcastShowId}/episodes | Read | podcasts:read | | podcasts_get_episode | GET /v2/publications/{publicationId}/podcasts/{podcastShowId}/episodes/{podcastEpisodeId} | Read | podcasts:read | | list_polls | GET /v2/publications/{publicationId}/polls | Read | polls:read | | get_poll | GET /v2/publications/{publicationId}/polls/{pollId} | Read | polls:read | | polls_list_responses | GET /v2/publications/{publicationId}/polls/{pollId}/responses | Read | polls:read | | create_post | POST /v2/publications/{publicationId}/posts | Write, confirms | posts:write | | list_posts | GET /v2/publications/{publicationId}/posts | Read | posts:read | | update_post | PATCH /v2/publications/{publicationId}/posts/{postId} | Write, confirms | posts:write | | get_post | GET /v2/publications/{publicationId}/posts/{postId} | Read | posts:read | | delete_post | DELETE /v2/publications/{publicationId}/posts/{postId} | Write, confirms | posts:write | | get_post_aggregate_stats | GET /v2/publications/{publicationId}/posts/aggregate_stats | Read | posts:read | | send_post_test | POST /v2/publications/{publicationId}/posts/{postId}/test_sends | Write, confirms | posts | | preview_post | GET /v2/publications/{publicationId}/posts/{postId}/preview | Read | posts:read | | list_post_templates | GET /v2/publications/{publicationId}/post_templates | Read | posts:read | | create_post_template | POST /v2/publications/{publicationId}/post_templates | Write, confirms | posts:write | | post_templates_workspace_index | GET /v2/workspaces/post_templates | Read | posts:read | | post_templates_workspace_create | POST /v2/workspaces/post_templates | Write, confirms | posts:write | | post_templates_workspace_show | GET /v2/workspaces/post_templates/{postTemplateId} | Read | posts:read | | get_post_template | GET /v2/publications/{publicationId}/post_templates/{postTemplateId} | Read | posts:read | | list_publication_fields | GET /v2/workspaces/publication_fields | Read | publication_fields:read | | create_publication_field | POST /v2/workspaces/publication_fields | Write, confirms | publication_fields:write | | get_publication_field | GET /v2/workspaces/publication_fields/{publicationFieldId} | Read | publication_fields:read | | update_publication_field | PATCH /v2/workspaces/publication_fields/{publicationFieldId} | Write, confirms | publication_fields:write | | publication_fields_values_index | GET /v2/workspaces/publication_field_values | Read | publication_fields:read | | publication_fields_values_update | PATCH /v2/workspaces/publication_fields/{publicationFieldId}/values | Write, confirms | publication_fields:write | | list_publications | GET /v2/publications | Read | publications:read | | get_publication | GET /v2/publications/{publicationId} | Read | publications:read | | get_referral_program | GET /v2/publications/{publicationId}/referral_program | Read | referral_program:read | | create_segment | POST /v2/publications/{publicationId}/segments | Write, confirms | Account permissions | | list_segments | GET /v2/publications/{publicationId}/segments | Read | segments:read | | get_segment | GET /v2/publications/{publicationId}/segments/{segmentId} | Read | segments:read | | delete_segment | DELETE /v2/publications/{publicationId}/segments/{segmentId} | Write, confirms | segments:write | | segments_recalculate | PUT /v2/publications/{publicationId}/segments/{segmentId}/recalculate | Write, confirms | segments:write | | get_segment_subscribers | GET /v2/publications/{publicationId}/segments/{segmentId}/members | Read | segments:read | | segments_expand_results | GET /v2/publications/{publicationId}/segments/{segmentId}/results | Read | segments:read | | get_subscription_by_email | GET /v2/publications/{publicationId}/subscriptions/by_email/{email} | Read | subscriptions:read | | update_subscription_by_email | PUT /v2/publications/{publicationId}/subscriptions/by_email/{email} | Write, confirms | subscriptions:write | | get_subscription | GET /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Read | subscriptions:read | | update_subscription | PUT /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Write, confirms | subscriptions:write | | patch_subscription | PATCH /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Write, confirms | subscriptions:write | | delete_subscription | DELETE /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Write, confirms | subscriptions:write | | add_tags | POST /v2/publications/{publicationId}/subscriptions/{subscriptionId}/tags | Write, confirms | subscriptions:write | | remove_tag | DELETE /v2/publications/{publicationId}/subscriptions/{subscriptionId}/tags | Write, confirms | subscriptions:write | | create_tier | POST /v2/publications/{publicationId}/tiers | Write, confirms | tiers:write | | list_tiers | GET /v2/publications/{publicationId}/tiers | Read | tiers:read | | get_tier | GET /v2/publications/{publicationId}/tiers/{tierId} | Read | tiers:read | | replace_tier | PUT /v2/publications/{publicationId}/tiers/{tierId} | Write, confirms | tiers:write | | update_tier | PATCH /v2/publications/{publicationId}/tiers/{tierId} | Write, confirms | tiers:write | | create_webhook | POST /v2/publications/{publicationId}/webhooks | Write, confirms | webhooks:write | | list_webhooks | GET /v2/publications/{publicationId}/webhooks | Read | webhooks:read | | get_webhook | GET /v2/publications/{publicationId}/webhooks/{endpointId} | Read | webhooks:read | | update_webhook | PATCH /v2/publications/{publicationId}/webhooks/{endpointId} | Write, confirms | webhooks:write | | delete_webhook | DELETE /v2/publications/{publicationId}/webhooks/{endpointId} | Write, confirms | webhooks:write | | workspaces_identify | GET /v2/workspaces/identify | Read | identify:read | | workspaces_permissions | GET /v2/workspaces/permissions | Read | identify:read | | workspaces_publications_by_subscription_email | GET /v2/workspaces/publications/by_subscription_email/{email} | Read | publications:read | | list_accounts | Local settings | Read | Not applicable |

Shared input rules

All API tools accept account for a private named account. Every write also takes confirm: set it true only when the user asked for exactly that action. Body tools accept either their individual body arguments, payload containing the whole JSON object, or payload_file pointing to a regular local JSON file up to 5 MB. These body routes are mutually exclusive; path/query inputs stay separate. schema <command> returns every nested property and validation rule.

Only tools whose native schema contains cursor expose all_pages and max_items. Do not invent cursor input on offset-only endpoints. Tool and argument underscores have dashed CLI aliases.

Complete arguments

list_ad_network_offers

Get ad offers. Reads account data. OAuth integrations require posts:read.

beehiiv-cli list-ad-network-offers --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. |

create_ad_network_offer

Accept ad offer. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require posts:write.

beehiiv-cli create-ad-network-offer --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | offer_id | string | Body | The ID of the ad offer to accept. | | advertisement_id | string | Body | The ID of the advertisement creative to use. | | post_id | string | Body | The ID of the post where the advertisement should be inserted. | | custom_intro | string | No | Plain text displayed before the advertisement. Maximum 200 characters and cannot contain URLs. Available only when custom ad introductions are enabled for the publication. |

ad_network_offers_advertisements

Get ad offer advertisements. Reads account data. OAuth integrations require posts:read.

beehiiv-cli ad-network-offers-advertisements --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | offer_id | string | Yes | The ID of the ad offer. |

list_ad_network_reports

Get ad network reports. Reads account data. OAuth integrations require posts:read.

beehiiv-cli list-ad-network-reports --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object. Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | limit | integer | No | A limit between 1 and 100. Defaults to 10. Minimum: 1. Maximum: 100. | | page | integer | No | The page of reports to return. Defaults to 1. Minimum: 1. Maximum: 100. | | start_date | string | No | Include reports for advertisements sent on or after this date in YYYY-MM-DD format. Format: date. | | end_date | string | No | Include reports for advertisements sent on or before this date in YYYY-MM-DD format. Format: date. |

ad_network_reports_summary

Get ad network report summary. Reads account data. OAuth integrations require posts:read.

beehiiv-cli ad-network-reports-summary --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object. Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | start_date | string | No | Include reports for advertisements sent on or after this date in YYYY-MM-DD format. Format: date. | | end_date | string | No | Include reports for advertisements sent on or before this date in YYYY-MM-DD format. Format: date. |

ad_network_reports_account_summary

Get account ad network report summary. Reads account data. OAuth integrations require posts:read.

beehiiv-cli ad-network-reports-account-summary --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | start_date | string | No | Include reports for advertisements sent on or after this date in YYYY-MM-DD format. Format: date. | | end_date | string | No | Include reports for advertisements sent on or before this date in YYYY-MM-DD format. Format: date. |

list_advertisement_opportunities

Get advertisement opportunities. Reads account data. OAuth integrations require posts:read.

beehiiv-cli list-advertisement-opportunities --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. |

list_authors

List authors. Reads account data.

beehiiv-cli list-authors --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | page | integer | No | 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. Minimum: 1. Maximum: 100. | | name | string | No | Optionally filter authors by full name or first name (case-insensitive). |

get_author

Get author. Reads account data.

beehiiv-cli get-author --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | author_id | string | Yes | The author identifier. This accepts a prefixed author ID, full name, or first name. |

add_subscriber_to_automation

Add subscription to an automation. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require automations:write.

beehiiv-cli add-subscriber-to-automation --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | automation_id | string | Yes | The prefixed ID of the automation object Pattern: ^(aut_[0-9a-fA-F\-]+)$. | | email | string | No | The email address associated with the subscription. | | subscription_id | string | No | The prefixed ID of the subscription. Pattern: ^(sub_[0-9a-fA-F\-]+)$. | | double_opt_override | string | No | 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. |

list_automation_journeys

List automation journeys. Reads account data. OAuth integrations require automations:read.

beehiiv-cli list-automation-journeys --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | automation_id | string | Yes | The prefixed ID of the automation object Pattern: ^(aut_[0-9a-fA-F\-]+)$. | | status | string | No | Optionally filter the results by the automation journey's status. Default: all. Values: in_progress, completed, exited_early, all. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | page | integer | No | Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10). Minimum: 1. Maximum: 100. |

get_automation_journey

Get automation journey. Reads account data. OAuth integrations require automations:read.

beehiiv-cli get-automation-journey --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | automation_id | string | Yes | The prefixed ID of the automation object Pattern: ^(aut_[0-9a-fA-F\-]+)$. | | automation_journey_id | string | Yes | The prefixed automation journey id Pattern: ^(aj_[0-9a-fA-F\-]+)$. |

list_automations

List automations. Reads account data. OAuth integrations require automations:read.

beehiiv-cli list-automations --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | expand | string | No | Optional list of expandable objects. Values: stats. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | page | integer | No | 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. Minimum: 1. Maximum: 100. |

get_automation

Get automation. Reads account data. OAuth integrations require automations:read.

beehiiv-cli get-automation --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | automation_id | string | Yes | The prefixed ID of the automation object Pattern: ^(aut_[0-9a-fA-F\-]+)$. | | expand | string | No | Optional list of expandable objects. Values: stats. |

automations_list_emails

List automation emails. Reads account data.

beehiiv-cli automations-list-emails --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | automation_id | string | Yes | The prefixed ID of the automation object Pattern: ^(aut_[0-9a-fA-F\-]+)$. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | cursor | string | No | 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. | | page | integer | No | Deprecated: Use cursor instead. Pagination returns the results in pages. Limited to 100 pages maximum. Minimum: 1. Maximum: 100. | | all_pages | boolean | No | Read successive cursor pages, bounded by max_items (default 1000). | | max_items | integer | No | Maximum records when all_pages=true. Returns continuation cursor and truncation. Minimum: 1. Maximum: 10000. |

create_bulk_subscription

Bulk create subscription. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli create-bulk-subscription --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | subscriptions | array | Body | Subscriptions (body input). Array items: object. |

list_bulk_subscription_updates

List subscription updates. Reads account data. OAuth integrations require subscriptions:read.

beehiiv-cli list-bulk-subscription-updates --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. |

get_bulk_subscription_update

Get subscription update. Reads account data. OAuth integrations require subscriptions:read.

beehiiv-cli get-bulk-subscription-update --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | bulk_subscription_update_id | string | Yes | The ID of the Subscription Update object |

replace_bulk_subscription_update

Update subscriptions. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli replace-bulk-subscription-update --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | subscriptions | array | No | An array of objects representing the subscriptions to be updated (max 1000). Array items: object. |

update_bulk_subscription_update

Update subscriptions. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli update-bulk-subscription-update --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | subscriptions | array | No | An array of objects representing the subscriptions to be updated (max 1000). Array items: object. |

bulk_subscription_updates_put_status

Update subscriptions' status. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli bulk-subscription-updates-put-status --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | subscription_ids | array | Body | An array of subscription IDs to be updated Array items: string. | | new_status | string | Body | The new status to set for the subscriptions |

bulk_subscription_updates_patch_status

Update subscriptions' status. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli bulk-subscription-updates-patch-status --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | subscription_ids | array | Body | An array of subscription IDs to be updated Array items: string. | | new_status | string | Body | The new status to set for the subscriptions |

create_subscription

Create subscription. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require subscriptions:write.

beehiiv-cli create-subscription --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | email | string | Body | The email address of the subscription. | | reactivate_existing | boolean | No | Whether or not to reactivate the subscription if they have already unsubscribed. This option should be used only if the subscriber is knowingly resubscribing. Default: false. | | send_welcome_email | boolean | No | Send welcome email (body input). Default: false. | | utm_source | string | No | The source of the subscription. | | utm_medium | string | No | The medium of the subscription | | utm_campaign | string | No | The acquisition campaign of the subscription | | utm_term | string | No | The acquisition term; typically the keyword or search term | | utm_content | string | No | The acquisition content; typically used for A/B testing or ad variations | | referring_site | string | No | The website that the subscriber was referred from | | referral_code | string | No | This should be a subscribers referral_code. This gives referral credit for the new subscription. | | custom_fields | array | No | The custom fields must already exist for the publication. Any new custom fields here will be discarded. Array items: object. | | double_opt_override | string | No | 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. | | tier | string | No | The tier for this subscription. Values: free, premium. | | premium_tiers | array | No | 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. Array items: string. | | premium_tier_ids | array | No | 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. Array items: string. | | stripe_customer_id | string | No | The Stripe customer ID for this subscription. Pattern: ^(cus_[0-9a-zA-Z]+)?$. | | automation_ids | array | No | Enroll the subscriber into automations after their subscription has been created. Requires the automations to have an active Add by API trigger. Array items: string. | | newsletter_list_ids | array | No | An array of newsletter list prefixed IDs to subscribe the new subscription to. The newsletter lists must belong to the same publication. Array items: string. | | skip_newsletter_list_auto_subscribe | boolean | No | When true, the subscriber will not be auto-subscribed to newsletter lists configured with auto-subscribe. Defaults to false. | | complimentary_gift_id | string | No | The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication. Pattern: ^(comp_access_[0-9a-fA-F\-]+)$. |

list_subscriptions

List subscriptions. Reads account data. OAuth integrations require subscriptions:read.

beehiiv-cli list-subscriptions --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | expand | string | No | 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. Values: stats, custom_fields, referrals, newsletter_lists. | | status | string | No | Optionally filter the results by a status Default: all. Values: validating, invalid, pending, active, inactive, all. | | tier | string | No | Optionally filter the results by a their tier Default: all. Values: free, premium, all. | | premium_tiers | string | No | Optionally filter the results by one or multiple premium tiers | | premium_tier_ids | string | No | Optionally filter the results by one or multiple premium tier ids | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | cursor | string | No | 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 for more details. | | page | integer | No | 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 for migration guidance. Minimum: 1. Maximum: 100. | | email | string | No | Optional email address to find a subscription. This param must be an exact match and is case insensitive. | | order_by | string | No | The field that the results are sorted by. Defaults to created created - The time in which the subscription was first created. Default: created. Values: created. | | direction | string | No | 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. Default: asc. Values: asc, desc. | | creation_date | string | No | Optional date entry (in the format YYYY/MM/DD) that filters returned subscriptions by their creation date. | | all_pages | boolean | No | Read successive cursor pages, bounded by max_items (default 1000). | | max_items | integer | No | Maximum records when all_pages=true. Returns continuation cursor and truncation. Minimum: 1. Maximum: 10000. |

list_complimentary_access

List complimentary access. Reads account data. OAuth integrations require complimentary_access:read.

beehiiv-cli list-complimentary-access --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | expand | string | No | Optional list of expandable objects. tier - Returns the full tier object associated with this complimentary access. stats - Returns granted subscription counts. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | cursor | string | No | Use this opaque cursor token to fetch the next page of results. Obtain the value from next_cursor in a previous response. | | all_pages | boolean | No | Read successive cursor pages, bounded by max_items (default 1000). | | max_items | integer | No | Maximum records when all_pages=true. Returns continuation cursor and truncation. Minimum: 1. Maximum: 10000. |

get_complimentary_access

Get complimentary access. Reads account data. OAuth integrations require complimentary_access:read.

beehiiv-cli get-complimentary-access --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | complimentary_access_id | string | Yes | The prefixed ID of the complimentary access object Pattern: ^(comp_access_[0-9a-fA-F\-]+)$. | | expand | string | No | Optional list of expandable objects. tier - Returns the full tier object associated with this complimentary access. |

list_condition_sets

List condition sets. Reads account data. OAuth integrations require condition_sets:read.

beehiiv-cli list-condition-sets --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | limit | integer | No | A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10. Minimum: 1. Maximum: 100. | | cursor | string | No | 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. | | page | integer | No | 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. Minimum: 1. Maximum: 100. | | purpose | string | No | Filter condition sets by purpose. When not specified, all active condition sets are returned. Values: dynamic_content. | | all_pages | boolean | No | Read successive cursor pages, bounded by max_items (default 1000). | | max_items | integer | No | Maximum records when all_pages=true. Returns continuation cursor and truncation. Minimum: 1. Maximum: 10000. |

get_condition_set

Get condition set. Reads account data. OAuth integrations require condition_sets:read.

beehiiv-cli get-condition-set --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | condition_set_id | string | Yes | The UUID of the condition set object | | expand | array | No | Optionally expand the response to include additional data. stats - Calculates and returns the active subscriber count for this condition set synchronously. Array items: string. |

create_custom_field

Create custom field. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require custom_fields:write.

beehiiv-cli create-custom-field --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | kind | string | Body | The type of value being stored in the custom field. Values: string, integer, boolean, date, datetime, list, double. | | display | string | Body | Display (body input). |

list_custom_fields

List custom fields. Reads account data. OAuth integrations require custom_fields:read.

beehiiv-cli list-custom-fields --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. |

get_custom_field

Get custom field. Reads account data. OAuth integrations require custom_fields:read.

beehiiv-cli get-custom-field --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | custom_field_id | string | Yes | The ID of the Custom Fields object |

update_custom_field

Update custom field. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require custom_fields:write.

beehiiv-cli update-custom-field --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | custom_field_id | string | Yes | The ID of the Custom Fields object | | display | string | No | Display (body input). |

patch_custom_field

Update custom field. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require custom_fields:write.

beehiiv-cli patch-custom-field --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | custom_field_id | string | Yes | The ID of the Custom Fields object | | display | string | No | Display (body input). |

delete_custom_field

Delete custom field. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require custom_fields:write.

beehiiv-cli delete-custom-field --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | custom_field_id | string | Yes | The ID of the Custom Fields object |

create_data_deletion

Create data deletion request. Changes account state and requires confirm=true for the user-requested action. OAuth integrations require data_deletion:write.

beehiiv-cli create-data-deletion --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | email | string | Body | The email address of the subscriber to delete. |

list_data_deletion

List data deletion requests. Reads account data. OAuth integrations require data_deletion:read.

beehiiv-cli list-data-deletion --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. |

get_data_deletion

Get data deletion request. Reads account data. OAuth integrations require data_deletion:read.

beehiiv-cli get-data-deletion --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication object Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | data_deletion_id | string | Yes | The ID of the data deletion request |

list_engagements

Get publication engagements. Reads account data. OAuth integrations require publications:read.

beehiiv-cli list-engagements --help

| Argument | Type | Required | Meaning and constraints | | --- | --- | --- | --- | | publication_id | string | Yes | The prefixed ID of the publication. Pattern: ^(pub_[0-9a-fA-F\-]+)$. | | start_date | string | No | The starting date for the engagement metrics in YYYY-MM-DD format. Defaults to 1 day ago if not provided. Format: date. | | number_of_days | integer | No | 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. Minimum: 1. Maximum: 31. | | granularity | string | No | The granularity at which to report the engagement metrics. Defaults to day if not provided. Values: day, week, month. | | email_type | string | No | Filter engagement metrics by email type. If omitted, all email engagement is included. post: Only post emails. message: Only automated and system-generated emails. Values: all, post, message. | | direction | string | No | The direction that the results are sort