Skip to content

StartMove from Resend, SendGrid or Postmark

Move transactional email from Resend, SendGrid or Postmark

Move your app's email in steps. Send 1% of recipients through Shipmail, check the results, then raise the share. Your old provider sends the rest, and sends any email that goes over a Shipmail limit.

Last updated

Before you start

  • A verified sending subdomain with an active sender. See Transactional email. Before you add its DNS records, check that your old provider has no records on the same host names.
  • An API key with send access to the sender's mailbox, stored as SHIPMAIL_API_KEY.
  • The sender address stored as EMAIL_FROM.

Request fields

Shipmail's send request uses these fields. Shipmail and Resend also accept an Idempotency-Key header, so a retry does not send twice.

ShipmailResendSendGridPostmark
fromfromfrom.emailFrom
totopersonalizations[].to[].emailTo
subjectsubjectsubjectSubject
htmlhtmlcontent[] of type text/htmlHtmlBody
texttextcontent[] of type text/plainTextBody
reply_toreply_toreply_toReplyTo
headersheadersheadersHeaders
attachmentsattachmentsattachmentsAttachments
metadatatagscustom_argsMetadata, Tag
client_referenceNoneNoneNone
  • from is the bare sender address. Shipmail adds the sender name.
  • Leave out reply_to. The sender sets it to its reply mailbox.
  • headers is an array of name and value pairs.
  • attachments are base64 filename and content pairs.
  • metadata holds up to 20 scalar values.
  • client_reference is your own ID for the email, unique in your organization. Find a send by it with Exact lookup in Activity.

Add a helper that splits traffic

Put every send behind one helper. It picks the provider from a hash of the recipient address, so each person gets all their email from one provider. SHIPMAIL_PERCENT sets the share that goes through Shipmail.

// lib/email.ts
import { createHash } from "node:crypto";
import { sendWithOldProvider } from "./email-old-provider";

type Email = { to: string; subject: string; text?: string; html?: string };

// Share of recipients that get their email from Shipmail, from 0 to 100.
const SHIPMAIL_PERCENT = Number(process.env.SHIPMAIL_PERCENT ?? "0");

// An address always gets the same provider.
function usesShipmail(address: string): boolean {
  const hash = createHash("sha256").update(address.trim().toLowerCase()).digest();
  return (hash.readUInt32BE(0) / 2 ** 32) * 100 < SHIPMAIL_PERCENT;
}

export async function sendEmail(email: Email): Promise<void> {
  if (!usesShipmail(email.to)) return sendWithOldProvider(email);

  const { to, ...content } = email;
  const res = await fetch("https://shipmail.to/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SHIPMAIL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ from: process.env.EMAIL_FROM, to: [to], ...content }),
  });

  // 429 means a Shipmail limit. Send this email through the old provider.
  if (res.status === 429) return sendWithOldProvider(email);
  if (!res.ok) throw new Error(`Shipmail returned ${res.status}: ${await res.text()}`);
}

A 429 means a Shipmail limit, such as the transactional daily limit. The helper sends that email through the old provider. For any other error, the helper throws. See the error codes.

Move traffic in steps

  1. Deploy at 0%

    Deploy with SHIPMAIL_PERCENT=0. Nothing changes for your users. Use a sm_test_ key in staging to check the Shipmail path. Test keys deliver nothing. See Sandbox mode.

  2. Send 1%

    Set the share to 1. After a day, open Issues in Activity and check the bounce and complaint rates on the Transactional page.

  3. Raise the share

    Go to 10, 50 and then 100. On a paid plan, transactional email starts with a safety limit of 1,000 recipients a day, which rises after a clean week. Raise the share as the limit grows. If you already send more than that, request a migration review on the Transactional page with your last 30 days. A person answers within one business day. How the limit grows is in Limits.

  4. Turn off the old provider

    Keep the old provider for a week after you reach 100%. Late bounces and replies to earlier email still arrive there. Then remove its code, API keys and DNS records.

Webhooks

Add a Shipmail webhook next to the old one and handle both until the move is done. A bounce event includes the receiving server's response for each recipient, and whether Shipmail suppressed the address.

ShipmailResendSendGridPostmark
message.sentemail.sentprocessedNone
message.deliveredemail.delivereddeliveredDelivery
message.bouncedemail.bouncedbounceBounce
message.complainedemail.complainedspamreportSpamComplaint

Let a coding agent do it

Paste this prompt into Claude Code, Codex, Cursor or another coding agent in your app's repository. The agent adds the helper and keeps the old provider.

Move this app's transactional email to Shipmail without removing the current provider.

Read https://shipmail.to/docs/guides/move-transactional-email and https://shipmail.to/llms.txt first.

1. Find every place that sends email through the current provider.
2. If they do not use one sendEmail helper yet, route them all through one.
3. In the helper, send through POST https://shipmail.to/api/v1/messages for the share of recipients in SHIPMAIL_PERCENT. Keep the old provider for everyone else.
4. Read the API key from SHIPMAIL_API_KEY and the sender address from EMAIL_FROM. Set from to the bare sender address.
5. If Shipmail answers 429, send that email through the old provider instead.
6. Map the provider's delivery webhooks to message.delivered, message.bounced and message.complained.
7. Do not change DNS. Do not delete the old provider's code or keys.
8. Run the tests and list what you changed.