基础说明

基础 URLhttps://mail.push.xiaocx.cc/api/

认证方式

所有发信接口均需在 Header 中传 token，值为控制台「API 接口」页生成的 API 秘钥 secret。账户需已配置发件邮箱，并有剩余邮件量。

发信接口

通过模板 ID 向指定收件人发送邮件，支持动态变量和定时发送。

POSThttps://mail.push.xiaocx.cc/api/send_email_v2

请求 Header

参数	必填	说明
`token`	是	API 秘钥 secret。Header 名保持为 `token`。

请求 Body

参数	必填	说明
`temp_id`	是	邮件模板 ID，整数。
`to_email`	是	收件人邮箱。
`content`	否	JSON 字符串，模板变量键值对，例如 `{"name":"张三"}`。
`send_time`	否	定时发送时间，格式 `Y-m-d H:i:s`；不传则立即发送。

响应与错误码

成功响应

{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "task_id": 12345
  }
}

失败响应示例

{
  "status": 0,
  "msg": "请输入收件人邮箱！",
  "data": {
    "error_code": -6
  }
}

data.error_code	说明
`无`	成功，返回 `data.task_id`。
`-100`	未在 Header 中传 `token`。
`-101`	`token` 不合法或未生成 API 秘钥。
`-102`	剩余邮件数不足。
`-103`	`temp_id` 不是合法整数。
`-1`	时间格式不正确。
`-3`	`content` 不是合法 JSON。
`-4`	无模板权限或模板不存在。
`-6`	未传收件人邮箱。

成功判断建议使用：response.status === 1 && response.data && response.data.task_id。

AI/MCP 可复制接入

下面内容可以直接复制给 AI 编程助手、MCP 工具配置、Apifox 或第三方系统。

MCP 工具定义

给 AI Agent 的工具 schema。

{
  "name": "mail_push_send_email",
  "description": "Create an email sending task in mail_push with an existing email template.",
  "inputSchema": {
    "type": "object",
    "required": [
      "apiSecret",
      "temp_id",
      "to_email"
    ],
    "properties": {
      "apiSecret": {
        "type": "string",
        "description": "API secret generated in the mail_push console. Send it as request header token."
      },
      "temp_id": {
        "type": "integer",
        "description": "Email template ID owned by the account."
      },
      "to_email": {
        "type": "string",
        "format": "email",
        "description": "Recipient email address."
      },
      "content": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Template variable values. Example: { \"name\": \"张三\", \"order_no\": \"NO001\" }."
      },
      "send_time": {
        "type": "string",
        "description": "Optional scheduled time in Y-m-d H:i:s. Omit for immediate sending."
      }
    }
  },
  "request": {
    "method": "POST",
    "url": "https://mail.push.xiaocx.cc/api/send_email_v2",
    "headers": {
      "token": "{{apiSecret}}",
      "Content-Type": "application/json;charset=UTF-8"
    },
    "body": {
      "temp_id": "{{temp_id}}",
      "to_email": "{{to_email}}",
      "content": "{{JSON.stringify(content || {})}}",
      "send_time": "{{send_time}}"
    }
  },
  "successCondition": "response.status === 1 && response.data && response.data.task_id"
}

OpenAPI 片段

给 API 网关、Apifox 或代码生成器。

openapi: 3.0.3
info:
  title: mail_push Email API
  version: 1.0.0
servers:
  - url: https://mail.push.xiaocx.cc/api
paths:
  /send_email_v2:
    post:
      summary: Create an email sending task
      security:
        - ApiSecretHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [temp_id, to_email]
              properties:
                temp_id:
                  type: integer
                to_email:
                  type: string
                  format: email
                content:
                  type: string
                  description: JSON string for template variables
                send_time:
                  type: string
                  example: "2026-07-04 10:00:00"
      responses:
        "200":
          description: API response. Success is status=1 and data.task_id is the queued email task id.
components:
  securitySchemes:
    ApiSecretHeader:
      type: apiKey
      in: header
      name: token

curl 调用

命令行最小可用请求。

curl -X POST 'https://mail.push.xiaocx.cc/api/send_email_v2' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'token: MAIL_PUSH_API_SECRET' \
  -d '{
    "temp_id": 1,
    "to_email": "user@example.com",
    "content": "{\"name\":\"张三\",\"order_no\":\"NO001\"}",
    "send_time": "2026-07-04 10:00:00"
  }'

JavaScript 封装

直接放入业务项目的调用函数。

async function sendMailPushEmail({ apiSecret, tempId, toEmail, variables = {}, sendTime = "" }) {
  const response = await fetch("https://mail.push.xiaocx.cc/api/send_email_v2", {
    method: "POST",
    headers: {
      "Content-Type": "application/json;charset=UTF-8",
      "token": apiSecret
    },
    body: JSON.stringify({
      temp_id: tempId,
      to_email: toEmail,
      content: JSON.stringify(variables),
      send_time: sendTime
    })
  });
  const result = await response.json();
  if (result.status !== 1 || !result.data || !result.data.task_id) {
    throw new Error(result.data?.msg || result.msg || "mail_push send failed");
  }
  return result.data.task_id;
}

给 AI 的项目接入提示词

直接复制给 AI

让 AI 在你的项目里封装发信函数或 MCP 工具。

请在当前项目中封装一个 mail_push 发信工具：
1. 接口地址：https://mail.push.xiaocx.cc/api/send_email_v2
2. 请求方法：POST
3. Header：token = 环境变量 MAIL_PUSH_API_SECRET
4. Body 字段：
   - temp_id: 邮件模板 ID，必填，整数
   - to_email: 收件人邮箱，必填
   - content: JSON 字符串，模板变量，例如 {"name":"张三"}
   - send_time: 可选，格式 Y-m-d H:i:s，不传则立即发送
5. 成功判断：HTTP 200 且 response.status === 1 且 response.data.task_id 存在
6. 返回任务或日志 ID：response.data.task_id
7. 不要把 MAIL_PUSH_API_SECRET 写死到代码里，只读取环境变量。

API 接口文档