Email API

通过代码管理您域名的邮件：付费邮件托管中的邮箱、在 NameOcean 注册的域名的免费转发，以及以 JSON 格式推送到您应用的收到的邮件。

开始之前

创建一个具有 email:read 权限的 API 密钥，如需进行更改，还需 email:write 权限。所有端点均可在 API 参考和 OpenAPI 文件中查看。购买、升级和续费邮件套餐会消耗账户余额，需在控制面板中操作。

邮箱

邮件域名的套餐包含一定的存储空间，由其下所有邮箱共享。创建邮箱时若不设置密码，系统将自动生成一个；该密码仅在此次响应中由 API 返回。

curl

$ curl -X POST https://nameocean.net/api/v1/email/domains/example.com/mailboxes \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"username": "info", "full_name": "Info", "quota_gb": 2}'

{"address": "info@example.com", "username": "info", "full_name": "Info", "quota_gb": 2,
 "used_gb": "0.00", "aliases": [], "password": "Qm7…"}

GET /email/domains/{domain}	邮箱、别名、邮件列表及 IMAP/SMTP 设置
PATCH /email/domains/{domain}/mailboxes/{username}	更改名称或配额
POST /email/domains/{domain}/mailboxes/{username}/password	设置或生成密码
POST /email/domains/{domain}/aliases	将其他地址的邮件投递到某个邮箱
POST /email/domains/{domain}/lists	由该域名邮箱组成的邮件列表
GET /email/domains/{domain}/dns-check	实时查看 NS、MX、SPF、DKIM 和 DMARC 记录及其预期值

免费邮件转发

在 NameOcean 注册并使用我们域名服务器的域名可免费转发邮件。开启后将写入 MX 记录；如果区域中存在其他服务商的 MX 记录，请传入 replace_mx: true 以将其删除。

curl

$ curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY"
$ curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/aliases \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"localpart": "hello", "to": "me@gmail.com"}'

新的目标地址会收到一封包含链接和 6 位验证码的邮件，地址所有者确认后（通过该链接，或携带验证码调用 POST /email/forwarding/targets/{id}/verify）即开始转发。* 会转发所有未单独设置别名的地址。GET /email/forwarding/{domain}/messages 列出最近 30 天的邮件及其状态；被拦截的邮件（垃圾邮件、超出每日限额）可通过 /release 进行转发。

收到的邮件推送至 webhook

除转发外，地址还可以将收到的每封邮件以 JSON 格式推送到您的 HTTPS 端点：正文、邮件头和附件均以 base64 编码。经过对您用途的简短审核后即可开通；请在域名的“邮件转发”页面申请。

curl

$ curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/webhooks \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" -H "Content-Type: application/json" \
    -d '{"localpart": "inbound", "url": "https://example.com/hooks/mail"}'

POST https://example.com/hooks/mail

X-NameOcean-Event: email.received
X-NameOcean-Signature: t=1794300000,v1=5f2b…

{
  "id": "6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f",
  "event": "email.received",
  "envelope": {"from": "alice@example.org", "to": "inbound@example.com"},
  "from": "Alice <alice@example.org>",
  "subject": "Order 1042",
  "text": "Hi…",
  "html": "<p>Hi…</p>",
  "headers": [["From", "Alice <alice@example.org>"], …],
  "attachments": [{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 48211,
                   "content_base64": "JVBERi0…"}],
  "spam_score": 0.4,
  "size": 66120
}

签名的工作方式与账户 webhook 相同：请参阅验证签名。

事件

账户 webhook 可订阅 email.* 事件：email.mailbox.created、email.mailbox.deleted、email.forwarding.enabled 和 email.forwarding.disabled（当域名不再符合免费转发条件时也会发送，并附带原因）。

通过终端

nameocean

$ nameocean email mailboxes add example.com info --name "Info"
$ nameocean email aliases add example.com sales info
$ nameocean email check example.com
$ nameocean email forwards on example.com
$ nameocean email forwards add example.com hello me@gmail.com
$ nameocean email inbound add example.com support https://example.com/hooks/mail

所有命令均支持 --json。安装方法及全部命令：CLI。

通过您的 AI

通过 MCP，AI 助手可以列出您的邮件域名、检查其 DNS、创建邮箱和别名，以及开启邮件转发。邮箱密码绝不会发送给 AI：您需要在控制面板中查看。