beehiiv API — list publications, list and look up subscriptions, and create new subscriptions for a publication.

beehiiv

Manage newsletter publications and subscriptions for creators via the beehiiv API.

This tool wraps beehiiv's REST API v2 so an InTouch job or the AI assistant can read your publications, list and look up subscriptions, and add new subscribers — no code required.

Base URL: https://api.beehiiv.com/v2
Auth: Authorization: Bearer <apiKey>
Format: JSON request/response

Operations

Operation	Method & path	What it does
`list-publications`	`GET /publications`	List the publications your API key can access.
`list-subscriptions`	`GET /publications/{publicationId}/subscriptions`	List subscriptions for a publication (optionally narrowed by `email`).
`get-subscription`	`GET /publications/{publicationId}/subscriptions?email=...`	Look up a single subscription by email on a publication.
`create-subscription`	`POST /publications/{publicationId}/subscriptions`	Add (subscribe) a new email to a publication.

Inputs

Input	Required	Used by	Notes
`apiKey`	yes	all	beehiiv API key, sent as a Bearer token.
`operation`	yes	all	One of the operations above.
`publicationId`	conditional	all except list-publications	Prefixed id like `pub_xxxx`.
`email`	conditional	get-subscription, create-subscription	Contact email.
`reactivateExisting`	no	create-subscription	`true` to reactivate an unsubscribed contact.
`sendWelcomeEmail`	no	create-subscription	`true` to send the welcome email.
`utmSource`	no	create-subscription	Acquisition source.
`utmCampaign`	no	create-subscription	Acquisition campaign.
`customFields`	no	create-subscription	JSON array, e.g. `[{"name":"First Name","value":"Jane"}]`.
`limit`	no	list-*	1–100, default 10.

API key setup

Sign in to your beehiiv dashboard.
Go to Settings > Integrations > API.
Create an API key and copy it.
Pass it as the apiKey input. It is sent as Authorization: Bearer <apiKey>.

Find your publicationId (prefixed pub_...) by running list-publications first — each returned publication includes its id.

Examples

List your publications:

{
  "apiKey": "your-beehiiv-api-key",
  "operation": "list-publications",
  "limit": "50"
}

List subscriptions for a publication:

{
  "apiKey": "your-beehiiv-api-key",
  "operation": "list-subscriptions",
  "publicationId": "pub_00000000-0000-0000-0000-000000000000",
  "limit": "25"
}

Look up one subscription by email:

{
  "apiKey": "your-beehiiv-api-key",
  "operation": "get-subscription",
  "publicationId": "pub_00000000-0000-0000-0000-000000000000",
  "email": "[email protected]"
}

Create (subscribe) a new contact:

{
  "apiKey": "your-beehiiv-api-key",
  "operation": "create-subscription",
  "publicationId": "pub_00000000-0000-0000-0000-000000000000",
  "email": "[email protected]",
  "sendWelcomeEmail": "true",
  "utmSource": "intouch",
  "customFields": "[{\"name\":\"First Name\",\"value\":\"Jane\"}]"
}

Output

Every call publishes:

result — the beehiiv API response payload as a JSON string.
status — the HTTP status code (e.g. 200, 201, 400).

On error the tool prints {"error": "<message>"} and exits non-zero, failing the step.