REST API · v1

通过 GridInbox API 发送邮件。

使用 GridInbox API Key，从已验证的邮箱或别名发送邮件、读取收件箱，并将邮件工作流接入你的应用。

支持发送邮件。 发送接口为 POST /api/v1/messages/send。此前 API Key 鉴权查询了数据库中不存在的 Tenant.role 列，导致发送时报错；该问题已修复。

快速开始

在 GridInbox 的设置 → Developer（开发者）页面生成 API Key，然后发送一封测试邮件。请只在服务端保存 API Key，不要暴露在浏览器代码中。

curl -X POST https://api.gridinbox.com/api/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "来自 GridInbox 的测试邮件",
    "content": "<p>这封邮件通过 GridInbox API 发送。</p>"
  }'

身份验证

使用标准 Bearer Authorization Header 传递 API Key。

Authorization: Bearer sk_live_...

API Key 只对当前租户有效。请求只能使用该租户拥有的邮箱或别名作为发件人。若 Key 泄露，请立即在“设置 → Developer”中轮换。

读取邮件

API Key 可以读取当前租户下的所有邮箱，包括通过有效别名投递的邮件。传入 mailboxId 可将请求限定到单个邮箱；省略时查询整个租户范围。

邮件列表

GET/api/v1/messages

查询参数包括：mailboxId、folder、q、start_date、end_date、has_attachments、otp_only、query_all_except_spam、limit 和 offset。

curl "https://api.gridinbox.com/api/v1/messages?mailboxId=MAILBOX_ID&folder=INBOX" -H "Authorization: Bearer sk_live_..."

响应中的 data.messages 为邮件列表，data.total 为总数。

邮件详情

GET/api/v1/messages/:id

返回邮件元数据、解析内容、收发件人、标签和附件信息。必要时可传入 mailboxId。

原始邮件

GET/api/v1/messages/:id/raw

返回保存的原始邮件。传入 download=true 时以 RFC 822 文件下载。

文件夹统计

GET/api/v1/messages/stats

返回各文件夹的邮件数量，可通过 mailboxId 指定邮箱。

提取 OTP 验证码

GET/api/v1/messages/latest-otp

返回可访问邮箱中最新解析出的 OTP。查询参数：alias（收件别名或地址）、since（ISO 8601 时间）和 timeout（短轮询时间窗口，平台会根据租户和风险动态设置上限）。

curl "https://api.gridinbox.com/api/v1/messages/[email protected]" -H "Authorization: Bearer sk_live_..."

找不到匹配验证码时返回 404。

附件

上传附件

POST/api/v1/attachments/upload

使用 multipart/form-data，字段名为 file。响应会返回附件对象，可直接放入发送请求的 attachments 数组。

curl -X POST https://api.gridinbox.com/api/v1/attachments/upload -H "Authorization: Bearer sk_live_..." -F "[email protected]"

预览附件对象

GET/api/v1/attachments/proxy?key=ATTACHMENT_KEY

读取当前租户的附件内容。key 来自上传接口响应。

创建签名下载链接

POST/api/v1/attachments/:id/link

返回短期有效的签名 URL。请求体传入 {"preview":true} 可请求浏览器内联预览。

直接下载附件

GET/api/v1/attachments/:id

完成租户和邮箱权限校验后返回附件流。浏览器下载建议使用签名链接流程。

发送邮件

POSThttps://api.gridinbox.com/api/v1/messages/send

创建并发送一封邮件，同时将副本保存到发件邮箱的“已发送”文件夹。

请求体

字段	类型	必填	说明
`from`	string	是	租户拥有且已验证的邮箱或别名地址。
`to`	string \| string[]	是	一个或多个收件人。字符串支持逗号或分号分隔。
`subject`	string	是	邮件主题。
`content`	string	是	HTML 邮件正文，也支持纯文本。
`cc`	string \| string[]	否	抄送地址。
`bcc`	string \| string[]	否	密送地址。
`attachments`	object[]	否	已上传附件对象，包含 `r2Key`、`filename`、`contentType`、`size`。
`inReplyTo`	string	否	用于会话归档的原邮件 Message-ID。
`references`	string[]	否	用于会话归档的 Message-ID 列表。

成功响应

{
  "success": true,
  "messageId": "2c5c7d9e-..."
}

响应与错误

状态码	含义
`200`	邮件已接受并保存到“已发送”。
`400`	缺少必填字段或请求数据无效。
`401`	API Key 缺失或无效。
`403`	发件地址不属于当前租户或当前 Key 无权使用。
`429`	超过速率限制或每日发送限制。
`500`	服务商或服务器错误。必要时请使用退避策略重试。

{
  "success": false,
  "error": "Sender address not found or access denied"
}

限制与送达

API 请求、附件上传、发送量和请求大小均受平台安全策略保护。限制会根据租户情况、套餐、使用模式、流量风险和账号状态动态调整。达到限制后，API 会返回限流响应；请使用指数退避，并仅在适合的情况下重试。

账号套餐配额、已验证域名和发件权限同样适用。请使用已验证域名，并确保发件地址已在当前 GridInbox 租户中创建。请勿发送未经请求或滥用内容；持续的退信和投诉可能导致发送功能被暂停。

API Key 范围与审计

API Key 面向租户级自动化，支持邮件读取、OTP 提取、统计、发送和附件操作。管理员操作、账单、团队管理、邮箱管理、域名管理、草稿及邮件修改操作需要用户会话 Token，不能通过 API Key 使用。

每个经过认证的 API Key 请求都会写入租户 API 审计日志，包括方法、路径、状态码、来源 IP 和成功状态。审计记录不会保存请求体或 Authorization 请求头。

需要帮助？请联系 [email protected]。