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

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

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.

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	beehiiv API key. Create one in the beehiiv dashboard under Settings > Integrations > API. Sent as 'Authorization: Bearer '.
`operation`	string	yes	—	One of: list-publications, list-subscriptions, get-subscription, create-subscription
`publicationId`	string	no	—	Prefixed publication id (e.g. pub_xxxx). Required for list-subscriptions, get-subscription, and create-subscription.
`email`	string	no	—	Contact email address. Required for create-subscription and get-subscription (used to look up the subscription on the publication).
`reactivateExisting`	string	no	—	create-subscription only: 'true' to reactivate a previously unsubscribed contact. Leave empty for the beehiiv default (false).
`sendWelcomeEmail`	string	no	—	create-subscription only: 'true' to send the welcome email. Leave empty for the beehiiv default (false).
`utmSource`	string	no	—	create-subscription only: optional acquisition source (utm_source).
`utmCampaign`	string	no	—	create-subscription only: optional acquisition campaign (utm_campaign).
`customFields`	string	no	—	create-subscription only: optional JSON array of custom field objects, e.g. [{"name":"First Name","value":"Jane"}].
`limit`	string	no	`10`	Max records to return for list-publications and list-subscriptions (1-100). Defaults to 10.