從 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,函式的第一個參數是用戶端,接著是以 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。
其他語言。 直接呼叫 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 無關聯,也未獲其背書。