> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# beehiiv

> Connect beehiiv to your Atako agents — 10 read and 4 write actions.

Let your agents manage newsletter subscribers in beehiiv (add, update tiers and custom fields, unsubscribe, enroll in automations) and read publications, posts, segments, custom fields, automations and tiers.

## Connection

* **Authentication**: API key.

<Note>
  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](https://developers.beehiiv.com/welcome/create-an-api-key).
</Note>

## 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](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.

***

*Last reviewed against the provider API: September 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.