邮件发送系统 API 文档

API 端点

简介基础邮件带附件邮件定时邮件批量邮件查看定时邮件删除定时邮件健康检查

API 简介

本邮件系统提供完整的 RESTful API，使您能够通过编程方式集成邮件发送功能。所有端点都返回 JSON 格式的响应。

基本信息

基础 URL: /api
默认域名: studyhard.qzz.io
内容类型: application/json

POST 发送基础邮件

发送简单的 HTML 或纯文本格式的电子邮件。

端点

/api/emails/send

请求体

{
  "from": "Your Name <your@studyhard.qzz.io>",  // 可选
  "to": "recipient@example.com",                // 必填
  "subject": "Hello World",                     // 必填
  "html": "<p>This is an HTML email</p>",      // html或text至少需要一个
  "text": "This is a plain text email"          // html和text二选一，或者都提供
}

响应

{
  "data": {
    "id": "email_id",
    "from": "Your Name <your@studyhard.qzz.io>",
    "to": "recipient@example.com",
    "subject": "Hello World"
  }
}

POST 发送带附件邮件

发送包含文件附件的电子邮件。

端点

/api/emails/send-with-attachments

请求体

{
  "from": "Your Name <your@studyhard.qzz.io>",  // 可选
  "to": "recipient@example.com",                // 必填
  "subject": "Email with Attachment",           // 必填
  "html": "<p>Please find the attachment</p>", // html或text至少需要一个
  "text": "Please find the attachment",         // html和text二选一，或者都提供
  "attachments": [                              // 必填
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content_here"
    }
  ]
}

响应

{
  "data": {
    "id": "email_id",
    "from": "Your Name <your@studyhard.qzz.io>",
    "to": "recipient@example.com",
    "subject": "Email with Attachment"
  }
}

POST 发送定时邮件

预定在未来某个时间发送的邮件。

端点

/api/emails/schedule

请求体

{
  "from": "Your Name <your@studyhard.qzz.io>",  // 可选
  "to": "recipient@example.com",                // 必填
  "subject": "Scheduled Email",                 // 必填
  "html": "<p>This is a scheduled email</p>",  // html或text至少需要一个
  "text": "This is a scheduled email",          // html和text二选一，或者都提供
  "scheduledAt": "2023-12-31 23:59"            // 必填，格式为 YYYY-MM-DD HH:MM
}

响应

{
  "data": {
    "id": "scheduled_email_id",
    "scheduledTime": "2023-12-31T23:59:00.000Z"
  },
  "message": "邮件已成功安排在 2023-12-31 23:59 发送"
}

POST 发送批量邮件

同时向多个收件人发送相同内容的邮件。

端点

/api/emails/send-bulk

请求体

{
  "from": "Your Name <your@studyhard.qzz.io>",             // 可选
  "recipients": [                                       // 必填
    "recipient1@example.com",
    "recipient2@example.com",
    "recipient3@example.com"
  ],
  "subject": "Bulk Email",                              // 必填
  "html": "<p>This is a bulk email to multiple recipients</p>", // html或text至少需要一个
  "text": "This is a bulk email to multiple recipients"  // html和text二选一，或者都提供
}

响应

{
  "data": {
    "id": "email_id",
    "from": "Your Name <your@studyhard.qzz.io>",
    "to": ["recipient1@example.com", "recipient2@example.com", "recipient3@example.com"],
    "subject": "Bulk Email"
  }
}

GET 获取定时邮件列表

查看所有已安排的定时邮件。

端点

/api/emails/scheduled

响应

{
  "data": [
    {
      "id": "scheduled_email_id_1",
      "from": "Your Name <your@studyhard.qzz.io>",
      "to": "recipient@example.com",
      "subject": "Scheduled Email 1",
      "html": "<p>This is a scheduled email</p>",
      "scheduledTime": "2023-12-31T23:59:00.000Z",
      "createdAt": "2023-12-01T10:00:00.000Z",
      "status": "scheduled",
      "sent": false
    },
    {
      "id": "scheduled_email_id_2",
      "from": "Your Name <your@studyhard.qzz.io>",
      "to": "recipient@example.com",
      "subject": "Scheduled Email 2",
      "html": "<p>This is another scheduled email</p>",
      "scheduledTime": "2024-01-01T12:00:00.000Z",
      "createdAt": "2023-12-01T10:30:00.000Z",
      "status": "scheduled",
      "sent": false
    }
  ]
}

DELETE 删除定时邮件

取消并删除已安排的定时邮件。

端点

/api/emails/scheduled/:id

参数

:id - 定时邮件的唯一标识符

响应

{
  "success": true,
  "message": "定时邮件 scheduled_email_id 已删除"
}

GET 健康检查

检查API服务状态和待发送的定时邮件数量。

端点

/api/health

响应

{
  "status": "healthy",
  "pendingScheduledEmails": 2,
  "serverTime": "2023-12-01T12:00:00.000Z",
  "storage": "Cloudflare KV"
}