---
title: 从 Resend 迁移
description: 一条命令迁移你的 Resend 账号数据；换上 BillionSend SDK 和一个 API 密钥，代码也就迁完了。
ai:
  exclude: true
---

BillionSend 的 API 与 Resend 的端点和请求格式相同，所以从 Resend 迁移只是换个软件包，不用重写代码。你的联系人、分群、订阅主题、模板、Webhook、域名和抑制列表，一条命令就能迁过来。

## 交给 agent

整个迁移写成了一条提示词，编码 agent 可以从头执行到尾。它对 Resend 只读，不让密钥写进文件，做任何不可逆的操作之前都会先询问。

**复制迁移提示词，粘贴到你的编码 agent 里。**

> 把这个项目从 Resend 迁移到 BillionSend。阅读 https://billionsend.com/docs/prompts/migrate-from-resend.zh-hans.md 并逐步执行。做任何不可逆的操作之前先停下来询问，并且绝不打印、记录或提交 API 密钥。

## 1. 迁移账号

在 **API 密钥**下创建一个完全访问的 `bs_` API 密钥，然后在你的机器上运行：

```sh
npx @billionsend/cli migrate --from resend
```

它会要求输入你的 Resend 密钥（完全访问）和 BillionSend 密钥，读取你的 Resend 账号，给出一份迁移计划，等你确认后执行，最后打印汇总。参数、文件和在 CI 中使用的方法见 [CLI](/docs/zh-hans/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` 时也会读取它。

```sh
BILLIONSEND_API_KEY=bs_...
```

**Node.js。** 把 `resend` 换成 `@billionsend/node`：

```sh
npm uninstall resend
npm install @billionsend/node
```

```ts
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 参考](/docs/zh-hans/api-reference)（`emails.send`、`emails.batch`、`broadcasts.send`），请求字段沿用 API 自己的名称：用 `reply_to`、`scheduled_at` 和 `segment_id`，而 Resend 的软件包用的是 `replyTo`、`scheduledAt` 和 `segmentId`。用同一个软件包里的 `verifyWebhook` 验证 Webhook 投递；签名密钥已随 Webhook 一起迁移，所以接收端保存的 `whsec_` 密钥继续有效。见 [Node.js SDK](/docs/zh-hans/sdks/node)。

**Python。** 把 `resend` 换成 `billionsend`：

```sh
pip uninstall resend
pip install billionsend
```

```python
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](/docs/zh-hans/sdks/python)。

**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](/docs/zh-hans/sdks/go)。

**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 服务](/docs/zh-hans/smtp)。见 [Ruby SDK](/docs/zh-hans/sdks/ruby)。

**PHP。** 把 `resend/resend-php` 换成 `billionsend/billionsend-php`（`composer require billionsend/billionsend-php`）。`new BillionSend\Client()` 会读取 `BILLIONSEND_API_KEY`，`$client->emails->send([...])` 这类调用接受同样的数组；调用失败时抛出 `BillionSendError` 的子类。见 [PHP SDK](/docs/zh-hans/sdks/php)。

**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](/docs/zh-hans/sdks/rust)。

**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](/docs/zh-hans/sdks/java)。

**.NET。** 把 `Resend` 包换成 `BillionSend`（`dotnet remove package Resend`，再执行 `dotnet add package BillionSend --version 0.1.0`）。`new BillionSendClient()` 会读取 `BILLIONSEND_API_KEY`，而 Resend 的客户端是通过 `ResendClientOptions` 接收令牌；一个客户端可以安全共享，所以只注册一次，用单例即可。调用沿用 [API 参考](/docs/zh-hans/api-reference)里的操作 id，再加上 `Async` 后缀，即 `client.Emails.SendAsync(...)`，参数可以是 `System.Text.Json` 能写出的任何对象，例如字段名与 API 一致（`from`、`to`、`reply_to`）的匿名对象，不再用 `EmailMessage`；返回值是 `JsonNode` 树（`sent?["id"]`），调用失败时抛出 `BillionSendException` 的子类，常见状态码对应 `ValidationException`、`NotFoundException` 和 `RateLimitException`。见 [.NET SDK](/docs/zh-hans/sdks/dotnet)。

**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](/docs/zh-hans/sdks/elixir)。

**其他语言。** 直接调用 REST API；[SDK](/docs/zh-hans/sdks) 页面有 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`。见[退订](/docs/zh-hans/concepts/unsubscribes)。
- **全部被抑制的发送。** 如果一次发送里所有 `to` 地址都在抑制列表中，会返回 `422 all_recipients_suppressed`，而 Resend 返回 `200`。把它当作「未发送」，不要当作需要重试的失败。见[抑制列表](/docs/zh-hans/concepts/suppressions)。
- **附件**只接受内嵌 base64 的 `content`；远程 `path` URL 会返回 `422`。
- **没有受众（audience）。** 联系人属于团队，受众端点是[分群](/docs/zh-hans/concepts/segments)的别名。
- **邮件头有允许列表**：任何 `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}}}` 的别名。

第一次群发之前，先设置每个域名自己的退订页面；如果想让链接带上你自己的名称，再设置一个退订子域名。在那之前，收件人看到的是共享主机和团队的默认页面。见[退订](/docs/zh-hans/concepts/unsubscribes)。

**在 Resend 也收信？** 在这里验证域名，然后在它的页面上选择**开启收信**。Resend 会接收域名下每个地址的邮件，而在这里需要你自己选择：开启**全域收信（catch-all）**（付费套餐），或者为每个地址创建一个[收件箱](/docs/zh-hans/inboxes)。然后把域名的 MX 记录换成两条优先级相同的记录：`mx1.billionsend-dns.com` 和 `mx2.billionsend-dns.com`。邮件会发往优先级数值最小的 MX 记录，所以这一步改动就是切换。Resend 已经收到的邮件会留在那里。`email.received` 的处理程序无需改动，收到的邮件通过 [SDK](/docs/zh-hans/sdks) 里的 `emails.receiving` 读取。见[收信](/docs/zh-hans/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` 不会发送。

见[收件箱](/docs/zh-hans/inboxes)。

通过新的 base URL 发一封邮件，在**邮件**页面看着它变成**已送达**，迁移就全部完成了。

---

Resend 是 Plus Five Five, Inc. 的注册商标。BillionSend 与 Resend 没有关联，也未获其认可。
