MoeMail

Appearance

Webhook 集成 ​

当收到新邮件时，系统会向用户配置并且已启用的 Webhook URL 发送 POST 请求。想要更详细的配置教程与最佳实践，请参考 MoeMail Webhook 接入指南。

请求头 ​

http
Content-Type: application/json
X-Webhook-Event: new_message

请求体 ​

json
{
  "emailId": "email-uuid",
  "messageId": "message-uuid",
  "fromAddress": "sender@example.com",
  "subject": "邮件主题",
  "content": "邮件文本内容",
  "html": "邮件HTML内容",
  "receivedAt": "2024-01-01T12:00:00.000Z",
  "toAddress": "your-email@moemail.app"
}

配置说明 ​

  1. 点击个人头像，进入个人中心
  2. 在个人中心启用 Webhook
  3. 设置接收通知的 URL
  4. 点击测试按钮验证配置
  5. 保存配置后即可接收新邮件通知

测试 ​

项目提供了一个简单的测试服务器, 可以通过如下命令运行:

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_KEY

API 接口 ​

获取系统配置 ​

http
GET /api/config

返回响应：

json
{
  "defaultRole": "CIVILIAN",
  "emailDomains": "moemail.app,example.com",
  "adminContact": "admin@example.com",
  "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": "test@moemail.app"
}

响应字段说明：

  • id: 邮箱的唯一标识符
  • email: 创建的邮箱地址

获取邮箱列表 ​

http
GET /api/emails?cursor=xxx

参数说明：

  • cursor: 分页游标，可选

返回响应：

json
{
  "emails": [
    {
      "id": "email-uuid-123",
      "address": "test@moemail.app",
      "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": "sender@example.com",
      "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": "sender@example.com",
    "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: 关联的邮箱 ID
  • token: 分享链接的访问令牌
  • 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: 关联的邮件 ID
  • token: 分享链接的访问令牌
  • 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}`);

Released under the MIT License

Copyright © 2024-2025 MoeMail