beehiiv

Grow and manage your beehiiv newsletter: list publications, browse posts with open/click stats, add and look up subscribers, and view audience segments. Uses the official beehiiv API v2, which is available on every plan including the free Launch plan.

Actions

Action	What it does
Create beehiiv subscription	Add a subscriber to a beehiiv publication by email, the core way to grow a list from another source such as a form, CRM, or purchase.
Get beehiiv subscription by email	Look up a single subscriber on a beehiiv publication by their email address, returning their status, tier, attribution, and creation time.
List beehiiv posts	List a beehiiv publication's posts (newsletter issues), newest first by default.
List beehiiv publications	List the beehiiv publications your API key can access, with each publication's id, name, and creation time.
List beehiiv segments	List a beehiiv publication's audience segments: the saved groups of subscribers you can target.

Create beehiiv subscription

Add a subscriber to a beehiiv publication by email, the core way to grow a list from another source such as a form, CRM, or purchase. Optionally send the welcome email, reactivate a previously unsubscribed contact, record UTM/referrer attribution, set values for existing custom fields, and override double opt-in. Custom fields must already exist on the publication.

Inputs

Publication IDpublication_idtextRequired: The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
EmailemailtextRequired: Email address of the subscriber to add.
Reactivate existingreactivate_existingtrue/false: When true, re-activate the contact if they previously unsubscribed. Defaults to false.Default: false.
Send welcome emailsend_welcome_emailtrue/false: When true, send the publication's welcome email to the new subscriber. Defaults to false.Default: false.
UTM sourceutm_sourcetext: Attribution source recorded on the subscription.
UTM mediumutm_mediumtext: Attribution medium recorded on the subscription.
UTM campaignutm_campaigntext: Attribution campaign recorded on the subscription.
Referring sitereferring_sitetext: The site the subscriber came from.
Double opt-in overridedouble_opt_overridetext: Override the publication's double opt-in setting for this subscriber. 'on' sends a confirmation email, 'off' activates immediately, 'not_set' uses the publication default.One of: not_set (Use publication default), on (On (send confirmation email)), off (Off (activate immediately)).
Custom fieldscustom_fieldslist: Values for custom fields that already exist on the publication, as a list of {name, value} objects. Unknown fields are ignored by beehiiv.

Outputs

The created (or reactivated) subscription, wrapped in 'data'.

dataobject

Example output

{
  "data": {
    "created": 1719400000,
    "email": "reader@example.com",
    "id": "sub_11112222-3333-4444-5555-666677778888",
    "referral_code": "ab12cd34",
    "referring_site": "example.com",
    "status": "active",
    "subscription_tier": "free",
    "utm_campaign": "spring-launch",
    "utm_medium": "api",
    "utm_source": "workflow"
  }
}

Get beehiiv subscription by email

Look up a single subscriber on a beehiiv publication by their email address, returning their status, tier, attribution, and creation time. Optionally include engagement stats and custom field values. Useful for checking whether someone is subscribed and what tier they are on before taking an action.

Inputs

Publication IDpublication_idtextRequired: The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
EmailemailtextRequired: Email address of the subscriber to look up.
Include statsinclude_statstrue/false: When true, include the subscriber's engagement stats.Default: false.
Include custom fieldsinclude_custom_fieldstrue/false: When true, include the subscriber's custom field values.Default: false.

Outputs

The matching subscription, wrapped in 'data'.

dataobject

Example output

{
  "data": {
    "created": 1719400000,
    "email": "reader@example.com",
    "id": "sub_11112222-3333-4444-5555-666677778888",
    "referral_code": "ab12cd34",
    "referring_site": null,
    "status": "active",
    "subscription_tier": "premium",
    "utm_campaign": null,
    "utm_medium": "social",
    "utm_source": "twitter"
  }
}

List beehiiv posts

List a beehiiv publication's posts (newsletter issues), newest first by default. Each post includes its title, subtitle, status (draft, confirmed, or archived), publish date, and web URL. Filter by status and, when 'Include stats' is on, get per-post open and click metrics. Useful for tracking what has shipped or pulling the latest issue into a workflow.

Inputs

Publication IDpublication_idtextRequired: The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
Statusstatustext: Only return posts with this status. Leave blank for all.One of: confirmed (Confirmed (published/scheduled)), draft, archived, all.
Limitlimitnumber: How many results to return per page, from 1 to 100. Defaults to 10.From 1 to 100.
Pagepagenumber: Which page of results to return (1-based). Defaults to 1. Combine with 'Limit' to page through large lists; the response reports 'total_pages'.At least 1.
Order byorder_bytext: Field to sort posts by. Defaults to creation time.One of: created, publish_date (Publish date), displayed_date (Displayed date).
Directiondirectiontext: Sort direction: ascending or descending.One of: desc (Descending (newest first)), asc (Ascending (oldest first)).
Include statsinclude_statstrue/false: When true, add per-post statistics such as email opens, clicks, and open/click rates.Default: false.

Outputs

Paginated list of posts. Heavy rendered-content fields are not requested; 'stats' is present only when 'include_stats' is true.

datalist
limitnumber
pagenumber
total_pagesnumber
total_resultsnumber

Example output

{
  "data": [
    {
      "audience": "free",
      "content_tags": [
        "ai",
        "creator-economy"
      ],
      "id": "post_a1b2c3d4-5566-7788-99aa-bbccddeeff00",
      "publish_date": 1719400000,
      "status": "confirmed",
      "subtitle": "And what that means for creators",
      "title": "AI agents are eating the newsletter",
      "web_url": "https://the-weekly-byte.beehiiv.com/p/ai-agents"
    }
  ],
  "limit": 10,
  "page": 1,
  "total_pages": 1,
  "total_results": 1
}

List beehiiv publications

List the beehiiv publications your API key can access, with each publication's id, name, and creation time. Every other beehiiv action needs a publication id, so this is usually the first step in a workflow. Optionally include high-level stats (subscriber and post counts).

Inputs

Limitlimitnumber: How many results to return per page, from 1 to 100. Defaults to 10.From 1 to 100.
Pagepagenumber: Which page of results to return (1-based). Defaults to 1. Combine with 'Limit' to page through large lists; the response reports 'total_pages'.At least 1.
Include statsinclude_statstrue/false: When true, add each publication's aggregate stats (active subscriptions, total posts, and more).Default: false.

Outputs

Paginated list of publications. 'data' holds the rows; 'total_results'/'total_pages' describe the full result set.

datalist
limitnumber
pagenumber
total_pagesnumber
total_resultsnumber

Example output

{
  "data": [
    {
      "created": 1704067200,
      "id": "pub_4c9c9b2a-1111-4a2b-8c3d-2f1e0a9b8c7d",
      "name": "The Weekly Byte",
      "organization_name": "Byte Media",
      "referral_program_enabled": true
    }
  ],
  "limit": 10,
  "page": 1,
  "total_pages": 1,
  "total_results": 1
}

List beehiiv segments

List a beehiiv publication's audience segments: the saved groups of subscribers you can target. Each segment includes its id, name, type (dynamic, static, or manual), status, and how many subscribers currently match. Filter by status or type. Useful for finding a segment id or checking segment sizes.

Inputs

Publication IDpublication_idtextRequired: The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
Statusstatustext: Only return segments with this processing status. Leave blank for all.One of: completed, pending, processing, failed, all.
Typetypetext: Only return segments of this type. Leave blank for all.One of: dynamic, static, manual, all.
Limitlimitnumber: How many results to return per page, from 1 to 100. Defaults to 10.From 1 to 100.
Pagepagenumber: Which page of results to return (1-based). Defaults to 1. Combine with 'Limit' to page through large lists; the response reports 'total_pages'.At least 1.

Outputs

Paginated list of audience segments.

datalist
limitnumber
pagenumber
total_pagesnumber
total_resultsnumber

Example output

{
  "data": [
    {
      "id": "seg_99887766-5544-3322-1100-aabbccddeeff",
      "last_calculated": 1719386400,
      "name": "Highly engaged readers",
      "status": "completed",
      "total_results": 1842,
      "type": "dynamic"
    }
  ],
  "limit": 10,
  "page": 1,
  "total_pages": 1,
  "total_results": 1
}

ActionsCopy Anchor Link

Create beehiiv subscriptionCopy Anchor Link

Inputs

Outputs

Get beehiiv subscription by emailCopy Anchor Link

Inputs

Outputs

List beehiiv postsCopy Anchor Link

Inputs

Outputs

List beehiiv publicationsCopy Anchor Link

Inputs

Outputs

List beehiiv segmentsCopy Anchor Link

Inputs

Outputs

On this page

Actions

Create beehiiv subscription

Get beehiiv subscription by email

List beehiiv posts

List beehiiv publications

List beehiiv segments