从 Resend 迁移

SpacePost 实现了 Resend API：路径、字段名、响应结构和错误格式都相同。大多数应用只需修改基础 URL 和 API 密钥即可完成迁移。

1. 在控制台中创建 SpacePost API 密钥。 SpacePost 密钥以 sp_live_ 开头（Resend 密钥以 re_ 开头）。

2. 在 SpacePost 中添加并验证你的域名。 DNS 记录与 Resend 不同，因此请添加新的 DKIM CNAME 记录以及 send 的 MX/TXT 记录。切换期间可以保留 Resend 的记录，因为 DKIM 选择器不会冲突。参见添加与验证。只有在你更改了 send 子域名时，才需要迁移 SPF/DMARC 策略。

3. 切换客户端。 从下列方案中任选其一。

   Resend SDK，保持不变

   继续使用官方的 resend 包。通过环境变量设置基础 URL，并使用你的 SpacePost 密钥：

   .env

   RESEND_API_KEY=sp_live_YOUR_API_KEY
   RESEND_BASE_URL=https://api.spacepost.dev

   import { Resend } from "resend";
   
   const resend = new Resend(process.env.RESEND_API_KEY);
   await resend.emails.send({ from: "Acme <hello@acme.com>", to: "you@example.com", subject: "Hi", html: "<p>Hi</p>" });

   或者在代码中传入：

   const resend = new Resend("sp_live_YOUR_API_KEY", { baseUrl: "https://api.spacepost.dev" });

   @spacepost/node

   替换 import 即可。方法名和 { data, error } 返回结构保持一致。

   import { Resend } from "resend";
   const resend = new Resend(process.env.RESEND_API_KEY);
   import { SpacePost } from "@spacepost/node";
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   
   await resend.emails.send({ ... });
   await spacepost.emails.send({ ... });

   原始 HTTP / 其他语言

   修改主机和密钥即可。路径和请求体完全相同。

   curl https://api.resend.com/emails -H "Authorization: Bearer re_..."
   curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_..."

   SMTP

   修改主机、端口和密码，并使用 STARTTLS。用户名 resend 可作为 spacepost 的别名使用。

   Host: smtp.spacepost.dev    Port: 25976 (STARTTLS)
   User: spacepost             Password: sp_live_YOUR_API_KEY

4. 重新创建 Webhook。 在 SpacePost 中重新创建每个端点（POST /webhooks），并保存新的 signing_secret。为 Resend 或 Svix 编写的验证代码可继续使用，因为 SpacePost 发送相同的 Standard Webhooks 标头（并附带重复的 svix-* 标头）。参见验证签名。

5. 迁移受众和联系人。 通过 POST /audiences/{id}/contacts 创建受众并导入联系人。{{{FIRST_NAME|fallback}}} 和 {{{RESEND_UNSUBSCRIBE_URL}}} 等占位符在群发中无需修改即可使用。

6. 发送测试邮件，然后切换。 发送到 delivered@test.spacepost.dev，确认 Webhook 已送达，然后部署。

功能对照表

Resend 功能	SpacePost	说明
POST /emails	支持	to/cc/bcc/reply_to 各最多 50 个；接受驼峰别名 replyTo、scheduledAt
POST /emails/batch	支持	最多 100 封邮件；每封邮件可带附件和 scheduled_at；要么全部成功，要么全部失败
GET /emails/{id}、GET /emails	支持	列表不含正文
PATCH /emails/{id}	支持	重新安排定时邮件的发送时间
POST /emails/{id}/cancel	支持	仅限定时邮件
附件（content、path）	支持	path 必须是 https
标签、自定义标头	支持	标签字符的限制相同
Idempotency-Key	支持	24 小时，适用于 POST /emails 和 /emails/batch
域名（创建、获取、列表、验证、更新、删除）	支持	open_tracking、click_tracking
API 密钥	支持	full_access、sending_access，可选 domain_id
Webhook、Standard Webhooks 签名	支持	同时提供 svix-* 标头
受众、联系人、群发	支持	联系人位于 /audiences/{id}/contacts 之下
抑制 API	支持	额外功能：列出、添加和移除条目
租户（平台模式）	仅 SpacePost 提供	每个客户拥有独立信誉；参见平台模式。Resend SDK 会丢弃 tenant_id；请使用 resend.post 或租户自有的域名
SMTP 中继	支持	smtp.spacepost.dev:25976，使用 STARTTLS（暂不提供 465 端口上的隐式 TLS）
入站邮件	暂不支持
模板编辑器	暂不支持	请使用 React Email 或你自己的 HTML

需要了解的差异

密钥前缀

SpacePost 密钥以 sp_live_ 开头。re_... 密钥会被拒绝，并返回 403 invalid_api_key。如果迁移后看到该错误，说明某处仍部署着旧的 RESEND_API_KEY。

• last_event 的取值。 Resend 的所有取值（queued、scheduled、sent、delivered、delivery_delayed、bounced、complained、opened、clicked、canceled、failed）都存在。SpacePost 另外增加了 suppressed，用于所有收件人都在你的抑制列表中的情况。状态不会倒退：在 delivered 之前到达的 opened 事件不会覆盖后面的状态。
• 额外的 Webhook 事件。 当收件人因被抑制而被跳过时，会触发 email.suppressed。请只订阅你会处理的事件。除此之外，载荷与 Resend 相同；租户邮件会额外带有 data.tenant_id。
• 速率限制。 每个团队每秒 10 个请求（Scale 为 25），而 Resend 为 2，并使用相同的 ratelimit-* 标头。
• 价格。 Pro 套餐 €9，含 50,000 封邮件，每超出 1,000 封收费 €0.25，以欧元计费，不含增值税（Resend Pro：USD 20，每超出 1,000 封收费 USD 0.90，为 Resend 截至 2026 年 10 月 23 日的美元价格）。前 7 天之后，包括 Free 在内的每个套餐都有一个随你的发送量增长的每日上限：1,000 与你最近 14 天中最高单日发送量的两倍中的较大值，最高每天 50,000 封。参见套餐与配额。
• 什么算一封邮件。 每个收件人都会计数：一封发给 3 个收件人（to、cc 和 bcc 合计）的邮件，会占用 3 封配额。
• 测试发件人。 onboarding@test.spacepost.dev 取代 onboarding@resend.dev。测试收件箱位于 test.spacepost.dev，而不是 resend.dev：delivered@、bounced@、complained@、delayed@，以及 softbounced@（仅 SpacePost 提供）。
• 新账户沙盒。 前 7 天每天最多发送 100 封邮件。参见账户验证与发送限额。
• 自动暂停。 退信率或投诉率异常的团队会被自动暂停。参见自动暂停。
• 基础 URL。 https://api.spacepost.dev，路径位于根目录。也接受 /v1 前缀（https://api.spacepost.dev/v1/emails）。