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

App · Email Marketing · 5 actions. Web page: https://docs.lodol.com/docs/integrations/beehiiv

## Actions

### 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 ID (`publication_id`, text, required): The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
- Email (`email`, text, required): Email address of the subscriber to add.
- Reactivate existing (`reactivate_existing`, true/false): When true, re-activate the contact if they previously unsubscribed. Defaults to false. Default: `false`.
- Send welcome email (`send_welcome_email`, true/false): When true, send the publication's welcome email to the new subscriber. Defaults to false. Default: `false`.
- UTM source (`utm_source`, text): Attribution source recorded on the subscription.
- UTM medium (`utm_medium`, text): Attribution medium recorded on the subscription.
- UTM campaign (`utm_campaign`, text): Attribution campaign recorded on the subscription.
- Referring site (`referring_site`, text): The site the subscriber came from.
- Double opt-in override (`double_opt_override`, text): 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 fields (`custom_fields`, list): 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'.

- `data` (object)

**Example output**

```json
{
  "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 ID (`publication_id`, text, required): The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
- Email (`email`, text, required): Email address of the subscriber to look up.
- Include stats (`include_stats`, true/false): When true, include the subscriber's engagement stats. Default: `false`.
- Include custom fields (`include_custom_fields`, true/false): When true, include the subscriber's custom field values. Default: `false`.

**Outputs**: The matching subscription, wrapped in 'data'.

- `data` (object)

**Example output**

```json
{
  "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 ID (`publication_id`, text, required): The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
- Status (`status`, text): Only return posts with this status. Leave blank for all. One of: `confirmed` (Confirmed (published/scheduled)), `draft`, `archived`, `all`.
- Limit (`limit`, number): How many results to return per page, from 1 to 100. Defaults to 10. From 1 to 100.
- Page (`page`, number): 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 by (`order_by`, text): Field to sort posts by. Defaults to creation time. One of: `created`, `publish_date` (Publish date), `displayed_date` (Displayed date).
- Direction (`direction`, text): Sort direction: ascending or descending. One of: `desc` (Descending (newest first)), `asc` (Ascending (oldest first)).
- Include stats (`include_stats`, true/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.

- `data` (list)
- `limit` (number)
- `page` (number)
- `total_pages` (number)
- `total_results` (number)

**Example output**

```json
{
  "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**

- Limit (`limit`, number): How many results to return per page, from 1 to 100. Defaults to 10. From 1 to 100.
- Page (`page`, number): 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 stats (`include_stats`, true/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.

- `data` (list)
- `limit` (number)
- `page` (number)
- `total_pages` (number)
- `total_results` (number)

**Example output**

```json
{
  "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 ID (`publication_id`, text, required): The beehiiv publication to act on, e.g. 'pub_00000000-0000-0000-0000-000000000000'. Use the 'List beehiiv publications' action to find it.
- Status (`status`, text): Only return segments with this processing status. Leave blank for all. One of: `completed`, `pending`, `processing`, `failed`, `all`.
- Type (`type`, text): Only return segments of this type. Leave blank for all. One of: `dynamic`, `static`, `manual`, `all`.
- Limit (`limit`, number): How many results to return per page, from 1 to 100. Defaults to 10. From 1 to 100.
- Page (`page`, number): 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.

- `data` (list)
- `limit` (number)
- `page` (number)
- `total_pages` (number)
- `total_results` (number)

**Example output**

```json
{
  "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
}
```