介绍
# Constant Contact
使用托管的 OAuth 身份验证访问 Constant Contact V3 API。管理联系人、电子邮件营销活动、联系人列表、细分市场和营销分析。
## 快速开始
```bash # List contacts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/constant-contact/v3/contacts') 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/constant-contact/v3/{resource} ```
网关将请求代理到 `api.cc.email/v3` 并自动注入您的 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` 管理您的 Constant Contact OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=constant-contact&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': 'constant-contact'}).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": "4314bd0f-fd56-40ab-8c65-2676dd2c23c4", "status": "ACTIVE", "creation_time": "2026-02-07T07:41:05.859244Z", "last_updated_time": "2026-02-07T07:41:32.658230Z", "url": "https://connect.maton.ai/?session_token=...", "app": "constant-contact", "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 ```
### 指定连接
如果您有多个 Constant Contact 连接，请使用 `Maton-Connection` 请求头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/constant-contact/v3/contacts') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '4314bd0f-fd56-40ab-8c65-2676dd2c23c4') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 账户
#### 获取账户摘要
```bash GET /constant-contact/v3/account/summary ```
#### 获取账户电子邮件
```bash GET /constant-contact/v3/account/emails ```
#### 获取用户权限
```bash GET /constant-contact/v3/account/user/privileges ```
### 联系人
#### 列出联系人
```bash GET /constant-contact/v3/contacts ```
查询参数： - `status` - 按状态筛选：`all`、`active`、`deleted`、`not_set`、`pending_confirmation`、`temp_hold`、`unsubscribed` - `email` - 按电子邮件地址筛选 - `lists` - 按列表 ID 筛选 - `segment_id` - 按细分 ID 筛选 - `tags` - 按标签 ID 筛选 - `updated_after` - ISO-8601 日期筛选 - `include` - 包含子资源：`custom_fields`、`list_memberships`、`taggings`、`notes` - `limit` - 每页结果数（默认 50，最大 500）
#### 获取联系人
```bash GET /constant-contact/v3/contacts/{contact_id} ```
#### 创建联系人
```bash POST /constant-contact/v3/contacts Content-Type: application/json
{ "email_address": { "address": "[email protected]", "permission_to_send": "implicit" }, "first_name": "John", "last_name": "Doe", "job_title": "Developer", "company_name": "Acme Inc", "list_memberships": ["list-uuid-here"] } ```
#### 更新联系人
```bash PUT /constant-contact/v3/contacts/{contact_id} Content-Type: application/json
{ "email_address": { "address": "[email protected]" }, "first_name": "John", "last_name": "Smith" } ```
#### 删除联系人
```bash DELETE /constant-contact/v3/contacts/{contact_id} ```
#### 创建或更新联系人（注册表单）
使用此端点创建新联系人或更新现有联系人，而无需先检查其是否存在：
```bash POST /constant-contact/v3/contacts/sign_up_form Content-Type: application/json
{ "email_address": "[email protected]", "first_name": "John", "last_name": "Doe", "list_memberships": ["list-uuid-here"] } ```
#### 获取联系人计数
```bash GET /constant-contact/v3/contacts/counts ```
### 联系人列表
#### 列出联系人列表
```bash GET /constant-contact/v3/contact_lists ```
查询参数： - `include_count` - 包含每个列表的联系人计数 - `include_membership_count` - 包含成员计数 - `limit` - 每页结果数
#### 获取联系人列表
```bash GET /constant-contact/v3/contact_lists/{list_id} ```
#### 创建联系人列表
```bash POST /constant-contact/v3/contact_lists Content-Type: application/json
{ "name": "Newsletter Subscribers", "description": "Main newsletter list", "favorite": false } ```
#### 更新联系人列表
```bash PUT /constant-contact/v3/contact_lists/{list_id} Content-Type: application/json
{ "name": "Updated List Name", "description": "Updated description", "favorite": true } ```
#### 删除联系人列表
```bash DELETE /constant-contact/v3/contact_lists/{list_id} ```
### 标签
#### 列出标签
```bash GET /constant-contact/v3/contact_tags ```
#### 创建标签
```bash POST /constant-contact/v3/contact_tags Content-Type: application/json
{ "name": "VIP Customer" } ```
#### 更新标签
```bash PUT /constant-contact/v3/contact_tags/{tag_id} Content-Type: application/json
{ "name": "Premium Customer" } ```
#### 删除标签
```bash DELETE /constant-contact/v3/contact_tags/{tag_id} ```
### 自定义字段
#### 列出自定义字段
```bash GET /constant-contact/v3/contact_custom_fields ```
#### 创建自定义字段
```bash POST /constant-contact/v3/contact_custom_fields Content-Type: application/json
{ "label": "Customer ID", "type": "string" } ```
#### 删除自定义字段
```bash DELETE /constant-contact/v3/contact_custom_fields/{custom_field_id} ```
### 电子邮件营销活动
#### 列出电子邮件营销活动
```bash GET /constant-contact/v3/emails ```
查询参数： - `limit` - 每页结果数（默认 50）
#### 获取电子邮件营销活动
```bash GET /constant-contact/v3/emails/{campaign_id} ```
#### 创建电子邮件营销活动
```bash POST /constant-contact/v3/emails Content-Type: application/json
{ "name": "March Newsletter", "email_campaign_activities": [ { "format_type": 5, "from_name": "Company Name", "from_email": "[email protected]", "reply_to_email": "[email protected]", "subject": "March Newsletter", "html_content": "<html><body><h1>Hello!</h1></body></html>" } ] } ```
#### 更新电子邮件营销活动
```bash PUT /constant-contact/v3/emails/activities/{campaign_activity_id} Content-Type: application/json
{ "contact_list_ids": ["list-uuid-here"], "from_name": "Updated Name", "subject": "Updated Subject" } ```
#### 发送测试电子邮件
```bash POST /constant-contact/v3/emails/activities/{campaign_activity_id}/tests Content-Type: application/json
{ "email_addresses": ["[email protected]"] } ```
#### 定时发送电子邮件营销活动
```bash POST /constant-contact/v3/emails/activities/{campaign_activity_id}/schedules Content-Type: application/json
{ "scheduled_date": "2026-03-01T10:00:00Z" } ```
### 细分市场
#### 列出细分市场
```bash GET /constant-contact/v3/segments ```
#### 获取细分市场
```bash GET /constant-contact/v3/segments/{segment_id} ```
#### 创建细分市场
```bash POST /constant-contact/v3/segments Content-Type: application/json
{ "name": "Engaged Subscribers", "segment_criteria": "..." } ```
#### 删除细分市场
```bash DELETE /constant-contact/v3/segments/{segment_id} ```
### 批量操作
#### 导入联系人
```bash POST /constant-contact/v3/activities/contacts_file_import Content-Type: multipart/form-data
{file: contacts.csv, list_ids: ["list-uuid"]} ```
#### 将联系人添加到列表
```bash POST /constant-contact/v3/activities/add_list_memberships Content-Type: application/json
{ "source": { "contact_ids": ["contact-uuid-1", "contact-uuid-2"] }, "list_ids": ["list-uuid"] } ```
#### 从列表中移除联系人
```bash POST /constant-contact/v3/activities/remove_list_memberships Content-Type: application/json
{ "source": { "list_ids": ["source-list-uuid"] }, "list_ids": ["target-list-uuid"] } ```
#### 批量删除联系人
```bash POST /constant-contact/v3/activities/contact_delete Content-Type: application/json
{ "contact_ids": ["contact-uuid-1", "contact-uuid-2"] } ```
#### 获取活动状态
```bash GET /constant-contact/v3/activities/{activity_id} ```
#### 列出活动
```bash GET /constant-contact/v3/activities ```
### 报告
#### 电子邮件营销活动摘要
```bash GET /constant-contact/v3/reports/summary_reports/email_campaign_summaries ```
查询参数： - `start` - 开始日期 (ISO-8601) - `end` - 结束日期 (ISO-8601)
#### 获取电子邮件营销活动报告
```bash GET /constant-contact/v3/reports/email_reports/{campaign_activity_id} ```
#### 联系人活动摘要
```bash GET /constant-contact/v3/reports/contact_reports/{contact_id}/activity_summary ```
## 分页
该 API 使用带有 `limit` 参数的基于游标的分页：
```bash GET /constant-contact/v3/contacts?limit=50 ```
响应包含分页链接：
```json { "contacts": [...], "_links": { "next": { "href": "/v3/contacts?cursor=abc123" } } } ```
使用来自 `next` 链接的游标来获取后续页面：
```bash GET /constant-contact/v3/contacts?cursor=abc123 ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/constant-contact/v3/contacts?limit=50', { 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/constant-contact/v3/contacts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'limit': 50} ) data = response.json() ```
## 注意事项
- 资源 ID 使用 UUID 格式（36 个字符，带连字符） - 所有日期使用 ISO-8601 格式：`YYYY-MM-DDThh:mm:ss.sZ` - 每个账户最多 1,000 个联系人列表 - 一个联系人最多可以属于 50 个列表 - 批量操作是异步的 - 请检查活动状态以确认完成情况 - 电子邮件营销活动需要经过验证的发件人电子邮件地址 - `format_type: 5` 用于自定义 HTML 电子邮件 - 重要：使用 curl 命令时，如果 URL 包含方括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，环境变量（如 `$MATON_API_KEY`）在某些 shell 环境中可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Constant Contact 连接或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 令牌已过期 | | 403 | 请求操作的权限不足 | | 404 | 未找到资源 | | 409 | 冲突（例如，电子邮件地址重复） | | 429 | 请求频率受限 | | 4xx/5xx | 来自 Constant Contact API 的透传错误 |
### 错误响应格式
```json { "error_key": "unauthorized", "error_message": "Unauthorized" } ```
### 故障排除：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 路径以 `constant-contact` 开头。例如：
- 正确：`https://gateway.maton.ai/constant-contact/v3/contacts` - 错误：`https://gateway.maton.ai/v3/contacts`
## 资源
- [Constant Contact V3 API 概述](https://developer.constantcontact.com/api_guide/getting_started.html) - [API 参考](https://developer.constantcontact.com/api_reference/index.html) - [技术概述](https://developer.constantcontact.com/api_guide/v3_technical_overview.html) - [联系人概述](https://developer.constantcontact.com/api_guide/contacts_overview.html) - [电子邮件营销活动指南](https://developer.constantcontact.com/api_guide/email_campaigns_get_started.html) - [联系人列表概述](https://v3.developer.constantcontact.com/api_guide/lists_overview.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])