介绍
# Kit
通过托管的 OAuth 身份验证访问 Kit（前身为 ConvertKit）API。管理订阅者、标签、表单、序列、广播、自定义字段和 Webhook。
## 快速开始
```bash # List subscribers python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/kit/v4/subscribers?per_page=10') 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/kit/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Kit API 端点路径。网关将请求代理到 `api.kit.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Kit OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=kit&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 ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'kit'}).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 ```
### 获取连接
```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 ```
**响应：** ```json { "connection": { "connection_id": "cb2025b3-706f-4b5d-87a5-c6809c0c7ec4", "status": "ACTIVE", "creation_time": "2026-02-07T00:04:08.476727Z", "last_updated_time": "2026-02-07T00:05:58.001964Z", "url": "https://connect.maton.ai/?session_token=...", "app": "kit", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```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 ```
### 指定连接
如果您有多个 Kit 连接，请使用 `Maton-Connection` 头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/kit/v4/subscribers') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'cb2025b3-706f-4b5d-87a5-c6809c0c7ec4') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 订阅者
#### 列出订阅者
```bash GET /kit/v4/subscribers ```
查询参数： - `per_page` - 每页结果数（默认：500，最大：1000） - `after` - 下一页的光标 - `before` - 上一页的光标 - `status` - 按状态筛选：`active`、`inactive`、`bounced`、`complained`、`cancelled` 或 `all` - `email_address` - 按特定电子邮件筛选 - `created_after` / `created_before` - 按创建日期筛选 (yyyy-mm-dd) - `updated_after` / `updated_before` - 按更新日期筛选 (yyyy-mm-dd) - `include_total_count` - 包含总数（较慢）
**响应：** ```json { "subscribers": [ { "id": 3914682852, "first_name": "Test User", "email_address": "[email protected]", "state": "active", "created_at": "2026-02-07T00:42:54Z", "fields": {"company": null} } ], "pagination": { "has_previous_page": false, "has_next_page": false, "start_cursor": "WzE0OV0=", "end_cursor": "WzE0OV0=", "per_page": 500 } } ```
#### 获取订阅者
```bash GET /kit/v4/subscribers/{id} ```
#### 创建订阅者
```bash POST /kit/v4/subscribers Content-Type: application/json
{ "email_address": "[email protected]", "first_name": "John" } ```
#### 更新订阅者
```bash PUT /kit/v4/subscribers/{id} Content-Type: application/json
{ "first_name": "Updated Name" } ```
### 标签
#### 列出标签
```bash GET /kit/v4/tags ```
查询参数：`per_page`、`after`、`before`、`include_total_count`
#### 创建标签
```bash POST /kit/v4/tags Content-Type: application/json
{ "name": "new-tag" } ```
**响应：** ```json { "tag": { "id": 15690016, "name": "new-tag", "created_at": "2026-02-07T00:42:53Z" } } ```
#### 更新标签
```bash PUT /kit/v4/tags/{id} Content-Type: application/json
{ "name": "updated-tag-name" } ```
#### 删除标签
```bash DELETE /kit/v4/tags/{id} ```
成功时返回 204 No Content。
#### 为订阅者打标签
```bash POST /kit/v4/tags/{tag_id}/subscribers Content-Type: application/json
{ "email_address": "[email protected]" } ```
#### 移除订阅者的标签
```bash DELETE /kit/v4/tags/{tag_id}/subscribers/{subscriber_id} ```
成功时返回 204 No Content。
#### 列出具有特定标签的订阅者
```bash GET /kit/v4/tags/{tag_id}/subscribers ```
### 表单
#### 列出表单
```bash GET /kit/v4/forms ```
查询参数： - `per_page`、`after`、`before`、`include_total_count` - `status` - 按状态筛选：`active`、`archived`、`trashed` 或 `all` - `type` - `embed` 表示嵌入表单，`hosted` 表示落地页
**响应：** ```json { "forms": [ { "id": 9061198, "name": "Creator Profile", "created_at": "2026-02-07T00:00:32Z", "type": "embed", "format": null, "embed_js": "https://chris-kim-2.kit.com/c682763b07/index.js", "embed_url": "https://chris-kim-2.kit.com/c682763b07", "archived": false, "uid": "c682763b07" } ], "pagination": {...} } ```
#### 将订阅者添加到表单
```bash POST /kit/v4/forms/{form_id}/subscribers Content-Type: application/json
{ "email_address": "[email protected]" } ```
#### 列出表单订阅者
```bash GET /kit/v4/forms/{form_id}/subscribers ```
### 序列
#### 列出序列
```bash GET /kit/v4/sequences ```
**响应：** ```json { "sequences": [ { "id": 123, "name": "Welcome Sequence", "hold": false, "repeat": false, "created_at": "2026-01-01T00:00:00Z" } ], "pagination": {...} } ```
#### 将订阅者添加到序列
```bash POST /kit/v4/sequences/{sequence_id}/subscribers Content-Type: application/json
{ "email_address": "[email protected]" } ```
#### 列出序列订阅者
```bash GET /kit/v4/sequences/{sequence_id}/subscribers ```
### 广播
#### 列出广播
```bash GET /kit/v4/broadcasts ```
查询参数：`per_page`、`after`、`before`、`include_total_count`
**响应：** ```json { "broadcasts": [ { "id": 123, "publication_id": 456, "created_at": "2026-02-07T00:00:00Z", "subject": "My Broadcast", "preview_text": "Preview...", "content": "<p>Content</p>", "public": false, "published_at": null, "send_at": null, "email_template": {"id": 123, "name": "Text only"} } ], "pagination": {...} } ```
### 分组
#### 列出分组
```bash GET /kit/v4/segments ```
查询参数：`per_page`、`after`、`before`、`include_total_count`
### 自定义字段
#### 列出自定义字段
```bash GET /kit/v4/custom_fields ```
**响应：** ```json { "custom_fields": [ { "id": 1192946, "name": "ck_field_1192946_company", "key": "company", "label": "Company" } ], "pagination": {...} } ```
#### 创建自定义字段
```bash POST /kit/v4/custom_fields Content-Type: application/json
{ "label": "Company" } ```
#### 更新自定义字段
```bash PUT /kit/v4/custom_fields/{id} Content-Type: application/json
{ "label": "Company Name" } ```
#### 删除自定义字段
```bash DELETE /kit/v4/custom_fields/{id} ```
成功时返回 204 No Content。
### 购买
#### 列出购买
```bash GET /kit/v4/purchases ```
查询参数：`per_page`、`after`、`before`、`include_total_count`
### 邮件模板
#### 列出邮件模板
```bash GET /kit/v4/email_templates ```
**响应：** ```json { "email_templates": [ { "id": 4956167, "name": "Text only", "is_default": true, "category": "Classic" } ], "pagination": {...} } ```
### Webhooks
#### 列出 Webhooks
```bash GET /kit/v4/webhooks ```
#### 创建 Webhook
```bash POST /kit/v4/webhooks Content-Type: application/json
{ "target_url": "https://example.com/webhook", "event": {"name": "subscriber.subscriber_activate"} } ```
**响应：** ```json { "webhook": { "id": 5291560, "account_id": 2596262, "event": { "name": "subscriber_activate", "initiator_value": null }, "target_url": "https://example.com/webhook" } } ```
#### 删除 Webhook
```bash DELETE /kit/v4/webhooks/{id} ```
成功时返回 204 No Content。
## 分页
Kit 使用基于光标的分页。请将 `after` 和 `before` 查询参数与响应中的光标值一起使用。
```bash GET /kit/v4/subscribers?per_page=100&after=WzE0OV0= ```
响应包含分页信息：
```json { "subscribers": [...], "pagination": { "has_previous_page": false, "has_next_page": true, "start_cursor": "WzE0OV0=", "end_cursor": "WzI0OV0=", "per_page": 100 } } ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/kit/v4/subscribers?per_page=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/kit/v4/subscribers', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'per_page': 10} ) data = response.json() ```
## 注意事项
- Kit API 使用 V4（V3 已弃用） - 订阅者 ID 是整数 - 自定义字段键是根据标签自动生成的 - 批量操作（超过 100 项）是异步处理的 - 删除操作返回 204 No Content 和空正文 - 重要：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确扩展
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Kit 连接 | | 401 | 无效或缺少 Maton API 密钥 | | 403 | 权限不足（请检查 OAuth 范围）| | 404 | 未找到资源 | | 429 | 速率受限 | | 4xx/5xx | 来自 Kit API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```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 ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `kit` 开头。例如：
- 正确：`https://gateway.maton.ai/kit/v4/subscribers` - 错误：`https://gateway.maton.ai/v4/subscribers`
## 资源
- [Kit API 概览](https://developers.kit.com/api-reference/overview) - [Kit API 订阅者](https://developers.kit.com/api-reference/subscribers/list-subscribers) - [Kit API 标签](https://developers.kit.com/api-reference/tags/list-tags) - [Kit API 表单](https://developers.kit.com/api-reference/forms/list-forms) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])