create and manage subscriber segments via the beehiiv API
domain: developers.beehiiv.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
POST /v2/publications/:publicationId/segments with a name and an input object
For a manual segment, set input.type to "subscriptions" or "emails" with an explicit list — processed synchronously (status: completed)
For a dynamic segment, set input to custom_fields filters — processed asynchronously (status: pending)
Poll GET .../segments/:id until status is completed, then list members via the segment results/expand endpoint
Recalculate a dynamic segment on demand with PUT .../segments/:id/recalculate
Known gotchas
The API only supports custom-field-based conditions for dynamic segments — engagement, tag, or subscription-status conditions from the dashboard builder aren't exposed via API
Manual segments ignore net-new email addresses that aren't already subscribers; create the subscription first
Segment names must be unique per publication or the create call fails
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?