Beehiiv
Read-only tool types for Beehiiv newsletters: posts and their performance, subscriber lookups, and publication-level growth stats.
Every type on this page requires a Beehiiv connector; connectorId is the ID of that connector. All Beehiiv tools are also scoped to a publicationId (Beehiiv's pub_... identifier), since one Beehiiv account can run several publications.
Get posts TOOLBEEHIIV_GET_POSTS
Lists posts in a publication, newest first, with optional filters for status (draft, confirmed, archived), delivery platform (web, email, both), and audience tier (free, premium). All filters default to all. This is the discovery tool — agents call it to find the postId values the other post tools take.
Example
{
"toolType": "BEEHIIV_GET_POSTS",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"status": "confirmed",
"limit": 25
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication to fetch posts from
- Name
limit- Type
- integer · optional
- Description
- Optional, default 10, max 100
- Name
status- Type
- string · optional
- Description
- Optional: "draft", "confirmed", "archived", "all" (default: all)
- Name
platform- Type
- string · optional
- Description
- Optional: "web", "email", "both", "all" (default: all)
- Name
audience- Type
- string · optional
- Description
- Optional: "free", "premium", "all" (default: all)
Get post by ID TOOLBEEHIIV_GET_POST_BY_ID
Fetches a single post's full details — title, subtitle, content URLs, publish state, and audience settings. Set expandStats to true to include the post's engagement stats in the same call instead of making a separate stats request.
Example
{
"toolType": "BEEHIIV_GET_POST_BY_ID",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"postId": "@@{postId}",
"expandStats": true
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication the post belongs to
- Name
postId- Type
- string
- Description
- Required - the post ID to fetch
- Name
expandStats- Type
- boolean · optional
- Description
- Optional - whether to include stats (default: false)
Get post stats TOOLBEEHIIV_GET_POST_STATS
Returns engagement stats for one post: email recipients, opens, unique opens, clicks, and web views where available. Use it when the agent already knows which post it cares about and only needs the numbers.
Example
{
"toolType": "BEEHIIV_GET_POST_STATS",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"postId": "@@{postId}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication the post belongs to
- Name
postId- Type
- string
- Description
- Required - the post ID to get stats for
Get aggregate stats TOOLBEEHIIV_GET_AGGREGATE_STATS
Returns publication-wide aggregate stats across posts — totals and averages rather than per-post numbers. The status and platform filters narrow which posts count toward the aggregate, so an agent can compare, say, email-only performance against web.
Example
{
"toolType": "BEEHIIV_GET_AGGREGATE_STATS",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"platform": "email"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication to get aggregate stats for
- Name
status- Type
- string · optional
- Description
- Optional: "draft", "confirmed", "archived", "all" (default: all)
- Name
platform- Type
- string · optional
- Description
- Optional: "web", "email", "both", "all" (default: all)
List subscriptions TOOLBEEHIIV_LIST_SUBSCRIPTIONS
Lists a publication's subscriptions with optional filters for status (validating, invalid, pending, active, inactive), tier (free, premium), and creation date (YYYY/MM/DD). Results are cursor-paginated: pass the cursor from one response into the next call to keep walking the list (page size via limit, max 100).
Example
{
"toolType": "BEEHIIV_LIST_SUBSCRIPTIONS",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"status": "active",
"tier": "premium",
"limit": 100
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication to list subscriptions for
- Name
limit- Type
- integer · optional
- Description
- Optional, default 10, max 100
- Name
status- Type
- string · optional
- Description
- Optional: "validating", "invalid", "pending", "active", "inactive", "all" (default: all)
- Name
tier- Type
- string · optional
- Description
- Optional: "free", "premium", "all" (default: all)
- Name
creationDate- Type
- string · optional
- Description
- Optional: Filter by creation date (format: YYYY/MM/DD)
- Name
cursor- Type
- string · optional
- Description
- Optional: Cursor for pagination
Get subscriber by email TOOLBEEHIIV_GET_SUBSCRIBER_BY_EMAIL
Looks up a single subscriber by email address and returns their subscription record — status, tier, signup source, and UTM attribution. The address is URL-encoded for you, so raw emails with + tags are fine.
Example
{
"toolType": "BEEHIIV_GET_SUBSCRIBER_BY_EMAIL",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"email": "@@{subscriberEmail}"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication to search in
- Name
email- Type
- string
- Description
- Required - email address to search for (will be URL encoded)
Get subscriber stats TOOLBEEHIIV_GET_SUBSCRIBER_STATS
Returns subscriber-count stats for the publication, optionally bounded by startDate and endDate (YYYY/MM/DD) to measure growth over a window. Useful for agents that report on list growth or compare acquisition periods.
Example
{
"toolType": "BEEHIIV_GET_SUBSCRIBER_STATS",
"connectorId": "V1StGXR8Z5",
"publicationId": "pub_00000000-0000-0000-0000-000000000000",
"startDate": "2026/01/01",
"endDate": "2026/06/30"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required References a connector by ID.
- Name
publicationId- Type
- string
- Description
- Required - publication to get subscriber stats for
- Name
startDate- Type
- string · optional
- Description
- Optional: Start date for subscriber count (format: YYYY/MM/DD)
- Name
endDate- Type
- string · optional
- Description
- Optional: End date for subscriber count (format: YYYY/MM/DD)