Webhook 集成
当收到新邮件时，系统会向用户配置并且已启用的 Webhook URL 发送 POST 请求。想要更详细的配置教程与最佳实践，请参考 MoeMail Webhook 接入指南。
请求头
http
Content-Type: application/json
X-Webhook-Event: new_message请求体
json
{
"emailId": "email-uuid",
"messageId": "message-uuid",
"fromAddress": "[email protected]",
"subject": "邮件主题",
"content": "邮件文本内容",
"html": "邮件HTML内容",
"receivedAt": "2024-01-01T12:00:00.000Z",
"toAddress": "[email protected]"
}配置说明
- 点击个人头像，进入个人中心
- 在个人中心启用 Webhook
- 设置接收通知的 URL
- 点击测试按钮验证配置
- 保存配置后即可接收新邮件通知
测试
项目提供了一个简单的测试服务器, 可以通过如下命令运行:
bash
pnpm webhook-test-server测试服务器会在本地启动一个 HTTP 服务器，监听 3001 端口（http://localhost:3001）, 并打印收到的 Webhook 消息详情。
如果需要进行外网测试，可以通过 Cloudflare Tunnel 将服务暴露到外网：
bash
pnpx cloudflared tunnel --url http://localhost:3001注意事项
- Webhook 接口应在 10 秒内响应
- 非 2xx 响应码会触发重试
OpenAPI
本项目提供了 OpenAPI 接口，支持通过 API Key 进行访问。API Key 可以在个人中心页面创建（需要是公爵或皇帝角色）。
使用 API Key
在请求头中添加 API Key：
http
X-API-Key: YOUR_API_KEYAPI 接口
获取系统配置
http
GET /api/config返回响应：
json
{
"defaultRole": "CIVILIAN",
"emailDomains": "moemail.app,example.com",
"adminContact": "[email protected]",
"maxEmails": "10"
}响应字段说明：
defaultRole: 新用户默认角色，可选值：CIVILIAN（平民）、KNIGHT（骑士）、DUKE（公爵）emailDomains: 支持的邮箱域名，多个域名用逗号分隔adminContact: 管理员联系方式maxEmails: 每个用户可创建的最大邮箱数量
创建临时邮箱
http
POST /api/emails/generate
Content-Type: application/json
{
"name": "test",
"expiryTime": 3600000,
"domain": "moemail.app"
}参数说明：
name: 邮箱前缀，可选expiryTime: 有效期（毫秒），可选值：3600000（1小时）、86400000（1天）、604800000（7天）、0（永久）domain: 邮箱域名，可通过/api/config接口获取
返回响应：
json
{
"id": "email-uuid-123",
"email": "[email protected]"
}响应字段说明：
id: 邮箱的唯一标识符email: 创建的邮箱地址
获取邮箱列表
http
GET /api/emails?cursor=xxx参数说明：
cursor: 分页游标，可选
返回响应：
json
{
"emails": [
{
"id": "email-uuid-123",
"address": "[email protected]",
"createdAt": "2024-01-01T12:00:00.000Z",
"expiresAt": "2024-01-02T12:00:00.000Z",
"userId": "user-uuid-456"
}
],
"nextCursor": "encoded-cursor-string",
"total": 5
}响应字段说明：
emails: 邮箱列表数组nextCursor: 下一页游标，用于分页请求total: 邮箱总数量
获取指定邮箱邮件列表
http
GET /api/emails/{emailId}?cursor=xxx参数说明：
emailId: 邮箱的唯一标识符，必填cursor: 分页游标，可选
返回响应：
json
{
"messages": [
{
"id": "message-uuid-789",
"from_address": "[email protected]",
"subject": "邮件主题",
"received_at": 1704110400000
}
],
"nextCursor": "encoded-cursor-string",
"total": 3
}响应字段说明：
messages: 邮件列表数组nextCursor: 下一页游标，用于分页请求total: 邮件总数量
删除邮箱
http
DELETE /api/emails/{emailId}参数说明：
emailId: 邮箱的唯一标识符，必填
返回响应：
json
{
"success": true
}响应字段说明：
success: 删除操作是否成功
获取单封邮件内容
http
GET /api/emails/{emailId}/{messageId}参数说明：
emailId: 邮箱的唯一标识符，必填messageId: 邮件的唯一标识符，必填
返回响应：
json
{
"message": {
"id": "message-uuid-789",
"from_address": "[email protected]",
"subject": "邮件主题",
"content": "邮件文本内容",
"html": "<p>邮件HTML内容</p>",
"received_at": 1704110400000
}
}响应字段说明：
message: 邮件详细信息对象id: 邮件的唯一标识符from_address: 发件人邮箱地址subject: 邮件主题content: 邮件纯文本内容html: 邮件 HTML 内容received_at: 接收时间（时间戳）
创建邮箱分享链接
http
POST /api/emails/{emailId}/share
Content-Type: application/json
{
"expiresIn": 86400000
}参数说明：
emailId: 邮箱的唯一标识符，必填expiresIn: 分享链接有效期（毫秒），0 表示永久有效，可选
返回响应：
json
{
"id": "share-uuid-123",
"emailId": "email-uuid-123",
"token": "abc123def456",
"expiresAt": "2024-01-02T12:00:00.000Z",
"createdAt": "2024-01-01T12:00:00.000Z"
}响应字段说明：
id: 分享记录的唯一标识符emailId: 关联的邮箱 IDtoken: 分享链接的访问令牌expiresAt: 分享链接过期时间，null 表示永久有效createdAt: 创建时间
分享链接访问地址：https://your-domain.com/shared/{token}
获取邮箱的所有分享链接
http
GET /api/emails/{emailId}/share参数说明：
emailId: 邮箱的唯一标识符，必填
返回响应：
json
{
"shares": [
{
"id": "share-uuid-123",
"emailId": "email-uuid-123",
"token": "abc123def456",
"expiresAt": "2024-01-02T12:00:00.000Z",
"createdAt": "2024-01-01T12:00:00.000Z"
}
],
"total": 1
}响应字段说明：
shares: 分享链接列表数组total: 分享链接总数
删除邮箱分享链接
http
DELETE /api/emails/{emailId}/share/{shareId}参数说明：
emailId: 邮箱的唯一标识符，必填shareId: 分享记录的唯一标识符，必填
返回响应：
json
{
"success": true
}响应字段说明：
success: 删除操作是否成功
创建邮件分享链接
http
POST /api/emails/{emailId}/messages/{messageId}/share
Content-Type: application/json
{
"expiresIn": 86400000
}参数说明：
emailId: 邮箱的唯一标识符，必填messageId: 邮件的唯一标识符，必填expiresIn: 分享链接有效期（毫秒），0 表示永久有效，可选
返回响应：
json
{
"id": "share-uuid-456",
"messageId": "message-uuid-789",
"token": "xyz789ghi012",
"expiresAt": "2024-01-02T12:00:00.000Z",
"createdAt": "2024-01-01T12:00:00.000Z"
}响应字段说明：
id: 分享记录的唯一标识符messageId: 关联的邮件 IDtoken: 分享链接的访问令牌expiresAt: 分享链接过期时间，null 表示永久有效createdAt: 创建时间
分享链接访问地址：https://your-domain.com/shared/message/{token}
获取邮件的所有分享链接
http
GET /api/emails/{emailId}/messages/{messageId}/share参数说明：
emailId: 邮箱的唯一标识符，必填messageId: 邮件的唯一标识符，必填
返回响应：
json
{
"shares": [
{
"id": "share-uuid-456",
"messageId": "message-uuid-789",
"token": "xyz789ghi012",
"expiresAt": "2024-01-02T12:00:00.000Z",
"createdAt": "2024-01-01T12:00:00.000Z"
}
],
"total": 1
}响应字段说明：
shares: 分享链接列表数组total: 分享链接总数
删除邮件分享链接
http
DELETE /api/emails/{emailId}/messages/{messageId}/share/{shareId}参数说明：
emailId: 邮箱的唯一标识符，必填messageId: 邮件的唯一标识符，必填shareId: 分享记录的唯一标识符，必填
返回响应：
json
{
"success": true
}响应字段说明：
success: 删除操作是否成功
使用示例
使用 curl 创建临时邮箱：
bash
curl -X POST https://your-domain.com/api/emails/generate \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "test",
"expiryTime": 3600000,
"domain": "moemail.app"
}'使用 JavaScript 获取邮件列表：
javascript
const res = await fetch('https://your-domain.com/api/emails/your-email-id', {
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
});
const data = await res.json();使用 curl 创建邮箱分享链接：
bash
curl -X POST https://your-domain.com/api/emails/your-email-id/share \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expiresIn": 86400000
}'使用 JavaScript 创建邮件分享链接：
javascript
const res = await fetch('https://your-domain.com/api/emails/your-email-id/messages/your-message-id/share', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
expiresIn: 0 // 永久有效
})
});
const data = await res.json();
console.log('分享链接:', `https://your-domain.com/shared/message/${data.token}`);