beehiiv

**Quick judgement** A strong, fairly comprehensive beehiiv integration built on the Maton gateway. It is well-suited for production-grade newsletter automation and subscriber management, provided you are comfortable relying on Maton as an intermediary and managing API keys and OAuth connections. **What it does well** - Exposes most of the beehiiv API surface via a consistent `/beehiiv/v2/{resource}` proxy. - Handles OAuth for beehiiv through Maton, simplifying token management for agents. - Offers detailed, concrete examples (Python, JS, curl) and clear parameter docs for publications, subscriptions, posts, custom fields, segments, tiers, automations, and referral programs. - Supports cursor-based pagination, which is important for large subscriber lists and bulk sync tasks. **Key risks and limitations** - **Third-party dependency**: All calls route through Maton (`gateway.maton.ai` and `ctrl.maton.ai`). Outages or API changes on Maton’s side can affect reliability even if beehiiv itself is up. - **Credential management**: Requires a valid MATON_API_KEY and proper handling of the Maton-Connection header for multi-account setups. Misconfiguration can cause 401/403 errors or operate on the wrong beehiiv account. - **Powerful write access**: Endpoints can create, update, and delete subscribers, posts, custom fields, segments, and tiers. Poorly designed automations could unintentionally remove or spam subscribers or alter monetization tiers. - **Rate limits and plan constraints**: Explicit 429 (rate limited) and 403 (permissions/plan) paths mean automations should be designed defensively with retries/backoff and error handling. **Recommended scenarios** Use this skill when: - You want to automate **subscriber management** (add/update/remove subscribers, manage statuses, handle reactivation) in beehiiv. - You need to **sync user data** (e.g., names, company, plan tiers) into beehiiv **custom fields** for segmentation and targeting. - You are building **internal operations tools** for marketing/editorial teams to inspect publications, subscriptions, segments, tiers, and automations. - You need an agent to coordinate **newsletter monetization** via tiers and to interact with **referral programs**. Avoid or use with extra care when: - You cannot or do not want to depend on a third-party gateway (Maton) for access to beehiiv. - You do not have secure processes in place for managing and rotating API keys. - You want read-only analytics only and are uncomfortable exposing write-capable operations to an automated agent (in which case, constrain the agent’s available operations carefully).