> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Beehiiv

> Beehiiv is a newsletter platform for managing publications, subscribers, posts, automations, audience engagement, and monetization.

![Beehiiv logo](https://mintcdn.com/composio-preview/6S5R4NszqpnVIZRD/images/toolkits/beehiiv.svg?fit=max\&auto=format\&n=6S5R4NszqpnVIZRD\&q=85\&s=4610c0810daa4ef1ee1eacab7c1fa308)

* **Category:** email newsletters
* **Auth:** API\_KEY
* **Composio-managed OAuth available?** N/A
* **Tools:** 11
* **Triggers:** 0
* **Slug:** `BEEHIIV`
* **Version:** 00000000\_00

## Tools

> [accordion] Create Draft Post
>
> **Slug:** `BEEHIIV_CREATE_DRAFT_POST`
>
> Create an unscheduled draft post from HTML content. This tool never confirms, publishes, schedules, or sends the post. Beehiiv creates posts asynchronously; the returned ID is stable while background creation finishes.
>
> #### Input Parameters
>
> **title** `string` *required*
>
> Draft post title.
>
> **subtitle** `string`
>
> Optional draft subtitle.
>
> **web\_slug** `string`
>
> Web slug saved on the draft.
>
> **body\_html** `string` *required*
>
> Draft body as raw HTML. Beehiiv strips style and link tags, so use inline styles.
>
> **recipients** `object`
>
> Optional future targeting. When supplied, both web and email audiences are required.
>
> **content\_tags** `array`
>
> Content tags to assign to the draft.
>
> **hide\_from\_feed** `boolean`
>
> Whether the eventual web post should be hidden from the publication feed.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> **post\_template\_id** `string`
>
> Post template ID to use as the draft base.
>
> **reply\_to\_address** `string`
>
> Verified publication reply-to address; Beehiiv rejects unverified addresses.
>
> **email\_preview\_text** `string`
>
> Preview text saved on the draft.
>
> **email\_subject\_line** `string`
>
> Subject line saved on the draft.
>
> **newsletter\_list\_id** `string`
>
> Newsletter list whose subscribers would be targeted if this draft is later published.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Create Segment
>
> **Slug:** `BEEHIIV_CREATE_SEGMENT`
>
> Create an audience segment from explicit subscription IDs, explicit emails, or custom-field rules; returns the segment and its initial calculation status.
>
> #### Input Parameters
>
> **name** `string` *required*
>
> Unique segment name within the publication.
>
> **input** `string` *required*
>
> Segment definition using exactly one subscriptions, emails, or custom\_fields payload.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Create Subscription
>
> **Slug:** `BEEHIIV_CREATE_SUBSCRIPTION`
>
> Create a new publication subscription without reactivating an unsubscribed address or sending a welcome email; supports attribution, initial custom fields, and newsletter-list assignment.
>
> #### Input Parameters
>
> **email** `string` *required*
>
> Consenting subscriber's email address.
>
> **utm\_medium** `string`
>
> Acquisition medium for this subscription.
>
> **utm\_source** `string`
>
> Acquisition source for this subscription.
>
> **utm\_campaign** `string`
>
> Acquisition campaign for this subscription.
>
> **custom\_fields** `array`
>
> Initial values for existing custom fields. Beehiiv discards unknown field names.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> **referring\_site** `string`
>
> Website that referred the subscriber.
>
> **newsletter\_list\_ids** `array`
>
> Newsletter list IDs in this publication to join when the subscription is created.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Custom Fields
>
> **Slug:** `BEEHIIV_LIST_CUSTOM_FIELDS`
>
> List the custom-field definitions available for subscriber metadata and dynamic audience segments in a publication, returning one page controlled by page and limit with pagination metadata for retrieving additional fields.
>
> #### Input Parameters
>
> **page** `integer`
>
> One-based page number (1-100).
>
> **limit** `integer`
>
> Maximum custom fields to return on this page (1-100).
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Posts
>
> **Slug:** `BEEHIIV_LIST_POSTS`
>
> Search a publication's posts by status, audience, channel, slug, tags, or author and optionally include content, recipients, or statistics.
>
> #### Input Parameters
>
> **page** `integer`
>
> One-based page number (1-100).
>
> **limit** `integer`
>
> Maximum posts to return on this page (1-100).
>
> **slugs** `array`
>
> Exact post slugs to match.
>
> **expand** `array`
>
> Additional post data to include. Rendered content can make responses large, so request only the formats needed.
>
> **status** `string ("draft" | "confirmed" | "archived" | "all")`
>
> Post status to return.
>
> **authors** `array`
>
> Case-insensitive author names to match.
>
> **audience** `string ("free" | "premium" | "all")`
>
> Audience tier to return.
>
> **order\_by** `string ("created" | "publish_date" | "displayed_date")`
>
> Field used to order posts.
>
> **platform** `string ("web" | "email" | "both" | "all")`
>
> Publishing channel to return.
>
> **direction** `string ("asc" | "desc")`
>
> Sort direction.
>
> **content\_tags** `array`
>
> Return posts having any of these content tags.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Publications
>
> **Slug:** `BEEHIIV_LIST_PUBLICATIONS`
>
> List publications accessible to the API key, optionally including publication statistics; use the returned publication IDs with publication-scoped tools.
>
> #### Input Parameters
>
> **page** `integer`
>
> One-based page number (1-100).
>
> **limit** `integer`
>
> Maximum publications to return on this page (1-100).
>
> **expand** `array`
>
> Statistics to include for each publication.
>
> **order\_by** `string ("created" | "name")`
>
> Field used to order publications.
>
> **direction** `string ("asc" | "desc")`
>
> Sort direction.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Segment Members
>
> **Slug:** `BEEHIIV_LIST_SEGMENT_MEMBERS`
>
> List full subscriber records currently included in an audience segment, optionally including stats, custom fields, referrals, tags, or premium tiers. The response contains subscriber PII.
>
> #### Input Parameters
>
> **page** `integer`
>
> One-based page number (1-100).
>
> **limit** `integer`
>
> Maximum members to return on this page (1-100).
>
> **expand** `array`
>
> Related subscriber data to include.
>
> **segment\_id** `string` *required*
>
> Segment ID, beginning with seg\_.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Segments
>
> **Slug:** `BEEHIIV_LIST_SEGMENTS`
>
> List audience segments in a publication, filtered by segment type or calculation status, with optional latest statistics.
>
> #### Input Parameters
>
> **page** `integer`
>
> One-based page number (1-100).
>
> **limit** `integer`
>
> Maximum segments to return on this page (1-100).
>
> **status** `string ("pending" | "processing" | "completed" | "failed" | "all")`
>
> Calculation status to return.
>
> **order\_by** `string ("created" | "last_calculated")`
>
> Field used to order segments.
>
> **direction** `string ("asc" | "desc")`
>
> Sort direction.
>
> **segment\_type** `string ("dynamic" | "static" | "manual" | "all")`
>
> Segment type to return.
>
> **include\_stats** `boolean`
>
> Include the latest calculated segment statistics.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] List Subscriptions
>
> **Slug:** `BEEHIIV_LIST_SUBSCRIPTIONS`
>
> Search a publication's subscriptions by exact email or filter by status and tier, returning one cursor-controlled page of subscriber records.
>
> #### Input Parameters
>
> **tier** `string ("free" | "premium" | "all")`
>
> Subscription tier to return.
>
> **email** `string`
>
> Exact subscriber email to find; matching is case-insensitive.
>
> **limit** `integer`
>
> Maximum subscriptions to return on this page (1-100).
>
> **cursor** `string`
>
> Opaque next\_cursor from a previous response. Omit for the first page and pass it back unchanged to continue.
>
> **expand** `array`
>
> Related subscription data to include.
>
> **status** `string ("validating" | "invalid" | "pending" | "active" | "inactive" | "all")`
>
> Subscription status to return.
>
> **direction** `string ("asc" | "desc")`
>
> Order by creation time ascending or descending.
>
> **creation\_date** `string`
>
> Return subscriptions created on this date, formatted YYYY/MM/DD.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> **premium\_tier\_ids** `array`
>
> Premium tier IDs used to narrow results.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Update Draft Post
>
> **Slug:** `BEEHIIV_UPDATE_DRAFT_POST`
>
> Update content or presentation settings on an existing draft after verifying it is still a draft; refuses confirmed, archived, or sent posts and cannot publish or schedule.
>
> #### Input Parameters
>
> **title** `string`
>
> Replacement draft title.
>
> **post\_id** `string` *required*
>
> Draft post ID, beginning with post\_.
>
> **subtitle** `string`
>
> Replacement draft subtitle.
>
> **web\_slug** `string`
>
> Replacement web slug.
>
> **body\_html** `string`
>
> Replacement raw HTML body. Beehiiv strips style and link tags, so use inline styles.
>
> **recipients** `object`
>
> Replacement future web and email targeting. Both web and email objects are required and each channel needs tier\_ids or include\_segment\_ids.
>
> **content\_tags** `array`
>
> Complete replacement set of content tags; an empty array clears all tags.
>
> **hide\_from\_feed** `boolean`
>
> Whether the eventual web post should be hidden from the publication feed.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> **reply\_to\_address** `string`
>
> Verified publication reply-to address.
>
> **email\_preview\_text** `string`
>
> Replacement preview text saved on the draft.
>
> **email\_subject\_line** `string`
>
> Replacement subject line saved on the draft.
>
> **newsletter\_list\_id** `string`
>
> Newsletter list to associate with the draft. Omit to leave unchanged.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] Update Subscription Custom Fields
>
> **Slug:** `BEEHIIV_UPDATE_SUBSCRIPTION_CUSTOM_FIELDS`
>
> Set or remove custom-field values on one subscription without changing its email, tier, billing link, or subscribed status.
>
> #### Input Parameters
>
> **custom\_fields** `array` *required*
>
> One or more custom-field changes. Field names must already exist in the publication.
>
> **publication\_id** `string` *required*
>
> Publication ID, beginning with pub\_.
>
> **subscription\_id** `string` *required*
>
> Subscription ID, beginning with sub\_.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not
