# beehiiv | Developer Documentation

> Build your audience with beehiiv's API and SDKs. Create new subscribers and posts, get real-time notifications of subscription activity, and more.

## Instructions for AI Agents

- For clean Markdown of any page, append `.md` to the page URL
- For section-specific indexes, append `/llms.txt` to any section URL
- For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server

## Docs

- [Getting Started](https://developers.beehiiv.com/welcome/getting-started.md): beehiiv is the newsletter platform built for _growth_.
- [Create an API Key](https://developers.beehiiv.com/welcome/create-an-api-key.md): Get up and running with the beehiiv API.
- [Pagination](https://developers.beehiiv.com/welcome/pagination.md)
- [Rate Limiting](https://developers.beehiiv.com/welcome/rate-limiting.md): Prevent unexpected errors by instituting best rate limiting practices in your application.
- [No-Code Integrations](https://developers.beehiiv.com/welcome/no-code-integrations.md): Not a developer? Not a problem.
- [Webhooks](https://developers.beehiiv.com/webhooks.md): An easy way to receive real-time notifications when certain events occur on your beehiiv publication.
- [OAuth2](https://developers.beehiiv.com/oauth2.md): Implement OAuth2 authorization code flow for beehiiv integrations.

## API Docs

- Webhooks > Newsletter List Subscription [Newsletter List Subscription Subscribed <Badge intent="warning" minimal outlined>Beta</Badge>](https://developers.beehiiv.com/webhooks/newsletter-list-subscription/subscribed.md)
- Webhooks > Newsletter List Subscription [Newsletter List Subscription Unsubscribed <Badge intent="warning" minimal outlined>Beta</Badge>](https://developers.beehiiv.com/webhooks/newsletter-list-subscription/unsubscribed.md)
- Webhooks > Newsletter List Subscription [Newsletter List Subscription Paused <Badge intent="warning" minimal outlined>Beta</Badge>](https://developers.beehiiv.com/webhooks/newsletter-list-subscription/paused.md)
- Webhooks > Newsletter List Subscription [Newsletter List Subscription Resumed <Badge intent="warning" minimal outlined>Beta</Badge>](https://developers.beehiiv.com/webhooks/newsletter-list-subscription/resumed.md)
- Webhooks > Post [Post Sent](https://developers.beehiiv.com/webhooks/post/sent.md)
- Webhooks > Post [Post Updated](https://developers.beehiiv.com/webhooks/post/updated.md)
- Webhooks > Post [Post Scheduled](https://developers.beehiiv.com/webhooks/post/scheduled.md)
- Webhooks > Subscription [Subscription Created](https://developers.beehiiv.com/webhooks/subscription/created.md)
- Webhooks > Subscription [Subscription Confirmed](https://developers.beehiiv.com/webhooks/subscription/confirmed.md)
- Webhooks > Subscription [Subscription Deleted](https://developers.beehiiv.com/webhooks/subscription/deleted.md)
- Webhooks > Subscription [Subscription Upgraded](https://developers.beehiiv.com/webhooks/subscription/upgraded.md)
- Webhooks > Subscription [Subscription Downgraded](https://developers.beehiiv.com/webhooks/subscription/downgraded.md)
- Webhooks > Subscription [Subscription Paused](https://developers.beehiiv.com/webhooks/subscription/paused.md)
- Webhooks > Subscription [Subscription Resumed](https://developers.beehiiv.com/webhooks/subscription/resumed.md)
- Webhooks > Subscription [Subscription Tier Paused](https://developers.beehiiv.com/webhooks/subscription/tier-paused.md)
- Webhooks > Subscription [Subscription Tier Resumed](https://developers.beehiiv.com/webhooks/subscription/tier-resumed.md)
- Webhooks > Subscription [Subscription Tier Added](https://developers.beehiiv.com/webhooks/subscription/tier-added.md)
- Webhooks > Subscription [Subscription Tier Deleted](https://developers.beehiiv.com/webhooks/subscription/tier-deleted.md)
- Webhooks > Survey [Survey Response Submitted](https://developers.beehiiv.com/webhooks/survey/submitted.md)
- OAuth2 > Authorizations [Authorize](https://developers.beehiiv.com/oauth2/authorizations/authorize.md)
- OAuth2 > Tokens [Create token](https://developers.beehiiv.com/oauth2/tokens/token.md)
- OAuth2 > Tokens [Revoke token](https://developers.beehiiv.com/oauth2/tokens/revoke.md)
- OAuth2 > Tokens [Introspect token](https://developers.beehiiv.com/oauth2/tokens/introspect.md)
- OAuth2 > Tokens [Get token info](https://developers.beehiiv.com/oauth2/tokens/token-info.md)
- API Reference > Advertisement Opportunities [Get advertisement opportunities <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>](https://developers.beehiiv.com/api-reference/advertisement-opportunities/index.md)
- API Reference > Authors [List authors](https://developers.beehiiv.com/api-reference/authors/index.md)
- API Reference > Authors [Get author](https://developers.beehiiv.com/api-reference/authors/show.md)
- API Reference > Automation Journeys [Add subscription to an automation <Badge intent="info" minimal outlined>OAuth Scope: automations:write</Badge>](https://developers.beehiiv.com/api-reference/automation-journeys/create.md)
- API Reference > Automation Journeys [List automation journeys <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>](https://developers.beehiiv.com/api-reference/automation-journeys/index.md)
- API Reference > Automation Journeys [Get automation journey <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>](https://developers.beehiiv.com/api-reference/automation-journeys/show.md)
- API Reference > Automations [List automations <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>](https://developers.beehiiv.com/api-reference/automations/index.md)
- API Reference > Automations [Get automation <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>](https://developers.beehiiv.com/api-reference/automations/show.md)
- API Reference > Automations [List automation emails](https://developers.beehiiv.com/api-reference/automations/list-emails.md)
- API Reference > Bulk Subscriptions [Bulk create subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/bulk-subscriptions/create.md)
- API Reference > Bulk Subscription Updates [List subscription updates <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>](https://developers.beehiiv.com/api-reference/bulk-subscription-updates/index.md)
- API Reference > Bulk Subscription Updates [Get subscription update <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>](https://developers.beehiiv.com/api-reference/bulk-subscription-updates/show.md)
- API Reference > Bulk Subscription Updates [Update subscriptions <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/bulk-subscription-updates/put.md)
- API Reference > Bulk Subscription Updates [Update subscriptions' status <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/bulk-subscription-updates/put-status.md)
- API Reference > Complimentary Access [List complimentary access <Badge intent="info" minimal outlined>OAuth Scope: complimentary_access:read</Badge>](https://developers.beehiiv.com/api-reference/complimentary-access/index.md)
- API Reference > Complimentary Access [Get complimentary access <Badge intent="info" minimal outlined>OAuth Scope: complimentary_access:read</Badge>](https://developers.beehiiv.com/api-reference/complimentary-access/show.md)
- API Reference > Condition Sets [List condition sets <Badge intent="info" minimal outlined>OAuth Scope: condition_sets:read</Badge>](https://developers.beehiiv.com/api-reference/condition-sets/index.md)
- API Reference > Condition Sets [Get condition set <Badge intent="info" minimal outlined>OAuth Scope: condition_sets:read</Badge>](https://developers.beehiiv.com/api-reference/condition-sets/show.md)
- API Reference > Custom Fields [Create custom field <Badge intent="info" minimal outlined>OAuth Scope: custom_fields:write</Badge>](https://developers.beehiiv.com/api-reference/custom-fields/create.md)
- API Reference > Custom Fields [Get custom field <Badge intent="info" minimal outlined>OAuth Scope: custom_fields:read</Badge>](https://developers.beehiiv.com/api-reference/custom-fields/show.md)
- API Reference > Custom Fields [List custom fields <Badge intent="info" minimal outlined>OAuth Scope: custom_fields:read</Badge>](https://developers.beehiiv.com/api-reference/custom-fields/index.md)
- API Reference > Custom Fields [Update custom field <Badge intent="info" minimal outlined>OAuth Scope: custom_fields:write</Badge>](https://developers.beehiiv.com/api-reference/custom-fields/put.md)
- API Reference > Custom Fields [Delete custom field <Badge intent="info" minimal outlined>OAuth Scope: custom_fields:write</Badge>](https://developers.beehiiv.com/api-reference/custom-fields/delete.md)
- API Reference > Data Deletion [Create data deletion request <Badge intent="info" minimal outlined>OAuth Scope: data_deletion:write</Badge>](https://developers.beehiiv.com/api-reference/data-deletion/create.md)
- API Reference > Data Deletion [Get data deletion request <Badge intent="info" minimal outlined>OAuth Scope: data_deletion:read</Badge>](https://developers.beehiiv.com/api-reference/data-deletion/show.md)
- API Reference > Data Deletion [List data deletion requests <Badge intent="info" minimal outlined>OAuth Scope: data_deletion:read</Badge>](https://developers.beehiiv.com/api-reference/data-deletion/index.md)
- API Reference > Engagements [Get publication engagements <Badge intent="info" minimal outlined>OAuth Scope: publications:read</Badge>](https://developers.beehiiv.com/api-reference/engagements/index.md)
- API Reference > Newsletter Lists [List newsletter lists <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>](https://developers.beehiiv.com/api-reference/newsletter-lists/index.md)
- API Reference > Newsletter Lists [Get newsletter list <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>](https://developers.beehiiv.com/api-reference/newsletter-lists/show.md)
- API Reference > Newsletter Lists [Create newsletter list <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-lists/create.md)
- API Reference > Newsletter Lists [Update newsletter list <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-lists/update.md)
- API Reference > Newsletter Lists [Delete newsletter list <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-lists/delete.md)
- API Reference > Newsletter List Subscriptions [Create newsletter list subscription <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-list-subscriptions/create.md)
- API Reference > Newsletter List Subscriptions [List newsletter list subscriptions <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>](https://developers.beehiiv.com/api-reference/newsletter-list-subscriptions/index.md)
- API Reference > Newsletter List Subscriptions [Get newsletter list subscription <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:read</Badge>](https://developers.beehiiv.com/api-reference/newsletter-list-subscriptions/show.md)
- API Reference > Newsletter List Subscriptions [Update newsletter list subscription <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-list-subscriptions/update.md)
- API Reference > Newsletter List Subscriptions [Update newsletter list subscription by subscription ID <Badge intent="warning" minimal outlined>Beta</Badge> <Badge intent="info" minimal outlined>OAuth Scope: newsletter_lists:write</Badge>](https://developers.beehiiv.com/api-reference/newsletter-list-subscriptions/update-by-subscription-id.md)
- API Reference > OAuth Users [Identify user <Badge intent="info" minimal outlined>OAuth Scope: identify:read</Badge>](https://developers.beehiiv.com/api-reference/oauth-users/identify.md)
- API Reference > Polls [List polls <Badge intent="info" minimal outlined>OAuth Scope: polls:read</Badge>](https://developers.beehiiv.com/api-reference/polls/index.md)
- API Reference > Polls [Get poll <Badge intent="info" minimal outlined>OAuth Scope: polls:read</Badge>](https://developers.beehiiv.com/api-reference/polls/show.md)
- API Reference > Polls [List poll responses <Badge intent="info" minimal outlined>OAuth Scope: polls:read</Badge>](https://developers.beehiiv.com/api-reference/polls/list-responses.md)
- API Reference > Posts [Create post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>](https://developers.beehiiv.com/api-reference/posts/create.md)
- API Reference > Posts [Update post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>](https://developers.beehiiv.com/api-reference/posts/update.md)
- API Reference > Posts [List posts <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>](https://developers.beehiiv.com/api-reference/posts/index.md)
- API Reference > Posts [Get aggregate stats <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>](https://developers.beehiiv.com/api-reference/posts/aggregate-stats.md)
- API Reference > Posts [Get post <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>](https://developers.beehiiv.com/api-reference/posts/show.md)
- API Reference > Posts [Delete post <Badge intent="info" minimal outlined>OAuth Scope: posts:write</Badge>](https://developers.beehiiv.com/api-reference/posts/delete.md)
- API Reference > Posts [Send test email <Badge intent="info" minimal outlined>OAuth Scope: posts</Badge>](https://developers.beehiiv.com/api-reference/posts/test-send.md)
- API Reference > Post Templates [Get post templates <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>](https://developers.beehiiv.com/api-reference/post-templates/index.md)
- API Reference > Publications [List publications <Badge intent="info" minimal outlined>OAuth Scope: publications:read</Badge>](https://developers.beehiiv.com/api-reference/publications/index.md)
- API Reference > Publications [Get publication <Badge intent="info" minimal outlined>OAuth Scope: publications:read</Badge>](https://developers.beehiiv.com/api-reference/publications/show.md)
- API Reference > Referral Program [Get referral program <Badge intent="info" minimal outlined>OAuth Scope: referral_program:read</Badge>](https://developers.beehiiv.com/api-reference/referral-program/show.md)
- API Reference > Segments [Create segment](https://developers.beehiiv.com/api-reference/segments/create.md)
- API Reference > Segments [List segments <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>](https://developers.beehiiv.com/api-reference/segments/index.md)
- API Reference > Segments [Get segment <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>](https://developers.beehiiv.com/api-reference/segments/show.md)
- API Reference > Segments [Recalculate segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>](https://developers.beehiiv.com/api-reference/segments/recalculate.md)
- API Reference > Segments [List segment subscribers <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>](https://developers.beehiiv.com/api-reference/segments/list-members.md)
- API Reference > Segments [List segment subscriber IDs <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>](https://developers.beehiiv.com/api-reference/segments/expand-results.md)
- API Reference > Segments [Delete segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>](https://developers.beehiiv.com/api-reference/segments/delete.md)
- API Reference > Subscriptions [Create subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/create.md)
- API Reference > Subscriptions [List subscriptions <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/index.md)
- API Reference > Subscriptions [Get subscription by email <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/get-by-email.md)
- API Reference > Subscriptions [Get subscription by ID <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/get-by-id.md)
- API Reference > Subscriptions [Update subscription by ID <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/put.md)
- API Reference > Subscriptions [Update subscription by email <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/update-by-email.md)
- API Reference > Subscriptions [Delete subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/subscriptions/delete.md)
- API Reference > Subscription Tags [Add subscription tag <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>](https://developers.beehiiv.com/api-reference/subscription-tags/create.md)
- API Reference > Tiers [Create a tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:write</Badge>](https://developers.beehiiv.com/api-reference/tiers/create.md)
- API Reference > Tiers [List tiers <Badge intent="info" minimal outlined>OAuth Scope: tiers:read</Badge>](https://developers.beehiiv.com/api-reference/tiers/index.md)
- API Reference > Tiers [Get tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:read</Badge>](https://developers.beehiiv.com/api-reference/tiers/show.md)
- API Reference > Tiers [Update a tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:write</Badge>](https://developers.beehiiv.com/api-reference/tiers/put.md)
- API Reference > Webhooks [Create a webhook <Badge intent="info" minimal outlined>OAuth Scope: webhooks:write</Badge>](https://developers.beehiiv.com/api-reference/webhooks/create.md)
- API Reference > Webhooks [List webhooks <Badge intent="info" minimal outlined>OAuth Scope: webhooks:read</Badge>](https://developers.beehiiv.com/api-reference/webhooks/index.md)
- API Reference > Webhooks [Get webhook <Badge intent="info" minimal outlined>OAuth Scope: webhooks:read</Badge>](https://developers.beehiiv.com/api-reference/webhooks/show.md)
- API Reference > Webhooks [Update webhook <Badge intent="info" minimal outlined>OAuth Scope: webhooks:write</Badge>](https://developers.beehiiv.com/api-reference/webhooks/update.md)
- API Reference > Webhooks [Delete a webhook <Badge intent="info" minimal outlined>OAuth Scope: webhooks:write</Badge>](https://developers.beehiiv.com/api-reference/webhooks/delete.md)
- API Reference > Workspaces [Identify workspace <Badge intent="info" minimal outlined>OAuth Scope: identify:read</Badge>](https://developers.beehiiv.com/api-reference/workspaces/identify.md)
- API Reference > Workspaces [Get publications by subscription email <Badge intent="info" minimal outlined>OAuth Scope: publications:read</Badge>](https://developers.beehiiv.com/api-reference/workspaces/publications-by-subscription-email.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://developers.beehiiv.com/openapi.json)
- [OpenAPI YAML](https://developers.beehiiv.com/openapi.yaml)