Switch Email SDKs

Tinbox compat routes let you move transactional email into your own Cloudflare account without rewriting every send call first.

The point is not that you must keep provider SDKs forever. The point is that you can test-drive Tinbox before you touch your application code. Keep the SDK and dependencies you already ship, swap the API key, and change one host/base URL line. When you are ready, move to Tinbox-native APIs on your own schedule.

The simple version:

keep your current SDK
change the API key to a tbx_... key
change one SDK host/base URL line
send through Tinbox

Your app keeps the request shape it already uses. Tinbox translates that provider shape into the canonical Tinbox send pipeline: sender-scope checks, idempotency, suppressions, MIME building, dispatch, and delivery logs.

Every SDK path on this page is backed by a mirror test in @tinbox/compat-sdk-smoke: the official SDK is pointed at localhost, the mirror records the exact method, path, headers, content type, and body it posts, and the compat route is built from that captured wire shape.

The code snippets are also represented in the smoke package as TypeScript fixtures that import the official distributed SDK types. tsc --noEmit must accept those fixtures for Resend, SendGrid, Mailjet, Postmark, and Mailgun before we treat the guide as current.

Compat routes are for transactional sending. They do not clone provider dashboards, hosted templates, audience tools, contact APIs, or webhook signature systems. Those move separately.

Pick your SDK

TINBOX_HOST=https://mail.yourdomain.com
TINBOX_API_KEY=tbx_...
RESEND_BASE_URL=https://mail.yourdomain.com/api/send/compat/resend/v1

import { Resend } from "resend";
const resend = new Resend(process.env.TINBOX_API_KEY!, {
baseUrl: ${process.env.TINBOX_HOST}/api/send/compat/resend/v1,
});
await resend.emails.send({
from: "Acme <hello@yourdomain.com>",
to: "ada@example.com",
subject: "Your receipt",
html: "<p>Thanks.</p>",
});

import sgMail from "@sendgrid/mail";
import sgClient from "@sendgrid/client";
sgMail.setApiKey(process.env.TINBOX_API_KEY!);
sgClient.setDefaultRequest(
"baseUrl",
${process.env.TINBOX_HOST}/api/send/compat/sendgrid,
);
await sgMail.send({
from: "hello@yourdomain.com",
to: "ada@example.com",
subject: "Your receipt",
html: "<p>Thanks.</p>",
});

import Mailjet from "node-mailjet";
const mailjet = new Mailjet({
apiKey: "tinbox",
apiSecret: process.env.TINBOX_API_KEY!,
config: { host: "mail.yourdomain.com/api/send/compat/mailjet", version: "v3.1" },
});
await mailjet.post("send", { version: "v3.1" }).request({
Messages: [{
From: { Email: "hello@yourdomain.com", Name: "Acme" },
To: [{ Email: "ada@example.com" }],
Subject: "Your receipt",
HTMLPart: "<p>Thanks.</p>",
}],
});

import postmark from "postmark";
const client = new postmark.ServerClient(process.env.TINBOX_API_KEY!, {
useHttps: true,
requestHost: "mail.yourdomain.com",
});
await client.sendEmail({
From: "hello@yourdomain.com",
To: "ada@example.com",
Subject: "Your receipt",
HtmlBody: "<p>Thanks.</p>",
});

import Mailgun from "mailgun.js";
const mailgun = new Mailgun(FormData);
const mg = mailgun.client({
username: "api",
key: process.env.TINBOX_API_KEY!,
url: ${process.env.TINBOX_HOST}/api/send/compat/mailgun,
});
await mg.messages.create("yourdomain.com", {
from: "hello@yourdomain.com",
to: ["ada@example.com"],
subject: "Your receipt",
html: "<p>Thanks.</p>",
});

What stays the same

For simple transactional email, most projects keep the same application-level send call:

• same from, to, cc, bcc
• same subject
• same html and text
• same base64 attachments
• same reply-to intent
• same SDK-side ergonomics

What changes is the delivery plane. The API key becomes a Tinbox sending key, the host points at your Tinbox deployment, and Tinbox stores the send ledger in your database.

Compatibility levels

Provider routes

Every provider gets a Tinbox-owned compat path under /api/send/compat. Some providers also get vendor-style aliases so official SDKs with host-only config can still work.

The official SDK mirror suite currently validates these package versions:

Full parity matrix

Compatibility warnings

Dangerous gaps fail fast with 422: hosted templates, scheduled sends, and raw MIME routes that Tinbox does not support yet. Lower-risk degraded fields are accepted but return an X-Tinbox-Compat-Warnings header. The response body stays provider-shaped so official SDKs keep parsing it.

Examples of warning-only fields:

SDK gaps at a glance

These are the gaps that should be visible before a user changes production traffic. Compat routes should either reject these fields clearly or document that the value is ignored.

What does not move through compat routes

Compat routes are deliberately narrow. These should be migrated to Tinbox-native features or app code:

• provider-hosted templates
• scheduled send APIs
• broadcasts, audiences, contacts, and marketing list APIs
• provider webhook signature verification
• provider analytics dashboards
• domain and sender management APIs
• raw MIME passthrough

Recommended migration path

1. Deploy Tinbox and verify your sending domain.
2. Create a Tinbox sending API key scoped to your app's from address or domain.
3. Pick your current SDK above and change only the key and one host/base URL line.
4. Send a smoke test from the same from address production uses.
5. Check the Tinbox send ledger and the received email's SPF/DKIM/DMARC headers.
6. Move advanced provider features one by one after simple sends are stable.

Detailed guides

• Switch from Resend
• Switch from SendGrid
• Switch from Mailjet
• Switch from Postmark
• Switch from Mailgun