Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Migrate from Resend

One command moves your Resend account data; the BillionSend SDK and one API key move your code.

BillionSend’s API has the same endpoints and request shapes as Resend’s, so migrating is a package swap, not a rewrite. Your contacts, segments, topics, templates, webhooks, domains and suppressions move with one command.

Hand it to an agent

The whole migration is written as one prompt that a coding agent can follow from start to finish. It keeps Resend read-only, keeps keys out of files and asks before anything irreversible.

Copy the migration prompt and paste it into your coding agent.

1. Move your account

Create a full-access bs_ API key under API keys, then run on your machine:

npx @billionsend/cli migrate --from resend

It asks for your Resend key (full access) and your BillionSend key, reads your Resend account, shows a plan, waits for your confirmation, applies it and prints a summary. Flags, files and CI use are on the CLI page.

  • Resend is only read. The tool never creates, changes or deletes anything there. It stays under Resend’s rate limit: 8 requests per second by default, with --rps to change it.
  • Your keys stay on your machine. They live in memory for the run and are never written to a file. There is no telemetry.
  • Cutover first, details after. The first pass takes minutes and ends with Cutover ready: the DNS records to add and the base URL line. You can move transactional sending at that point. A second pass then reads each contact’s topic subscriptions and properties. Hold topic sends and broadcasts until it finishes.
  • Safe to re-run. Every run compares both sides: rows that differ are updated, rows that match are left alone, contacts are matched by email. Run it again right before you switch traffic to pick up contacts that arrived in between. Press Ctrl-C at any time and run it again to resume.
Resource What moves
Contacts Email, names, unsubscribed, properties, topic subscriptions, segment memberships. Opt-outs are kept; nobody is re-subscribed. Resend’s unsubscribed is global, so it becomes BillionSend’s team-wide unsubscribed: true.
Segments, topics, properties Matched by name or key: created when missing, updated when different.
Templates Name, alias, subject, html, text. from, reply_to and variables cannot be stored and are listed as manual steps.
Webhooks Endpoint, events and signing secret, so your receiver keeps verifying. Events BillionSend does not send are dropped per webhook and listed in the report.
Suppressions Bounces, complaints and manual entries, with their origin.
Domains Created with their tracking settings. DNS records must be added again (step 3).
Broadcasts Drafts and scheduled ones arrive as drafts. Sent ones are skipped unless you pass --include-sent.

What does not move: API keys (Resend only shows their names, so the report lists them as a to-do), DNS and DKIM records (keys belong to each provider), inboxes with their threads and drafts, and email history.

Large accounts

The second pass makes two requests per contact, against a limit your production sending shares. The time is about contacts × 2 ÷ rate:

Contacts At 8 req/s At 50 req/s
36,685 about 2 h 30 min about 25 min
160,000 about 11 h about 1 h 50 min

To shorten it, ask Resend to raise your limit and pass the new rate with --rps, or run off-peak. A second API key does not help, because the limit is per team.

2. Point your code at BillionSend

Swap the Resend package for BillionSend’s and give it a bs_ key. Each SDK reads BILLIONSEND_API_KEY, and BILLIONSEND_BASE_URL when it is set.

BILLIONSEND_API_KEY=bs_...

Node.js. Replace resend with @billionsend/node 0.1.1:

npm uninstall resend
npm install @billionsend/node
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <onboarding@acme.dev>",
  to: ["ana@example.com"],
  subject: "Welcome to Acme",
  html: "<p>Glad you are here.</p>",
  reply_to: "support@acme.dev",
});

Calls still resolve to { data, error }. Method names follow the API reference (emails.send, emails.batch, broadcasts.send), and request fields keep the API’s own names: reply_to, scheduled_at and segment_id where the Resend package takes replyTo, scheduledAt and segmentId. Verify webhook deliveries with verifyWebhook from the same package; the signing secrets moved with your webhooks, so the whsec_ secret your receiver holds keeps working. See Node.js SDK.

Python. Replace resend with billionsend 0.1.1:

pip uninstall resend
pip install billionsend
from billionsend import BillionSend

client = BillionSend()  # reads BILLIONSEND_API_KEY

email = client.emails.send(
    {
        "from": "Acme <onboarding@acme.dev>",
        "to": ["ana@example.com"],
        "subject": "Welcome to Acme",
        "html": "<p>Glad you are here.</p>",
    }
)

Calls move from the module (resend.Emails.send(...)) to a client object (client.emails.send(...)), and a failed call raises a BillionSendError subclass. See Python SDK.

Go. Replace github.com/resend/resend-go/v4 with github.com/billionsend/billionsend-go 0.1.3 (go get github.com/billionsend/billionsend-go@v0.1.3). billionsend.NewClient() reads BILLIONSEND_API_KEY; every method takes a context.Context first, and optional fields are pointers made with billionsend.String and the like. See Go SDK.

Ruby. Replace resend with billionsend 0.1.0 (gem install billionsend, or gem "billionsend", "~> 0.1" in the Gemfile). Instead of setting Resend.api_key and calling class methods such as Resend::Emails.send(params), make a client: BillionSend::Client.new reads BILLIONSEND_API_KEY, and client.emails.send({...}) takes the same hash; an idempotency key moves from options: { idempotency_key: ... } to the keyword idempotency_key:. Answers are Hashes with string keys (email["id"]), and a failed call raises a BillionSend::Error subclass where the old gem raised Resend::Error. The gem has no Action Mailer delivery method: a Rails app on delivery_method = :resend points Action Mailer at the SMTP relay. See Ruby SDK.

PHP. Replace resend/resend-php with billionsend/billionsend-php 0.1.2 (composer require billionsend/billionsend-php:^0.1). new BillionSend\Client() reads BILLIONSEND_API_KEY, and calls such as $client->emails->send([...]) take the same arrays; a failed call throws a BillionSendError subclass. See PHP SDK.

Rust. Replace resend-rs with billionsend 0.1.2 (cargo add billionsend@0.1.2). BillionSend::from_env() reads BILLIONSEND_API_KEY, and resources are methods rather than fields: resend.emails.send(email) becomes bs.emails().send(&body).await?. Typed option builders such as CreateEmailBaseOptions::new(from, to, subject).with_html(html) give way to any serde::Serialize body with the API’s own field names, usually a json! value; answers are serde_json::Value, or your own type through .json::<T>(), and a failed call is a billionsend::Error with a variant per kind. See Rust SDK.

Java. Replace com.resend:resend-java with com.billionsend:billionsend-java 0.1.2 (implementation("com.billionsend:billionsend-java:0.1.2"), or the same coordinates in Maven). new BillionSend() reads BILLIONSEND_API_KEY where new Resend(key) took the key. Calls keep their shape, client.emails().send(...), but take a Map (or any value Jackson can write) with the API’s own field names, such as reply_to, in place of CreateEmailOptions.builder()...build(), and answer a JsonNode (sent.get("id").asText()) in place of CreateEmailResponse. A failed call throws an unchecked BillionSendException subclass instead of the checked ResendException, so the catch (ResendException e) blocks go. See Java SDK.

.NET. Replace the Resend package with BillionSend 0.1.0 (dotnet remove package Resend, then dotnet add package BillionSend --version 0.1.0). new BillionSendClient() reads BILLIONSEND_API_KEY where the Resend client took its token through ResendClientOptions, and one client is safe to share, so register it once as a singleton. Calls follow the operation ids of the API reference with an Async suffix, client.Emails.SendAsync(...), and take any object System.Text.Json can write, such as an anonymous object with the API’s own field names (from, to, reply_to), in place of an EmailMessage; answers are JsonNode trees (sent?["id"]), and a failed call throws a BillionSendException subclass, with ValidationException, NotFoundException and RateLimitException for the common statuses. See .NET SDK.

Elixir. Replace the community resend package with billionsend 0.1.0 ({:billionsend, "~> 0.1"} in mix.exs). BillionSend.client() reads BILLIONSEND_API_KEY, and functions take the client first, then the body as a map with the API’s own field names: BillionSend.Emails.send(client, %{from: ..., to: [...], subject: ..., html: ...}) returns {:ok, answer} or {:error, error}, where the answer is a map with string keys (sent["id"]) and the error an exception struct such as BillionSend.NotFoundError. An idempotency key goes in the options, idempotency_key: "welcome/ana", and every send carries one anyway. Webhook deliveries are checked with BillionSend.verify_webhook/4. See Elixir SDK.

Other languages. Call the REST API directly; SDKs has the cURL form.

What differs from what a Resend integration may assume:

  • One mailbox per address field. from, to, cc and bcc take one mailbox each, such as ada@example.com or Ada <ada@example.com>. A display name with a comma must be quoted ("Ada, Inc." <ada@example.com>). Unquoted, it reads as two addresses and the send fails with 422.
  • Topic subscriptions. PATCH /contacts/{id}/topics takes a bare JSON array of { "id": "<topic-id>", "subscription": "opt_in" | "opt_out" }.
  • Bulk contacts. There is no CSV import endpoint. Use POST /contacts/batch?on_conflict=upsert with JSON, up to 1,000 contacts per call. Add x-batch-validation: permissive to keep the valid rows when some fail.
  • Addresses that can never receive mail. A recipient such as x@example.com, x@foo.test or x@gmail.con is refused with 422 validation_error, and so is a new contact at one.
  • Unsubscribes belong to the sending domain. A recipient who clicks unsubscribe leaves only the domain that sent the email. The contact’s unsubscribed field stays your team-wide switch, so code that checks who has left should read both unsubscribed and unsubscribed_domains. To bring over an opt-out list from another provider, import it under Audience → Unsubscribes or post it to POST /unsubscribes. See Unsubscribes.
  • Fully suppressed sends. A send where every to address is suppressed answers 422 all_recipients_suppressed, where Resend answers 200. Treat it as “not sent”, not as a failure to retry. See Suppressions.
  • Attachments take inline base64 content only; a remote path URL answers 422.
  • No audiences. Contacts belong to the team, and the audience endpoints work as aliases of segments.
  • Headers are allowlisted: any X-* name (except X-SES-* and X-BillionSend-*), threading and priority headers, and the List-Unsubscribe pair. Anything else answers 422.
  • Bulk suppressions take up to 1,000 addresses per request, where Resend takes 100.
  • Unsupported settings answer 422 instead of being ignored.

3. Finish the checklist

The summary ends with a checklist. Three items are always there:

  • Add DNS records for each domain. BillionSend uses its own DKIM keys, so the records are new even for a domain that already sends through Resend. The report prints them per domain, and they are also on the domain’s page in Domains. Both providers can stay verified side by side.
  • Point your code at BillionSend in every environment that sends. The summary prints the base URL line for a Resend package you keep; with the BillionSend SDK, set BILLIONSEND_API_KEY instead (step 2).
  • Create API keys, one for each name the report lists, under API keys.

Two more appear when they apply: template from and reply_to values to set per send, and webhook events BillionSend does not send. {{{RESEND_UNSUBSCRIBE_URL}}} in a broadcast keeps working as an alias of {{{UNSUBSCRIBE_URL}}}.

Before your first broadcast, set each domain’s own unsubscribe page and, if you want links under your own name, an unsubscribe subdomain. Until then recipients see the shared host and your team’s default page. See Unsubscribes.

Receiving mail at Resend too? Verify the domain here, then choose Enable receiving on its page. Resend takes mail at every address of a domain. Here you choose: turn on Catch-all (paid plans) or create an inbox per address. Then replace the domain’s MX record with two at the same priority, mx1.billionsend-dns.com and mx2.billionsend-dns.com. Mail goes to the lowest-priority MX records, so this change is the cutover. Mail Resend already received stays there. Handlers for email.received need no change, and received mail is read with emails.receiving in the SDKs. See Receiving.

Using Resend’s Inboxes? Create each inbox again with the same address (bs.inboxes.create(), POST /inboxes, or Inboxes → Create inbox). Threads and drafts stay at Resend. kind defaults to agent, with BillionSend’s protections on; create inboxes that people read with kind: "human". Where BillionSend’s inboxes differ from Resend’s:

  • Creating an inbox or a draft answers the whole object, of which Resend’s { object, id } is a part.
  • POST /inboxes/{id}/emails starts a new conversation in one call, and GET /inboxes/events and GET /inboxes/{id}/events stream inbox events; Resend has neither.
  • inbox.expired and inbox.email.quarantined are BillionSend’s own webhook events; inbox.thread.assigned and inbox.thread.unassigned are not sent.

See Inboxes.

Send one email through the new base URL and watch it reach Delivered on the Emails page. That is the whole migration.


Resend is a registered trademark of Plus Five Five, Inc. BillionSend is not affiliated with or endorsed by Resend.

Was this page helpful?