Mail-for-Good API参考手册：完整端点说明与使用示例
项目地址: https://gitcode.com/gh_mirrors/ma/mail-for-good Mail-for-Good是一款专为非营利组织设计的开源电子邮件活动管理工具，提供了丰富的API接口用于管理邮件活动、订阅列表、用户权限等核心功能。本手册将详细介绍所有可用API端点的使用方法，帮助开发者快速集成和扩展系统功能。
1. API基础信息
1.1 基础URL
所有API端点均以应用服务器地址为基础，默认路径前缀为/api。
1.2 认证方式
- 使用JWT令牌进行认证
- 在请求头中添加：
Authorization: Bearer {token}
1.3 响应格式
所有API响应均采用JSON格式，包含以下基本结构：
{
"success": true,
"data": {},
"message": "操作成功"
}
2. 邮件活动API
2.1 创建邮件活动
请求：POST /api/campaigns
请求体：
{
"name": "年度筹款活动",
"subject": "支持我们的公益项目",
"templateId": 1,
"listIds": [1, 2],
"scheduledTime": "2023-12-01T08:00:00Z"
}
响应：返回创建的活动信息，包含活动ID和状态。
图：Mail-for-Good创建邮件活动表单界面
2.2 获取活动列表
请求：GET /api/campaigns
查询参数：
page: 页码（默认1）limit: 每页数量（默认20）status: 活动状态（可选：draft, scheduled, sending, sent, cancelled）
响应：返回活动列表及分页信息。
2.3 发送邮件活动
请求：POST /api/campaigns/{id}/send
响应：返回发送状态和任务ID。
2.4 停止邮件发送
请求：POST /api/campaigns/{id}/stop
响应：返回停止操作结果。
3. 订阅列表API
3.1 创建订阅列表
请求：POST /api/lists
请求体：
{
"name": "月度通讯订阅者",
"description": "接收月度公益项目进展的订阅者列表"
}
响应：返回创建的列表信息。
3.2 添加订阅者
请求：POST /api/lists/{id}/subscribers
请求体：
{
"subscribers": [
{"email": "user1@example.com", "name": "张三"},
{"email": "user2@example.com", "name": "李四"}
]
}
响应：返回添加结果，包含成功和失败的订阅者数量。
3.3 导出订阅者
请求：GET /api/lists/{id}/export
响应：返回CSV格式的订阅者数据文件。
4. 模板管理API
4.1 创建邮件模板
请求：POST /api/templates
请求体：
{
"name": "季度报告模板",
"subject": "【{{organization}}】季度项目进展报告",
"htmlContent": "<html>...</html>",
"plainContent": "纯文本内容..."
}
响应：返回创建的模板信息。
4.2 获取模板列表
请求：GET /api/templates
响应：返回所有可用模板列表。
5. 用户权限API
5.1 授予权限
请求：POST /api/permissions/grant
请求体：
{
"userId": 2,
"resourceType": "campaign",
"resourceId": 5,
"permission": "edit"
}
响应：返回权限授予结果。
5.2 获取权限列表
请求：GET /api/permissions
响应：返回当前用户拥有的所有权限。
6. 分析数据API
6.1 获取活动统计
请求：GET /api/analytics/campaigns/{id}
响应：返回邮件打开率、点击率等统计数据。
图：Mail-for-Good邮件活动数据分析仪表板
6.2 获取点击数据
请求：GET /api/analytics/campaigns/{id}/clicks
响应：返回邮件中各链接的点击数据。
7. 错误处理
API可能返回的常见错误码：
400: 请求参数错误401: 未授权访问403: 权限不足404: 资源不存在500: 服务器内部错误
错误响应格式：
{
"success": false,
"error": {
"code": "INVALID_PARAM",
"message": "无效的电子邮件地址"
}
}
8. 快速开始指南
8.1 安装与配置
- 克隆仓库：
git clone https://gitcode.com/gh_mirrors/ma/mail-for-good - 安装依赖：
npm install - 配置环境变量：复制
.env.example为.env并修改配置 - 启动服务：
npm start
8.2 第一个API请求
使用curl测试API连接：
curl -X GET http://localhost:3000/api/campaigns \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
9. API文档与资源
- 完整API文档：docs/local-deployment-guide.md
- API源码实现：server/routes/
- 控制器实现：server/controllers/
通过以上API，开发者可以灵活地扩展Mail-for-Good的功能，实现与其他系统的集成，为非营利组织提供更强大的邮件营销解决方案。如有任何问题，请参考项目文档或提交issue获取支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
