---
canonical_url: "https://docs.composio.dev/toolkits/beehiiv"
markdown_url: "https://docs.composio.dev/toolkits/beehiiv.md"
product: "platform"
version: null
last_updated: null
---

# Beehiiv

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

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

## Tools

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Draft post title. |
| `subtitle` | string | No | Optional draft subtitle. |
| `web_slug` | string | No | Web slug saved on the draft. |
| `body_html` | string | Yes | Draft body as raw HTML. Beehiiv strips style and link tags, so use inline styles. |
| `recipients` | object | No | Optional future targeting. When supplied, both web and email audiences are required. |
| `content_tags` | array | No | Content tags to assign to the draft. |
| `hide_from_feed` | boolean | No | Whether the eventual web post should be hidden from the publication feed. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |
| `post_template_id` | string | No | Post template ID to use as the draft base. |
| `reply_to_address` | string | No | Verified publication reply-to address; Beehiiv rejects unverified addresses. |
| `email_preview_text` | string | No | Preview text saved on the draft. |
| `email_subject_line` | string | No | Subject line saved on the draft. |
| `newsletter_list_id` | string | No | Newsletter list whose subscribers would be targeted if this draft is later published. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Unique segment name within the publication. |
| `input` | string | Yes | Segment definition using exactly one subscriptions, emails, or custom_fields payload. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Consenting subscriber's email address. |
| `utm_medium` | string | No | Acquisition medium for this subscription. |
| `utm_source` | string | No | Acquisition source for this subscription. |
| `utm_campaign` | string | No | Acquisition campaign for this subscription. |
| `custom_fields` | array | No | Initial values for existing custom fields. Beehiiv discards unknown field names. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |
| `referring_site` | string | No | Website that referred the subscriber. |
| `newsletter_list_ids` | array | No | Newsletter list IDs in this publication to join when the subscription is created. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number (1-100). |
| `limit` | integer | No | Maximum custom fields to return on this page (1-100). |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number (1-100). |
| `limit` | integer | No | Maximum posts to return on this page (1-100). |
| `slugs` | array | No | Exact post slugs to match. |
| `expand` | array | No | Additional post data to include. Rendered content can make responses large, so request only the formats needed. |
| `status` | string ("draft" | "confirmed" | "archived" | "all") | No | Post status to return. |
| `authors` | array | No | Case-insensitive author names to match. |
| `audience` | string ("free" | "premium" | "all") | No | Audience tier to return. |
| `order_by` | string ("created" | "publish_date" | "displayed_date") | No | Field used to order posts. |
| `platform` | string ("web" | "email" | "both" | "all") | No | Publishing channel to return. |
| `direction` | string ("asc" | "desc") | No | Sort direction. |
| `content_tags` | array | No | Return posts having any of these content tags. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number (1-100). |
| `limit` | integer | No | Maximum publications to return on this page (1-100). |
| `expand` | array | No | Statistics to include for each publication. |
| `order_by` | string ("created" | "name") | No | Field used to order publications. |
| `direction` | string ("asc" | "desc") | No | Sort direction. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number (1-100). |
| `limit` | integer | No | Maximum members to return on this page (1-100). |
| `expand` | array | No | Related subscriber data to include. |
| `segment_id` | string | Yes | Segment ID, beginning with seg_. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number (1-100). |
| `limit` | integer | No | Maximum segments to return on this page (1-100). |
| `status` | string ("pending" | "processing" | "completed" | "failed" | "all") | No | Calculation status to return. |
| `order_by` | string ("created" | "last_calculated") | No | Field used to order segments. |
| `direction` | string ("asc" | "desc") | No | Sort direction. |
| `segment_type` | string ("dynamic" | "static" | "manual" | "all") | No | Segment type to return. |
| `include_stats` | boolean | No | Include the latest calculated segment statistics. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tier` | string ("free" | "premium" | "all") | No | Subscription tier to return. |
| `email` | string | No | Exact subscriber email to find; matching is case-insensitive. |
| `limit` | integer | No | Maximum subscriptions to return on this page (1-100). |
| `cursor` | string | No | Opaque next_cursor from a previous response. Omit for the first page and pass it back unchanged to continue. |
| `expand` | array | No | Related subscription data to include. |
| `status` | string ("validating" | "invalid" | "pending" | "active" | "inactive" | "all") | No | Subscription status to return. |
| `direction` | string ("asc" | "desc") | No | Order by creation time ascending or descending. |
| `creation_date` | string | No | Return subscriptions created on this date, formatted YYYY/MM/DD. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |
| `premium_tier_ids` | array | No | Premium tier IDs used to narrow results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | No | Replacement draft title. |
| `post_id` | string | Yes | Draft post ID, beginning with post_. |
| `subtitle` | string | No | Replacement draft subtitle. |
| `web_slug` | string | No | Replacement web slug. |
| `body_html` | string | No | Replacement raw HTML body. Beehiiv strips style and link tags, so use inline styles. |
| `recipients` | object | No | 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 | No | Complete replacement set of content tags; an empty array clears all tags. |
| `hide_from_feed` | boolean | No | Whether the eventual web post should be hidden from the publication feed. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |
| `reply_to_address` | string | No | Verified publication reply-to address. |
| `email_preview_text` | string | No | Replacement preview text saved on the draft. |
| `email_subject_line` | string | No | Replacement subject line saved on the draft. |
| `newsletter_list_id` | string | No | Newsletter list to associate with the draft. Omit to leave unchanged. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `custom_fields` | array | Yes | One or more custom-field changes. Field names must already exist in the publication. |
| `publication_id` | string | Yes | Publication ID, beginning with pub_. |
| `subscription_id` | string | Yes | Subscription ID, beginning with sub_. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |