Migrate from Resend without changing your code

01The part that really is one line

The request and response shapes of /v1/emails are Resend's, exactly. Not inspired by, not mostly compatible — the same fields in the same places, so the resend SDK you already have installed works against your instance with a base URL and a key.

import { Resend } from 'resend'

// before
const resend = new Resend(process.env.RESEND_API_KEY)

// after — same import, same calls, same response handling
const resend = new Resend(process.env.MAILYSEND_API_KEY, {
  baseUrl: 'https://your-instance.example.com/v1',
})

await resend.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your receipt',
  html: body,
})  // → { id: "…" }, exactly as before

Everything added on top is additive and ignored by their SDK, which is what makes the compatibility survive contact with reality rather than only with a hello-world. None of it is required to migrate.

02Moving a sending domain

The rule for the whole DNS step is one sentence: publish the new records alongside the old ones and verify them before you move any traffic. Do it in that order and there is never a moment where neither system can authenticate your mail.

; during the overlap — one record, both includes
@  TXT  "v=spf1 include:_spf.mx.cloudflare.net include:amazonses.com ~all"

$ dig +short TXT yourdomain.com
$ dig +short TXT ms1._domainkey.yourdomain.com
$ dig +short TXT _dmarc.yourdomain.com

03Contacts, suppressions and history

Three kinds of data, and they are not equally important. One of them must be moved before your first send; one is worth moving carefully; one is usually not worth moving at all.

Export the list from your current provider and import it in bulk. Up to a thousand addresses per call, and re-running an import is safe: an address that is already suppressed is upserted rather than rejected, so a partial import can simply be run again rather than diffed. Carry the reason across rather than flattening everything to a generic entry — it costs nothing at import time and it is the difference between later being able to say “these two thousand are unsubscribes, those four hundred are dead mailboxes” and having one undifferentiated blocklist you can never safely prune.

POST /v1/suppressions/bulk
{
  "emails": [
    { "email": "[email protected]", "reason": "hard_bounce" },
    { "email": "[email protected]",    "reason": "unsubscribe" }
  ]
}

Contacts, second. Import into an audience, check the count against your source before you trust it, and — this is the one worth being fussy about — confirm that the unsubscribe flag survived. A contact import that silently drops unsubscribed produces exactly the same catastrophe as skipping the suppression list, with the added indignity of having done the work.

History, mostly not. A segment defined over imported counts is a segment computed from numbers whose provenance you have already forgotten. Keep your old dashboard read-only for as long as your provider allows and let the new numbers accumulate honestly. The exception is genuine legal retention — export the raw records to your own storage and treat that as an archive rather than trying to make it queryable in the new system.

04Rewiring webhooks

This is the one place where “compatible” stops. The event names are close and the signature scheme is not the same, so your receiver needs a real change — and the way to make that change safely is to run both verifiers at once.

The two differ in every dimension — header names, signed string, encoding of the result. There is no shim that makes one verify as the other, and you should be glad: a compatibility layer over a signature check is a place for a bypass to hide.

if (req.get('mailysend-signature')) {
  if (!verifyMailySend(req)) return res.sendStatus(400)
} else if (req.get('svix-signature')) {
  if (!verifySvix(req)) return res.sendStatus(400)
} else {
  return res.sendStatus(400)  // unsigned is not a third case
}

The retry behaviour is different too, and generally in your favour: six queue attempts, then a long tail at three, six, twelve and twenty-four hours, then the endpoint is disabled after twenty consecutive failures with replay available once you have fixed it. The webhooks guide has verifier code in six languages and the full ladder, which is the page to have open while you write this branch.

05A cutover you can undo

Move a percentage, not a system. The point of a percentage cutover is not caution for its own sake — it is that a problem shows up in a slice of your traffic instead of all of it, and that going back is a configuration change rather than a project.

Watch the two paths side by side, not the new one in isolation. Your bounce rate on the new system is meaningless without knowing what it is on the old one this week — plenty of “migration problems” turn out to be a bad list segment that was misbehaving equally on both, and you only discover that if you were looking at both.

Rolling back is genuinely cheap here, and that is by construction: the DNS for both systems is still published and verified, the old credential still works, and the send call is identical, so reverting is one configuration value. That property is the reason the DNS section insisted on alongside rather than instead of — it is what turns a roll back from an incident into a shrug.

06Where the two genuinely differ

Plainly, then, including the parts that do not favour this project. A comparison a reader cannot check is not worth reading, and a comparison that never loses is a comparison nobody should believe.

Where Resend is the better answer. It is a capable product with real people operating it, and if you do not want to run infrastructure, that is a legitimate choice rather than a failure of nerve. Concretely:

That framing matters because it tells you when to reconsider. If you migrate expecting a capability you did not have before, you will be disappointed — sending an email is a well-understood problem and both systems do it. If who holds the account, whose reputation the domain is building, who can change the pricing and who is able to read the contents of your mail is not currently a problem for you, this migration is work with no payoff, and you should not do it.

Common questions