Migrate from SendGrid

Keep your SendGrid SDK and change two lines, or adopt our SDK. Either way, the send you ship today keeps working.

Facts verified 2026-07-17 — corrections: hello@emailfast.dev

Two ways to switch

Email Fast speaks SendGrid's send API natively: SendGrid-, Mailgun-, and Postmark-compatible endpoints: point your existing SDK at a new base URL with a new key and keep your code — attachment sends are the one exception, refused with a clear error in your provider's own format rather than silently dropped. A successful call returns what your code already expects: an empty-body 202 with an X-Message-Id header.

Path 1 — keep @sendgrid/mail

  import sgMail from "@sendgrid/mail";
+ import sgClient from "@sendgrid/client";

+ sgClient.setDefaultRequest("baseUrl", "https://api.emailfast.dev");
+ sgMail.setClient(sgClient);
- sgMail.setApiKey(process.env.SENDGRID_API_KEY);
+ sgMail.setApiKey(process.env.EMAILFAST_API_KEY); // ef_sandbox_… works everywhere

  await sgMail.send({
    to: "ada@example.com",
    from: "you@yourdomain.com",
    subject: "Welcome",
    html: "<h1>Hi Ada</h1>",
+   headers: { "Idempotency-Key": "welcome-ada-1" }, // retry-safe (see below)
  });

Path 2 — adopt @email-fast/nodejs

- import sgMail from "@sendgrid/mail";
+ import { EmailFast } from "@email-fast/nodejs";

- sgMail.setApiKey(process.env.SENDGRID_API_KEY);
- await sgMail.send({
-   to: "ada@example.com",
-   from: "you@yourdomain.com",
-   subject: "Welcome",
-   html: "<h1>Hi Ada</h1>",
- });
+ const ef = new EmailFast({ apiKey: process.env.EMAILFAST_API_KEY, baseUrl: "https://api.emailfast.dev" });
+ await ef.send({
+   to: "ada@example.com",
+   subject: "Welcome",
+   html: "<h1>Hi Ada</h1>",
+   idempotency_key: "welcome-ada-1",
+ });

What maps 1:1

• Personalizations. Each personalization fans out to one message per recipient, carrying that personalization's cc/bcc on every copy — where SendGrid sends one message per personalization, each recipient here gets their own. If one recipient is blocked by policy, the whole call rolls back and returns a truthful 4xx — nothing half-queued.
• Scheduling. send_at — top-level or per-personalization — schedules the send.
• Templates. template_id resolves against a template whose slug equals the id: re-create your template under its old SendGrid id and dynamic-template sends keep working.
• The response contract. 202, empty body, X-Message-Id header.

One thing deliberately does not map: outbound attachments aren't supported yet, platform-wide, and a send carrying one is refused with a SendGrid-shaped 400 errors[] entry — never silently stripped.

Every message admitted this way passes the same checkpoint as every other ingress: every send — REST, SMTP, browser SDK, compatibility endpoints, broadcasts, automations — passes through one admission gate: idempotency, suppression, quota, and content policy in a single checkpoint no ingress can skip.

What moves by hand today

A hosted importer that pulls templates, contacts, and suppression lists across from your SendGrid account is planned. Today, templates re-create under their old ids and contacts and suppression lists move by CSV through the dashboard — and you can evaluate the whole send path with a sandbox key: sandbox keys (ef_sandbox_…) that run the real pipeline dry: real validation, real rendering, real events, a hosted capture inbox — and no email leaves.

The idempotency bonus

SendGrid's send endpoint has no idempotency. Ours does: pass an Idempotency-Key header and each recipient in a personalizations fan-out gets its own derived key, so a timeout-and-retry can never double-send part of a batch: a 202 from the API means the send is committed to a durable, partitioned outbox before we answer — a crash can't lose it, and a retry with the same idempotency key can't double-send.

Next

• Why teams leave SendGrid
• The full migration kit
• API docs