基础 URL

https://gateway.maton.ai/beehiiv/{native-api-path}

将 {native-api-path} 替换为实际的 beehiiv API 端点路径。网关将请求代理到 api.beehiiv.com 并自动注入您的 OAuth 令牌。

认证

所有请求都需要在 Authorization 标头中包含 Maton API 密钥：

Authorization: Bearer $MATONAPIKEY

环境变量： 将您的 API 密钥设置为 MATONAPIKEY：

bash
export MATONAPIKEY=YOURAPIKEY

获取您的 API 密钥

1. 1. 在 maton.ai 登录或创建账户
2. 前往 maton.ai/settings
3. 复制您的 API 密钥

连接管理

在 https://ctrl.maton.ai 管理您的 beehiiv OAuth 连接。

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=beehiiv&status=ACTIVE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

bash
python < 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.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：
json
{
connection: {
connection_id: 8bfe17f4-0038-4cbd-afb4-907b1ffa9d66,
status: ACTIVE,
creation_time: 2026-02-11T00:25:10.464852Z,
lastupdatedtime: 2026-02-11T00:27:00.816431Z,
url: https://connect.maton.ai/?session_token=...,
app: beehiiv,
metadata: {}
}
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 beehiiv 连接，请使用 Maton-Connection 标头指定要使用的连接：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/beehiiv/v2/publications)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 8bfe17f4-0038-4cbd-afb4-907b1ffa9d66)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最旧的）活动连接。

API 参考

所有 beehiiv API 端点遵循以下模式：

/beehiiv/v2/{resource}

出版物

列出出版物

bash
GET /beehiiv/v2/publications

查询参数：

响应：
json
{
data: [
{
id: pub_c6c521e4-91ac-4c14-8a52-06987b7e32f2,
name: 我的新闻通讯,
organization_name: 我的组织,
referralprogramenabled: true,
created: 1770767522
}
],
page: 1,
limit: 10,
total_results: 1,
total_pages: 1
}

获取出版物

bash
GET /beehiiv/v2/publications/{publication_id}

订阅

列出订阅

bash
GET /beehiiv/v2/publications/{publication_id}/subscriptions

查询参数：

响应：
json
{
data: [
{
id: sub_c27d9640-f418-43a8-a0f9-528c20a05002,
email: subscriber@example.com,
status: active,
created: 1770767524,
subscription_tier: free,
subscriptionpremiumtier_names: [],
utm_source: direct,
utm_medium: ,
utm_channel: website,
utm_campaign: ,
referring_site: ,
referral_code: gBZbSVal1X,
stripecustomerid:
}
],
limit: 10,
has_more: false,
next_cursor: null
}

按 ID 获取订阅

bash
GET /beehiiv/v2/publications/{publicationid}/subscriptions/{subscriptionid}

查询参数：

按邮箱获取订阅

bash
GET /beehiiv/v2/publications/{publicationid}/subscriptions/byemail/{email}

创建订阅

bash
POST /beehiiv/v2/publications/{publication_id}/subscriptions
Content-Type: application/json

{
email: newsubscriber@example.com,
utm_source: api,
sendwelcomeemail: false,
reactivate_existing: false
}

请求体：