Connection
- Authentication: API key.
Sign in at app.beehiiv.com → Settings → API (in the Workspace Settings section) → Create New API Key. Copy the key right away: it can no longer be read once you leave the page (beehiiv may ask you to verify your identity with Stripe first). By default the key reaches every publication of the workspace; if you restrict it to some publications, the others answer 404. API access depends on your beehiiv plan (see beehiiv.com/pricing).See beehiiv’s documentation.
Read actions (10)
| Action | Description |
|---|---|
get_post | Get one post. publication_id: string pub_… from list_publications. post_id: string post_… from list_posts. expand: same values as list_posts (stats, free_web_content… for the HTML content); premium_tiers: array of tier display names scoping the expanded content. A post just created by the Send API may answer 202 (still being built): retry shortly. |
get_publication | Get one publication. publication_id: string pub_… from list_publications. expand: same values as list_publications (stats or individual stat_… fields). |
get_subscription | Get one subscription by id (email, status, tier, UTM and referral data). publication_id: string pub_… from list_publications. subscription_id: string sub_… from list_subscriptions (filter by email to find it). expand: array among stats, custom_fields, referrals, tags, newsletter_lists. |
list_automations | List the automations of a publication (id aut_…, name, status, trigger events). publication_id: string pub_… from list_publications. expand: [“stats”] adds their statistics. limit 1 to 100 (default 10); page: 1-based page number. |
list_custom_fields | List the custom fields defined on a publication (id, kind, display, created date, options): display is the name to pass in custom_fields of create_subscription and update_subscription. publication_id: string pub_… from list_publications. |
list_posts | List the posts of a publication (id post_…, title, subtitle, authors, status, audience, dates, web URL). publication_id: string pub_… from list_publications. status: draft, confirmed, archived or all; audience: free, premium or all; platform: web, email, both or all; hidden_from_feed: all, true or false; content_tags, slugs, authors, premium_tiers (tier display names): arrays of strings, any match. expand: array among stats, free_web_content, free_email_content, free_rss_content, premium_web_content, premium_email_content, recipients (content fields return HTML). order_by: created, publish_date or displayed_date; direction: asc or desc. limit 1 to 100 (default 10); page: 1-based page number. |
list_publications | List the publications the API key can reach (id pub_…, name, organization name, referral program flag, created date). expand: array among 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. order_by: created or name; direction: asc or desc. limit 1 to 100 (default 10); page: 1-based page number. |
list_segments | List the segments of a publication (id, name, type, status, last calculation). publication_id: string pub_… from list_publications. type: dynamic, static, manual or all; status: pending, processing, completed, failed or all; expand: [“stats”] adds the latest calculated stats. order_by: created or last_calculated; direction: asc or desc. limit 1 to 100 (default 10); page: 1-based page number. |
list_subscriptions | List the subscriptions of a publication (id sub_…, email, status, created date, subscription tier, UTM data). publication_id: string pub_… from list_publications. email: exact, case-insensitive match — the way to find one subscriber’s id from an address. status: validating, invalid, pending, active, inactive or all; tier: free, premium or all; premium_tier_ids: array of tier ids from list_tiers; creation_date: YYYY/MM/DD. expand: array among stats, custom_fields, referrals, newsletter_lists. direction: asc or desc. Cursor pagination: limit 1 to 100 (default 10), pass the response next_cursor as cursor while has_more is true. |
list_tiers | List the tiers of a publication (id, name, status, description): the ids to pass as premium_tier_ids. publication_id: string pub_… from list_publications. expand: array among stats, prices. direction: asc or desc. limit 1 to 100 (default 10); page: 1-based page number. |
Write actions (4)
| Action | Description |
|---|---|
add_subscription_to_automation | Enroll an EXISTING subscriber in an automation (to enroll a new one, use automation_ids of create_subscription). The automation must have an active “Add by API” trigger. Arguments: publication_id (string pub_…); automation_id (string aut_…, from list_automations); exactly one of email (string) or subscription_id (string sub_…, from list_subscriptions); double_opt_override (string, optional, overrides the publication’s double opt-in setting). |
create_subscription | Subscribe an email address to a publication. Arguments: publication_id (string pub_…, from list_publications); email (string, required); send_welcome_email (boolean, default false); reactivate_existing (boolean, default false — only when the person knowingly re-subscribes after unsubscribing); double_opt_override (string, overrides the publication’s double opt-in setting); tier (free or premium); premium_tier_ids (array of strings, tier ids from list_tiers); custom_fields (array of objects {name, value}: name = an existing field’s display value from list_custom_fields, value = string, number, boolean or array of strings — not a map; unknown names are discarded); automation_ids (array of strings aut_… from list_automations, each needing an active “Add by API” trigger); utm_source, utm_medium, utm_campaign, utm_term, utm_content, referring_site (strings); referral_code (string, an existing subscriber’s referral code, to credit them). |
unsubscribe_subscription | Unsubscribe a subscription from the publication (the subscriber record and its history are kept, nothing is deleted). Treat it as the subscriber’s own decision: only re-subscribe them later with their explicit consent. Arguments: publication_id (string pub_…); subscription_id (string sub_…, from list_subscriptions filtered by email). |
update_subscription | Update a subscription’s tier and custom field values (use unsubscribe_subscription to unsubscribe). Arguments: publication_id (string pub_…); subscription_id (string sub_…, from list_subscriptions filtered by email); tier (free or premium); premium_tier_ids (array of strings, tier ids from list_tiers; takes precedence over tier); custom_fields (array of objects {name, value, delete}: name = an existing field’s display value from list_custom_fields; value = string, number, boolean or array of strings; delete = true removes that field’s value from the subscription). Provide at least one of tier, premium_tier_ids, custom_fields. |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: September 2026.