从 Resend 迁移
一条命令迁移你的 Resend 账号数据;换上 BillionSend SDK 和一个 API 密钥,代码也就迁完了。
BillionSend 的 API 与 Resend 的端点和请求格式相同,所以从 Resend 迁移只是换个软件包,不用重写代码。你的联系人、分群、订阅主题、模板、Webhook、域名和抑制列表,一条命令就能迁过来。
交给 agent
整个迁移写成了一条提示词,编码 agent 可以从头执行到尾。它对 Resend 只读,不让密钥写进文件,做任何不可逆的操作之前都会先询问。
复制迁移提示词,粘贴到你的编码 agent 里。
1. 迁移账号
在 API 密钥下创建一个完全访问的 bs_ API 密钥,然后在你的机器上运行:
npx @billionsend/cli migrate --from resend
它会要求输入你的 Resend 密钥(完全访问)和 BillionSend 密钥,读取你的 Resend 账号,给出一份迁移计划,等你确认后执行,最后打印汇总。参数、文件和在 CI 中使用的方法见 CLI 页面。
- 只读取 Resend。 工具绝不会在那边创建、修改或删除任何内容。它遵守 Resend 的速率限制:默认每秒 8 次请求,可用
--rps修改。 - 密钥只留在你的机器上。 密钥只在运行期间存在于内存里,不会写入任何文件,也没有任何遥测。
- 先切换,后补细节。 第一遍只要几分钟,结束时显示 Cutover ready:要添加的 DNS 记录,以及 base URL 那一行。到这一步就可以迁移事务邮件的发送。接着第二遍会读取每个联系人的订阅主题和属性。在它结束之前,先暂停按订阅主题发送和群发。
- 可以放心重复运行。 每次运行都会比较两边:不一致的行会更新,一致的行保持不动,联系人按邮箱地址匹配。切换流量之前再运行一次,把期间新增的联系人带过来。随时按 Ctrl-C 中断,再次运行即可继续。
| 资源 | 迁移的内容 |
|---|---|
| 联系人 | 邮箱、姓名、unsubscribed、属性、订阅主题、分群成员关系。已退订的状态会保留,不会让任何人重新订阅。Resend 的 unsubscribed 是全局的,所以在 BillionSend 里变成整个团队的 unsubscribed: true。 |
| 分群、订阅主题、属性 | 按名称或键匹配:缺失就创建,不同就更新。 |
| 模板 | 名称、别名、主题、html、text。from、reply_to 和 variables 无法存储,会作为手动步骤列出。 |
| Webhook | 端点、事件和签名密钥,所以你的接收端可以继续验签。BillionSend 不发送的事件会按 Webhook 丢弃,并列在报告里。 |
| 抑制列表 | 退信、投诉和手动添加的条目,附带它们的来源。 |
| 域名 | 连同追踪设置一起创建。DNS 记录需要重新添加(第 3 步)。 |
| 群发 | 草稿和已定时的群发都会作为草稿迁入。已发送的会被跳过,除非加上 --include-sent。 |
不会迁移的内容:API 密钥(Resend 只显示密钥的名称,所以报告把它们列为待办)、DNS 和 DKIM 记录(密钥属于各个服务商)、带会话和草稿的收件箱,以及邮件历史。
大型账号
第二遍对每个联系人发出两次请求,所占用的限额与你的生产发送共用。所需时间大约是 联系人数 × 2 ÷ 速率:
| 联系人 | 每秒 8 次请求 | 每秒 50 次请求 |
|---|---|---|
| 36,685 | 约 2 小时 30 分钟 | 约 25 分钟 |
| 160,000 | 约 11 小时 | 约 1 小时 50 分钟 |
要缩短时间,可以请 Resend 提高你的限额,再用 --rps 传入新的速率,或者在非高峰时段运行。再申请一个 API 密钥没有用,因为限额是按团队计算的。
2. 让代码指向 BillionSend
把 Resend 的软件包换成 BillionSend 的,并给它一个 bs_ 密钥。每个 SDK 都会读取 BILLIONSEND_API_KEY,设置了 BILLIONSEND_BASE_URL 时也会读取它。
BILLIONSEND_API_KEY=bs_...
Node.js。 把 resend 换成 @billionsend/node:
npm uninstall resend
npm install @billionsend/node
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // 读取 BILLIONSEND_API_KEY
const { data, error } = await bs.emails.send({
from: "Acme <onboarding@acme.dev>",
to: ["success@simulator.amazonses.com"],
subject: "Welcome to Acme",
html: "<p>Glad you are here.</p>",
reply_to: "support@acme.dev",
});
调用仍然返回 { data, error }。方法名遵循 API 参考(emails.send、emails.batch、broadcasts.send),请求字段沿用 API 自己的名称:用 reply_to、scheduled_at 和 segment_id,而 Resend 的软件包用的是 replyTo、scheduledAt 和 segmentId。用同一个软件包里的 verifyWebhook 验证 Webhook 投递;签名密钥已随 Webhook 一起迁移,所以接收端保存的 whsec_ 密钥继续有效。见 Node.js SDK。
Python。 把 resend 换成 billionsend:
pip uninstall resend
pip install billionsend
from billionsend import BillionSend
client = BillionSend() # 读取 BILLIONSEND_API_KEY
email = client.emails.send(
{
"from": "Acme <onboarding@acme.dev>",
"to": ["success@simulator.amazonses.com"],
"subject": "Welcome to Acme",
"html": "<p>Glad you are here.</p>",
}
)
调用从模块(resend.Emails.send(...))改成客户端对象(client.emails.send(...)),调用失败时会抛出 BillionSendError 的子类。见 Python SDK。
Go。 把 github.com/resend/resend-go/v4 换成 github.com/billionsend/billionsend-go(go get github.com/billionsend/billionsend-go)。billionsend.NewClient() 会读取 BILLIONSEND_API_KEY;每个方法的第一个参数都是 context.Context,可选字段是指针,用 billionsend.String 之类的函数创建。见 Go SDK。
Ruby。 把 resend 换成 billionsend(gem install billionsend,或在 Gemfile 里写 gem "billionsend")。不再设置 Resend.api_key 并调用 Resend::Emails.send(params) 这类类方法,而是创建客户端:BillionSend::Client.new 会读取 BILLIONSEND_API_KEY,client.emails.send({...}) 接受同样的 hash;幂等键从 options: { idempotency_key: ... } 改为关键字参数 idempotency_key:。返回值是键为字符串的 Hash(email["id"]),调用失败时抛出 BillionSend::Error 的子类,原来的 gem 抛出的是 Resend::Error。这个 gem 没有 Action Mailer 的投递方法:使用 delivery_method = :resend 的 Rails 应用,要让 Action Mailer 指向 SMTP 服务。见 Ruby SDK。
PHP。 把 resend/resend-php 换成 billionsend/billionsend-php(composer require billionsend/billionsend-php)。new BillionSend\Client() 会读取 BILLIONSEND_API_KEY,$client->emails->send([...]) 这类调用接受同样的数组;调用失败时抛出 BillionSendError 的子类。见 PHP SDK。
Rust。 把 resend-rs 换成 billionsend(cargo add billionsend)。BillionSend::from_env() 会读取 BILLIONSEND_API_KEY,资源是方法而不是字段:resend.emails.send(email) 变成 bs.emails().send(&body).await?。CreateEmailBaseOptions::new(from, to, subject).with_html(html) 这类带类型的选项构造器,换成任何使用 API 自己字段名的 serde::Serialize 请求体,通常是一个 json! 值;返回值是 serde_json::Value,也可以通过 .json::<T>() 得到你自己的类型,调用失败时返回 billionsend::Error,每种错误对应一个变体。见 Rust SDK。
Java。 把 com.resend:resend-java 换成 com.billionsend:billionsend-java(implementation("com.billionsend:billionsend-java:0.1.2"),或在 Maven 里使用同样的坐标)。new BillionSend() 会读取 BILLIONSEND_API_KEY,而 new Resend(key) 是直接传入密钥。调用的形式不变,仍是 client.emails().send(...),但参数改为使用 API 自己字段名(如 reply_to)的 Map(或任何 Jackson 能写出的值),不再用 CreateEmailOptions.builder()...build();返回 JsonNode(sent.get("id").asText()),不再是 CreateEmailResponse。调用失败时抛出的是非受检的 BillionSendException 子类,而不是受检的 ResendException,所以 catch (ResendException e) 这类代码块可以删掉。见 Java SDK。
.NET。 把 Resend 包换成 BillionSend(dotnet remove package Resend,再执行 dotnet add package BillionSend --version 0.1.0)。new BillionSendClient() 会读取 BILLIONSEND_API_KEY,而 Resend 的客户端是通过 ResendClientOptions 接收令牌;一个客户端可以安全共享,所以只注册一次,用单例即可。调用沿用 API 参考里的操作 id,再加上 Async 后缀,即 client.Emails.SendAsync(...),参数可以是 System.Text.Json 能写出的任何对象,例如字段名与 API 一致(from、to、reply_to)的匿名对象,不再用 EmailMessage;返回值是 JsonNode 树(sent?["id"]),调用失败时抛出 BillionSendException 的子类,常见状态码对应 ValidationException、NotFoundException 和 RateLimitException。见 .NET SDK。
Elixir。 把社区的 resend 包换成 billionsend(在 mix.exs 里写 {:billionsend, "~> 0.1"})。BillionSend.client() 会读取 BILLIONSEND_API_KEY,函数的第一个参数是客户端,然后是字段名与 API 一致的 map 请求体:BillionSend.Emails.send(client, %{from: ..., to: [...], subject: ..., html: ...}) 返回 {:ok, answer} 或 {:error, error},其中 answer 是键为字符串的 map(sent["id"]),error 是一个异常 struct,例如 BillionSend.NotFoundError。幂等键放在选项里,即 idempotency_key: "welcome/ana",不过每次发送本来就会带一个。Webhook 投递用 BillionSend.verify_webhook/4 检查。见 Elixir SDK。
其他语言。 直接调用 REST API;SDK 页面有 cURL 写法。
Resend 集成可能默认成立、但这里有所不同的地方:
- 每个地址字段只能有一个邮箱。
from、to、cc和bcc每个只接受一个邮箱,例如ada@example.com或Ada <ada@example.com>。含逗号的显示名必须加引号("Ada, Inc." <ada@example.com>)。不加引号会被读成两个地址,发送会以422失败。 - 订阅主题的订阅关系。
PATCH /contacts/{id}/topics接受一个由{ "id": "<topic-id>", "subscription": "opt_in" | "opt_out" }组成的纯 JSON 数组。 - 批量联系人。 没有 CSV 导入端点。用
POST /contacts/batch?on_conflict=upsert提交 JSON,每次最多 1,000 个联系人。加上x-batch-validation: permissive,部分行失败时仍会保留有效的行。 - 永远收不到邮件的地址。 发往
x@example.com、x@foo.test或x@gmail.con这类收件人的请求会被拒绝并返回422 validation_error,在这类地址上新建联系人也一样。 - 退订属于发信域名。 点击退订的收件人只会退出发出这封邮件的那个域名。联系人的
unsubscribed字段仍是整个团队的开关,所以检查谁已退订的代码,应该同时读取unsubscribed和unsubscribed_domains。要带入其他服务商的退订名单,可以在联系人 → 退订下导入,或提交到POST /unsubscribes。见退订。 - 全部被抑制的发送。 如果一次发送里所有
to地址都在抑制列表中,会返回422 all_recipients_suppressed,而 Resend 返回200。把它当作「未发送」,不要当作需要重试的失败。见抑制列表。 - 附件只接受内嵌 base64 的
content;远程pathURL 会返回422。 - 没有受众(audience)。 联系人属于团队,受众端点是分群的别名。
- 邮件头有允许列表:任何
X-*名称(X-SES-*和X-BillionSend-*除外)、会话串联和优先级相关的邮件头,以及List-Unsubscribe这一对。其他邮件头会返回422。 - 批量抑制每次请求最多 1,000 个地址,而 Resend 是 100 个。
- 不支持的设置会返回
422,而不是被忽略。
3. 完成检查清单
汇总的末尾是一份检查清单。以下三项一定会有:
- 为每个域名添加 DNS 记录。 BillionSend 使用自己的 DKIM 密钥,所以即使域名已经在通过 Resend 发信,这些记录也是新的。报告会按域名打印它们,它们也在域名下该域名的页面里。两个服务商可以同时保持验证通过。
- 让代码指向 BillionSend,每个会发信的环境都要改。如果保留 Resend 的软件包,汇总会打印对应的 base URL 那一行;使用 BillionSend SDK 的话,改为设置
BILLIONSEND_API_KEY(第 2 步)。 - 创建 API 密钥,报告列出多少个名称就创建多少个,在 API 密钥下操作。
适用时还会出现两项:需要在每次发送时单独设置的模板 from 和 reply_to 值,以及 BillionSend 不发送的 Webhook 事件。群发里的 {{{RESEND_UNSUBSCRIBE_URL}}} 仍然有效,是 {{{UNSUBSCRIBE_URL}}} 的别名。
第一次群发之前,先设置每个域名自己的退订页面;如果想让链接带上你自己的名称,再设置一个退订子域名。在那之前,收件人看到的是共享主机和团队的默认页面。见退订。
在 Resend 也收信? 在这里验证域名,然后在它的页面上选择开启收信。Resend 会接收域名下每个地址的邮件,而在这里需要你自己选择:开启全域收信(catch-all)(付费套餐),或者为每个地址创建一个收件箱。然后把域名的 MX 记录换成两条优先级相同的记录:mx1.billionsend-dns.com 和 mx2.billionsend-dns.com。邮件会发往优先级数值最小的 MX 记录,所以这一步改动就是切换。Resend 已经收到的邮件会留在那里。email.received 的处理程序无需改动,收到的邮件通过 SDK 里的 emails.receiving 读取。见收信。
在用 Resend 的 Inboxes? 用相同的地址重新创建每个收件箱(bs.inboxes.create()、POST /inboxes,或收件箱 → 创建收件箱)。会话和草稿留在 Resend。kind 默认是 agent,并开启 BillionSend 的保护;供真人阅读的收件箱用 kind: "human" 创建。BillionSend 的收件箱与 Resend 的不同之处:
- 创建收件箱或草稿会返回完整对象,Resend 的
{ object, id }只是其中的一部分。 POST /inboxes/{id}/emails一次调用就能发起新会话,GET /inboxes/events和GET /inboxes/{id}/events以流的形式推送收件箱事件;Resend 两者都没有。inbox.expired和inbox.email.quarantined是 BillionSend 自有的 Webhook 事件;inbox.thread.assigned和inbox.thread.unassigned不会发送。
见收件箱。
通过新的 base URL 发一封邮件,在邮件页面看着它变成已送达,迁移就全部完成了。
Resend 是 Plus Five Five, Inc. 的注册商标。BillionSend 与 Resend 没有关联,也未获其认可。