Introduction
# beehiiv
Access the beehiiv API with managed OAuth authentication. Manage newsletter publications, subscriptions, posts, custom fields, segments, tiers, and automations.
## Quick Start
```bash # List publications python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/beehiiv/v2/publications') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/beehiiv/{native-api-path} ```
Replace `{native-api-path}` with the actual beehiiv API endpoint path. The gateway proxies requests to `api.beehiiv.com` and automatically injects your OAuth token.
## Authentication
All requests require the Maton API key in the Authorization header:
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your beehiiv OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=beehiiv&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'beehiiv'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Get Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**Response:** ```json { "connection": { "connection_id": "8bfe17f4-0038-4cbd-afb4-907b1ffa9d66", "status": "ACTIVE", "creation_time": "2026-02-11T00:25:10.464852Z", "last_updated_time": "2026-02-11T00:27:00.816431Z", "url": "https://connect.maton.ai/?session_token=...", "app": "beehiiv", "metadata": {} } } ```
Open the returned `url` in a browser to complete OAuth authorization.
### Delete Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Specifying Connection
If you have multiple beehiiv connections, specify which one to use with the `Maton-Connection` header:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/beehiiv/v2/publications') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '8bfe17f4-0038-4cbd-afb4-907b1ffa9d66') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
All beehiiv API endpoints follow this pattern:
``` /beehiiv/v2/{resource} ```
---
## Publications
### List Publications
```bash GET /beehiiv/v2/publications ```
**Query Parameters:**
| Parameter | Description | |-----------|-------------| | `limit` | Results per page (1-100, default: 10) | | `page` | Page number (default: 1) | | `expand[]` | Expand with: `stats`, `stat_active_subscriptions`, `stat_average_open_rate`, etc. | | `order_by` | Sort by: `created` or `name` | | `direction` | Sort direction: `asc` or `desc` |
**Response:** ```json { "data": [ { "id": "pub_c6c521e4-91ac-4c14-8a52-06987b7e32f2", "name": "My Newsletter", "organization_name": "My Organization", "referral_program_enabled": true, "created": 1770767522 } ], "page": 1, "limit": 10, "total_results": 1, "total_pages": 1 } ```
### Get Publication
```bash GET /beehiiv/v2/publications/{publication_id} ```
---
## Subscriptions
### List Subscriptions
```bash GET /beehiiv/v2/publications/{publication_id}/subscriptions ```
**Query Parameters:**
| Parameter | Description | |-----------|-------------| | `limit` | Results per page (1-100, default: 10) | | `cursor` | Cursor for pagination (recommended) | | `page` | Page number (deprecated, max 100 pages) | | `email` | Filter by exact email (case-insensitive) | | `status` | Filter: `validating`, `invalid`, `pending`, `active`, `inactive`, `all` | | `tier` | Filter: `free`, `premium`, `all` | | `expand[]` | Expand with: `stats`, `custom_fields`, `referrals` | | `order_by` | Sort field (default: `created`) | | `direction` | Sort direction: `asc` or `desc` |
**Response:** ```json { "data": [ { "id": "sub_c27d9640-f418-43a8-a0f9-528c20a05002", "email": "[email protected]", "status": "active", "created": 1770767524, "subscription_tier": "free", "subscription_premium_tier_names": [], "utm_source": "direct", "utm_medium": "", "utm_channel": "website", "utm_campaign": "", "referring_site": "", "referral_code": "gBZbSVal1X", "stripe_customer_id": "" } ], "limit": 10, "has_more": false, "next_cursor": null } ```
### Get Subscription by ID
```bash GET /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id} ```
**Query Parameters:**
| Parameter | Description | |-----------|-------------| | `expand[]` | Expand with: `stats`, `custom_fields`, `referrals`, `tags` |
### Get Subscription by Email
```bash GET /beehiiv/v2/publications/{publication_id}/subscriptions/by_email/{email} ```
### Create Subscription
```bash POST /beehiiv/v2/publications/{publication_id}/subscriptions Content-Type: application/json
{ "email": "[email protected]", "utm_source": "api", "send_welcome_email": false, "reactivate_existing": false } ```
**Request Body:**
| Field | Type | Required | Description | |-------|------|----------|-------------| | `email` | string | Yes | Subscriber email address | | `reactivate_existing` | boolean | No | Reactivate if previously unsubscribed | | `send_welcome_email` | boolean | No | Send welcome email | | `utm_source` | string | No | UTM source for tracking | | `utm_medium` | string | No | UTM medium | | `referring_site` | string | No | Referral code of referring subscriber | | `custom_fields` | object | No | Custom field values (fields must exist) | | `double_opt_override` | string | No | `on` or `off` to override double opt-in | | `tier` | string | No | Subscription tier | | `premium_tier_names` | array | No | Premium tier names to assign |
### Update Subscription
```bash PATCH /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id} Content-Type: application/json
{ "utm_source": "updated-source", "custom_fields": [ {"name": "First Name", "value": "John"} ] } ```
### Delete Subscription
```bash DELETE /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id} ```
---
## Posts
### List Posts
```bash GET /beehiiv/v2/publications/{publication_id}/posts ```
**Query Parameters:**
| Parameter | Description | |-----------|-------------| | `limit` | Results per page (1-100, default: 10) | | `page` | Page number | | `status` | Filter by status | | `expand[]` | Expand with additional data |
**Response:** ```json { "data": [], "page": 1, "limit": 10, "total_results": 0, "total_pages": 0 } ```
### Get Post
```bash GET /beehiiv/v2/publications/{publication_id}/posts/{post_id} ```
### Delete Post
```bash DELETE /beehiiv/v2/publications/{publication_id}/posts/{post_id} ```
---
## Custom Fields
### List Custom Fields
```bash GET /beehiiv/v2/publications/{publication_id}/custom_fields ```
**Response:** ```json { "data": [ { "id": "95c9653f-a1cf-45f0-a140-97feef19057b", "kind": "string", "display": "Last Name", "created": 1770767523 }, { "id": "4cfe081e-c89b-4da5-9c1a-52a4fb8ba69e", "kind": "string", "display": "First Name", "created": 1770767523 } ], "page": 1, "limit": 10, "total_results": 2, "total_pages": 1 } ```
**Field Kinds:** `string`, `integer`, `boolean`, `date`, `datetime`, `list`, `double`
### Create Custom Field
```bash POST /beehiiv/v2/publications/{publication_id}/custom_fields Content-Type: application/json
{ "display": "Company", "kind": "string" } ```
### Update Custom Field
```bash PATCH /beehiiv/v2/publications/{publication_id}/custom_fields/{custom_field_id} Content-Type: application/json
{ "display": "Company Name" } ```
### Delete Custom Field
```bash DELETE /beehiiv/v2/publications/{publication_id}/custom_fields/{custom_field_id} ```
---
## Segments
### List Segments
```bash GET /beehiiv/v2/publications/{publication_id}/segments ```
**Response:** ```json { "data": [], "page": 1, "limit": 10, "total_results": 0, "total_pages": 0 } ```
### Get Segment
```bash GET /beehiiv/v2/publications/{publication_id}/segments/{segment_id} ```
### Delete Segment
```bash DELETE /beehiiv/v2/publications/{publication_id}/segments/{segment_id} ```
---
## Tiers
### List Tiers
```bash GET /beehiiv/v2/publications/{publication_id}/tiers ```
### Get Tier
```bash GET /beehiiv/v2/publications/{publication_id}/tiers/{tier_id} ```
### Create Tier
```bash POST /beehiiv/v2/publications/{publication_id}/tiers Content-Type: application/json
{ "name": "Premium", "description": "Premium tier with exclusive content" } ```
### Update Tier
```bash PATCH /beehiiv/v2/publications/{publication_id}/tiers/{tier_id} Content-Type: application/json
{ "name": "Updated Tier Name" } ```
---
## Automations
### List Automations
```bash GET /beehiiv/v2/publications/{publication_id}/automations ```
### Get Automation
```bash GET /beehiiv/v2/publications/{publication_id}/automations/{automation_id} ```
---
## Referral Program
### Get Referral Program
```bash GET /beehiiv/v2/publications/{publication_id}/referral_program ```
---
## Pagination
beehiiv supports two pagination methods:
### Cursor-Based (Recommended)
```bash GET /beehiiv/v2/publications/{publication_id}/subscriptions?limit=10&cursor={next_cursor} ```
**Response includes:** ```json { "data": [...], "limit": 10, "has_more": true, "next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTA3LTAyVDE3OjMwOjAwLjAwMDAwMFoifQ==" } ```
Use the `next_cursor` value for subsequent requests.
### Page-Based (Deprecated)
```bash GET /beehiiv/v2/publications?page=2&limit=10 ```
**Response includes:** ```json { "data": [...], "page": 2, "limit": 10, "total_results": 50, "total_pages": 5 } ```
**Note:** Page-based pagination is limited to 100 pages maximum.
## Code Examples
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/beehiiv/v2/publications', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); console.log(data.data); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/beehiiv/v2/publications', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() for pub in data['data']: print(f"{pub['id']}: {pub['name']}") ```
## Notes
- Publication IDs start with `pub_` - Subscription IDs start with `sub_` - Timestamps are Unix timestamps (seconds since epoch) - Custom fields must be created before use in subscriptions - Cursor-based pagination is recommended for better performance - Page-based pagination is deprecated and limited to 100 pages - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments
## Error Handling
| Status | Meaning | |--------|---------| | 400 | Bad request or invalid parameters | | 401 | Invalid or missing Maton API key | | 403 | Forbidden - insufficient permissions or plan limitation | | 404 | Resource not found | | 429 | Rate limited | | 500 | Internal server error |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `beehiiv`. For example:
- Correct: `https://gateway.maton.ai/beehiiv/v2/publications` - Incorrect: `https://gateway.maton.ai/v2/publications`
## Resources
- [beehiiv Developer Documentation](https://developers.beehiiv.com/) - [beehiiv API Reference](https://developers.beehiiv.com/api-reference) - [beehiiv Help Center](https://beehiivhelp.zendesk.com/) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])