API 简介

SpacePost API 是一个与 Resend API 兼容的 JSON REST API。完整的端点列表见 API 参考，它由 OpenAPI 规范生成。

基础 URL

https://api.spacepost.dev

路径位于根目录（/emails、/domains 等）。也接受 /v1 前缀：https://api.spacepost.dev/v1/emails 是同一个端点。请使用你的客户端更喜欢的那种。

在每个请求中以 bearer 令牌的形式发送你的 API 密钥：

curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"

密钥以 sp_live_ 开头。full_access 密钥可使用所有端点；sending_access 密钥只能发送邮件，还可以限定为单个域名。参见安全与 API 密钥。

问题	响应
缺少 `Authorization` 标头	`401 missing_api_key`
密钥未知、已吊销或格式错误（包括 Resend 的 `re_` 密钥）	`403 invalid_api_key`
`sending_access` 密钥用于非发送端点	`401 restricted_api_key`

发送 JSON，并带上 Content-Type: application/json。无效的 JSON 会返回 422 validation_error。
字段使用 snake_case（reply_to、scheduled_at）。为方便起见，发送时也接受 replyTo 和 scheduledAt。
ID 是 UUIDv7 字符串；它们按创建时间排序，分页正是基于这一点实现的。
时间戳为 UTC 的 ISO 8601 格式（2026-10-23T14:02:09.512Z）。
请求中的未知字段会被忽略。

成功的响应是状态码为 200 的 JSON。资源带有 object 字段，用于标明其类型（"email"、"domain" 等）。列表形如 { "object": "list", "has_more": false, "data": [] }。

错误始终采用相同的结构：

{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }

所有 name 的说明见错误。

POST /emails 和 POST /emails/batch 接受 Idempotency-Key 标头（1 到 256 个字符，保留 24 小时）：相同的键和请求体会返回第一次的响应，而不会再次发送。参见幂等键。

按团队计算：每秒 10 个请求（Scale 为 25），通过 ratelimit-* 标头返回。参见速率限制。

API 遵循 Resend 当前的结构，不使用带日期的版本号。我们对现有端点只做向后兼容的更改（新的可选字段、响应中的新字段、新的事件类型和错误名称），因此请编写能忽略未知字段、并能处理未知错误名称的客户端。任何破坏性变更都会通过新的路径前缀发布，并会提前在更新日志中通知。

API 会发送宽松的 CORS 标头，以便 API 浏览工具可以调用，但切勿在浏览器中使用真实密钥调用它。密钥应该放在服务器上。