beehiiv

Retrieve aggregate stats for all posts

Add an existing subscription to an automation flow. Requires the automation to have an active *Add by API* trigger. The specified `email` or `subscription_id` will be matched against your existing subscribers. If an existing subscriber is found, they will be enrolled immediately. Looking to enroll new subscribers? Use the **[Create Subscription](/api-reference/subscriptions/create)** endpoint instead and specify the `automation_ids` param.

Delete a custom field from a publication.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Delete a newsletter list belonging to a specific publication.

Delete or Archive a post. Any post that has been confirmed will have it's status changed to `archived`. Posts in the `draft` status will be permanently deleted.

Delete a segment. Deleting the segment does not effect the subscriptions in the segment.

<Warning>This cannot be undone. All data associated with the subscription will also be deleted. We recommend unsubscribing when possible instead of deleting. If a premium subscription is deleted they will no longer be billed.</Warning> Deletes a subscription.

Delete a webhook subscription from a publication.

List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details. **Use this endpoint when you only need subscriber IDs** (e.g., for counting, ID-based lookups, or integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use `/segments/{segmentId}/members` instead.

<Info>Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding.</Info> Retrieve a single subscription belonging to a specific email address in a specific publication.

<Info>In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID. This endpoint is now deprecated and will be removed in a future version of the API. Please use this endpoint instead. The subscription ID can be found by exporting a list of subscriptions either via the `Settings > Publications > Export Data` or by exporting a CSV in a segment.</Info> Retrieve a single subscription belonging to a specific publication.

Retrieve all publications associated with your API key.

Retrieve a single publication

Retrieve a list of authors available for the publication.

Retrieve automations for a publication.

Retrieve a single automation for a publication.

Retrieve a list of automation journeys that have occurred within a specific automation.

Retrieve a single automation journey by ID.

Returns a list of Subscription Update objects for a publication.

Returns a single Subscription Update object for a publication.

Retrieve all complimentary access objects belonging to a specific publication.

Retrieve a single complimentary access object belonging to a specific publication.

Retrieve all active condition sets for a publication. Condition sets define reusable audience segments for targeting content to specific subscribers. Use the `purpose` parameter to filter by a specific use case.

Retrieve a single active dynamic content condition set for a publication. Use `expand[]=stats` to calculate and return the active subscriber count synchronously.

List all custom fields on a publication.

View a specific custom field on a publication.

<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning> List all data deletion requests for your organization. API keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.

<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning> Retrieve the details and current status of a specific data deletion request. API keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.

Retrieve email engagement metrics for a specific publication over a defined date range and granularity.<br><br> By default, the endpoint returns metrics for the past day, aggregated daily. The max number of days allowed is 31. All dates and times are in UTC.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> List all newsletter lists for a publication.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Retrieve a single newsletter list belonging to a specific publication.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> List all subscriptions for a newsletter list.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Retrieve a single newsletter list subscription.

Retrieve all polls belonging to a specific publication. Poll choices are always included. Use `expand[]=stats` to include aggregate vote counts per choice.

Retrieve detailed information about a specific poll belonging to a publication. Use `expand[]=stats` for aggregate vote counts, or `expand[]=poll_responses` for individual subscriber responses.

Retrieve a list of post templates available for the publication.

Retrieve all posts belonging to a specific publication

Retrieve a single Post belonging to a specific publication

Retrieve details about the publication's referral program, including milestones and rewards.

Retrieve information about all segments belonging to a specific publication

Retrieve information about a specific segment belonging to a publication

Retrieve all subscriptions belonging to a specific publication. <Info> **New**: This endpoint now supports cursor-based pagination for better performance and consistency. Use the `cursor` parameter instead of `page` for new integrations. </Info> <Warning> **Deprecation Notice**: Offset-based pagination (using `page` parameter) is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination. See our [Pagination Guide](/welcome/pagination) for details. </Warning>

Retrieve all tiers belonging to a specific publication

Retrieve a single tier belonging to a specific publication

Retrieve all webhooks belonging to a specific publication.

Retrieve a specific webhook belonging to a publication.

Retrieve information about the workspace the OAuth or API token is associated with.

Retrieve information about the user who authorized the OAuth access token.

Retrieve a list of accepted advertisement opportunities for the publication.

Retrieve all emails belonging to a specific automation, including engagement statistics for each email.

List all members in a segment with full subscription data. Each member is returned as a subscription object containing complete subscriber information and their subscription details. Supports optional expansions for stats, custom fields, tags, referrals, and premium tiers. **Use this endpoint when you need detailed subscriber information.** If you only need subscriber IDs, use `/segments/{segmentId}/results` for a lighter-weight response.

Retrieve all individual subscriber responses for a specific poll with cursor-based pagination. Use this endpoint for large datasets instead of the `expand[]=poll_responses` parameter on the poll show endpoint.

Bulk update multiple subscriptions fields, including status, custom fields, and tiers.

Update a custom field on a publication.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Update a newsletter list subscription. Currently supports unsubscribing a subscription from a newsletter list.

<Note title="Currently in beta" icon="b"> This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing, please visit our <a href="https://www.beehiiv.com/enterprise">Enterprise page</a>. </Note> Update an existing post for a specific publication. Only the fields provided in the request body will be updated — all other fields remain unchanged. For a detailed walkthrough of content methods and working with custom HTML, see the <a href="https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint">Using the Send API and Create Post Endpoint</a> guide. To update post content, provide either `blocks` or `body_content` (not both). If neither is provided, the existing content is preserved. The same content methods and CSS guardrails described in the create endpoint apply here.

Update a single subscription.

Update an existing tier belonging to a specific publication

Update a webhook subscription for a publication.

Bulk update subscriptions' status.

Create new subscriptions for a publication.

Create a custom field on a publication, for use in subscriptions.

<Warning>This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.</Warning> Creates a data deletion request for a subscriber within your organization. The subscriber's data will be redacted from all publications in the organization after a 14-day safety delay. This action cannot be undone once processing begins. API keys restricted to specific publications cannot access this endpoint and will receive a 403 response, since deletion requests apply to the entire workspace.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Create a new newsletter list for a publication. The list will be created with an active status. The slug will be auto-generated from the name if not provided.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Subscribe a subscription to a newsletter list. Accepts either a subscription_id or email to identify the subscription.

<Note title="Currently in beta" icon="b"> This feature is currently in beta, the API is subject to change, and available only to Enterprise users.<br/><br/>To inquire about Enterprise pricing, please visit our <a href="https://www.beehiiv.com/enterprise">Enterprise page</a>. </Note> Create a post for a specific publication. For a detailed walkthrough including setup, testing workflows, and working with custom HTML and templates, see the <a href="https://www.beehiiv.com/support/article/36759164012439-using-the-send-api-and-create-post-endpoint">Using the Send API and Create Post Endpoint</a> guide. ## Content methods There are three ways to provide content for a post. You must provide either `blocks` or `body_content`, but not both. ### 1. Blocks Use the `blocks` field to build your post with structured content blocks such as paragraphs, images, headings, buttons, tables, and more. Each block has a `type` and its own set of properties. This method gives you fine-grained control over individual content elements and supports features like visual settings, visibility settings, and dynamic content targeting. ### 2. Raw HTML (`body_content`) Use the `body_content` field to provide a single string of raw HTML. The HTML is wrapped in an `htmlSnippet` block internally. This is useful when you have pre-built HTML content or are migrating from another platform. ### 3. HTML blocks within blocks Use `type: html` blocks inside the `blocks` array to embed raw HTML snippets alongside other structured blocks. This lets you mix structured content (paragraphs, images, etc.) with custom HTML where needed. ## CSS and styling guardrails beehiiv processes all HTML content through a sanitization pipeline. When using `body_content` or `html` blocks, be aware of the following: - **`<style>` tags are removed.** All `<style>` block elements are stripped during sanitization. Do not rely on embedded stylesheets. - **`<link>` tags are removed.** External stylesheet references are not allowed. - **Inline styles are preserved.** Styles applied directly to elements via the `style` attribute (e.g., `<div style="color: red;">`) are kept intact. - **CSS classes have no effect.** While class attributes are not stripped, no corresponding stylesheets are loaded to apply them. - **beehiiv's email template wraps your content.** Your HTML is rendered inside beehiiv's email table structure, which applies its own layout and spacing. This may affect the appearance of your content. - **Use inline styles for all visual styling.** Since `<style>` and `<link>` tags are removed, inline styles on individual elements are the only reliable way to control appearance.

Create a new segment.<br><br> **Manual segments** — Use `subscriptions` or `emails` input to create a segment from an explicit list of subscription IDs or email addresses. The segment is processed synchronously and returns with `status: completed`. Net new email addresses will be ignored; create subscriptions using the `Create Subscription` endpoint.<br><br> **Dynamic segments** — Use `custom_fields` input to create a segment that filters subscribers by custom field values. The segment is processed asynchronously and returns with `status: pending`. Results will be available in the `List Segment Subscribers` endpoint after processing is complete.

Create new subscriptions for a publication.

Adds tags to a subscription. If the tag does not exist on the publication, it will be created automatically.

Create a new tier for a publication.

Create a new webhook for a given publication.

Generate a URL to preview a post as a given audience. The returned `preview_url` renders the post in the beehiiv app and requires a beehiiv session with access to the publication - it is not itself an HTML-returning endpoint.

Retrieve all publications in the workspace that have a subscription for the specified email address. The workspace is determined by the provided API key.

Bulk update multiple subscriptions fields, including status, custom fields, and tiers.

Update a custom field on a publication.

Update a single subscription.

Update an existing tier belonging to a specific publication

Bulk update subscriptions' status.

Recalculates a specific segment belonging to a publication

Retrieve a single author from a publication.

Send a test email for a specific post to one or more email addresses. Returns the number of remaining test sends for the day and the time at which the limit resets.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Update a newsletter list belonging to a specific publication.

Update a single subscription by email.

<Note title="Currently in beta" icon="b"> Newsletter Lists is currently in beta, the API is subject to change. </Note> Update a newsletter list subscription by subscription ID. An alternative to the update endpoint when you don't have the newsletter list subscription ID. Accepts either a subscription_id or email to identify the subscription. Currently supports unsubscribing a subscription from a newsletter list.