Skip to main content
Beehiiv logo
  • Category: email newsletters
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 11
  • Triggers: 0
  • Slug: BEEHIIV
  • Version: 00000000_00

Tools

Slug: BEEHIIV_CREATE_DRAFT_POSTCreate 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

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_CREATE_SEGMENTCreate an audience segment from explicit subscription IDs, explicit emails, or custom-field rules; returns the segment and its initial calculation status.

Input Parameters

string
required
Unique segment name within the publication.
string
required
Segment definition using exactly one subscriptions, emails, or custom_fields payload.
string
required
Publication ID, beginning with pub_.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_CREATE_SUBSCRIPTIONCreate 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

string
required
Consenting subscriber’s email address.
string
Acquisition medium for this subscription.
string
Acquisition source for this subscription.
string
Acquisition campaign for this subscription.
array
Initial values for existing custom fields. Beehiiv discards unknown field names.
string
required
Publication ID, beginning with pub_.
string
Website that referred the subscriber.
array
Newsletter list IDs in this publication to join when the subscription is created.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_CUSTOM_FIELDSList 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

integer
One-based page number (1-100).
integer
Maximum custom fields to return on this page (1-100).
string
required
Publication ID, beginning with pub_.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_POSTSSearch a publication’s posts by status, audience, channel, slug, tags, or author and optionally include content, recipients, or statistics.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_PUBLICATIONSList publications accessible to the API key, optionally including publication statistics; use the returned publication IDs with publication-scoped tools.

Input Parameters

integer
One-based page number (1-100).
integer
Maximum publications to return on this page (1-100).
array
Statistics to include for each publication.
string ("created" | "name")
Field used to order publications.
string ("asc" | "desc")
Sort direction.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_SEGMENT_MEMBERSList 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

integer
One-based page number (1-100).
integer
Maximum members to return on this page (1-100).
array
Related subscriber data to include.
string
required
Segment ID, beginning with seg_.
string
required
Publication ID, beginning with pub_.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_SEGMENTSList audience segments in a publication, filtered by segment type or calculation status, with optional latest statistics.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_LIST_SUBSCRIPTIONSSearch a publication’s subscriptions by exact email or filter by status and tier, returning one cursor-controlled page of subscriber records.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_UPDATE_DRAFT_POSTUpdate 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

string
Replacement draft title.
string
required
Draft post ID, beginning with post_.
string
Replacement draft subtitle.
string
Replacement web slug.
string
Replacement raw HTML body. Beehiiv strips style and link tags, so use inline styles.
object
Replacement future web and email targeting. Both web and email objects are required and each channel needs tier_ids or include_segment_ids.
array
Complete replacement set of content tags; an empty array clears all tags.
boolean
Whether the eventual web post should be hidden from the publication feed.
string
required
Publication ID, beginning with pub_.
string
Verified publication reply-to address.
string
Replacement preview text saved on the draft.
string
Replacement subject line saved on the draft.
string
Newsletter list to associate with the draft. Omit to leave unchanged.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: BEEHIIV_UPDATE_SUBSCRIPTION_CUSTOM_FIELDSSet or remove custom-field values on one subscription without changing its email, tier, billing link, or subscribed status.

Input Parameters

array
required
One or more custom-field changes. Field names must already exist in the publication.
string
required
Publication ID, beginning with pub_.
string
required
Subscription ID, beginning with sub_.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not