---
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-hant.md 並逐步執行。做任何無法復原的操作之前先停下來詢問，而且絕不列印、記錄或提交 API 金鑰。

## 1. 遷移帳號

在 **API 金鑰**下建立一把完整存取的 `bs_` API 金鑰，然後在你的電腦上執行：

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

它會要求輸入你的 Resend 金鑰（完整存取）與 BillionSend 金鑰，讀取你的 Resend 帳號，提出一份遷移計畫，等你確認後執行，最後列印摘要。參數、檔案與在 CI 中使用的方式，請見 [CLI](/docs/zh-hant/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-hant/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-hant/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-hant/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-hant/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-hant/smtp)。見 [Ruby SDK](/docs/zh-hant/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-hant/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-hant/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-hant/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-hant/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-hant/sdks/dotnet)。

**Elixir。** 把社群的 `resend` 套件換成 `billionsend`（在 `mix.exs` 裡寫 `{:billionsend, "~> 0.1"}`）。`BillionSend.client()` 會讀取 `BILLIONSEND_API_KEY`，函式的第一個參數是用戶端，接著是以 map 表示、欄位名稱與 API 一致的請求本文：`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-hant/sdks/elixir)。

**其他語言。** 直接呼叫 REST API；[SDK](/docs/zh-hant/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-hant/concepts/unsubscribes)。
- **全部被抑制的傳送。** 如果一次傳送裡所有 `to` 地址都在抑制清單中，會回覆 `422 all_recipients_suppressed`，而 Resend 回覆的是 `200`。把它當作「未傳送」，不要當作需要重試的失敗。見[抑制清單](/docs/zh-hant/concepts/suppressions)。
- **附件**只接受內嵌 base64 的 `content`；遠端 `path` URL 會回覆 `422`。
- **沒有受眾（audience）。** 聯絡人屬於團隊，受眾端點是[分群](/docs/zh-hant/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-hant/concepts/unsubscribes)。

**在 Resend 也收信？** 在這裡驗證網域，然後在它的頁面上選擇**啟用收信**。Resend 會接收網域下每個地址的郵件，而在這裡需要你自己選擇：開啟**全收（catch-all）**（付費方案），或為每個地址建立一個[收件匣](/docs/zh-hant/inboxes)。然後把網域的 MX 記錄換成兩筆優先順序相同的記錄：`mx1.billionsend-dns.com` 與 `mx2.billionsend-dns.com`。郵件會送往優先順序數值最小的 MX 記錄，所以這項變更就是切換。Resend 已經收到的郵件會留在那裡。`email.received` 的處理常式無須修改，收到的郵件透過 [SDK](/docs/zh-hant/sdks) 裡的 `emails.receiving` 讀取。見[收信](/docs/zh-hant/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-hant/inboxes)。

透過新的 base URL 寄一封郵件，在**郵件**頁面看著它變成**已送達**，遷移就全部完成了。

---

Resend 是 Plus Five Five, Inc. 的註冊商標。BillionSend 與 Resend 無關聯，也未獲其背書。
