Open API

发送第一封邮件

使用标准 REST API 提交事务邮件。阅读文档无需账号，实际调用需要在用户中心创建 API Key，并完成发件域名验证。

身份认证

所有 Open API 请求都需要通过 HTTP Bearer 方式提交 API Key。Key 只会在创建时完整显示，请勿放入浏览器前端或公开仓库。

Authorization: Bearer mg_your_api_key

POST

/v1/open/emails

提交一封包含主送、抄送、密送、纯文本、HTML、自定义 Header、标签和附件的邮件。

curl -X POST 'https://api.mailgo.fyi/v1/open/emails' \
  -H 'Authorization: Bearer mg_your_api_key' \
  -H 'Idempotency-Key: order-1001-welcome' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "MailGo <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Hello from MailGo",
    "html": "<strong>It works.</strong>",
    "text": "It works."
  }'

字段	类型	说明
from	string	已验证域名下的发件地址
to	string[]	至少一个收件人，全部收件人合计最多 100 个
subject	string	邮件主题，最多 300 个字符
html / text	string	至少提供一种正文格式

幂等发送

Idempotency-Key 是可选请求头，生产环境强烈建议设置。相同 API Key 使用相同幂等键和相同请求时会返回原邮件，不会重复创建、扣减额度或投递；相同键对应不同请求时返回 HTTP 409。

Idempotency-Key: order-1001-welcome

查询邮件

GET/v1/open/emails/{email_id}

使用全权限 API Key，根据发送接口返回的邮件编号查询当前状态、收件人、正文、附件元数据和失败原因。邮件状态包括 queued、scheduled、sending、sent、delivered、failed、canceled、suppressed、retrying 和 partial。

curl 'https://api.mailgo.fyi/v1/open/emails/EMAIL_ID' \
  -H 'Authorization: Bearer mg_your_api_key'

取消邮件

POST/v1/open/emails/{email_id}/cancel

使用全权限 API Key 取消邮件。只有尚未开始投递的 queued、scheduled 或 retrying 邮件可以取消；已经发送或进入最终状态的邮件返回 HTTP 409。

curl -X POST 'https://api.mailgo.fyi/v1/open/emails/EMAIL_ID/cancel' \
  -H 'Authorization: Bearer mg_your_api_key'

附件与定时发送

attachments[].content 使用 Base64，单次请求附件总计不超过 10 MB。设置 content_id 可作为 HTML 内嵌资源。scheduled_at 使用 RFC3339，并限制在未来 30 天内。

响应与错误

请求被接受时返回 HTTP 202。错误响应使用稳定错误码，并通过响应头与 Body 返回可用于排查日志的请求编号。

{
  "error": {
    "code": "domain_not_verified",
    "message": "the sender domain is not verified for sending",
    "request_id": "request-id"
  }
}