Transactional or marketing, one message or a hundred, sent through the same Email API, with idempotency, suppression, and webhooks built in. Pass raw HTML or render your React Email templates.
import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { WelcomeEmail } from "./emails/welcome";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.email.send({
from: "Bird <hello@bird.com>",
to: ["ada@example.com"],
subject: "Your invite is ready",
html: await render(<WelcomeEmail name="Ada" />),
}).safe();
if (error) throw error;
console.log(data.id);
// → "em_2bX91Yk8h..."
You can sign in any time at bird.com/login.
Your test API key is on your dashboard, ready to send.
Send your first email in five minutes.
From the language you already use.
Sending is the core of the Bird Email API. Your first send can go to a sandbox address (delivered@messagebird.dev), so you can exercise the whole platform (sends, webhooks, suppression) before you verify a domain.
const msg = await bird.email.send({
from: { email: "onboarding@messagebird.dev", name: "Bird" },
to: ["delivered@messagebird.dev"],
subject: "Hello from Bird",
html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"Five things you don't build yourself.
The same contract on every Bird channel.
- 01
Transactional + marketing.
The same endpoint sends a password reset or a campaign. A category field decides how suppression and unsubscribes apply.
- 02
Templates your way.
Pass raw HTML, render React Email templates to HTML in your app and send the result, or name a stored template and have it rendered for you. Your toolchain, unchanged.
- 03
Batch up to 100.
Up to 100 independent messages per call, each with its own recipient and variables, validated as one unit so you never half-send.
- 04
Idempotent by contract.
Every send accepts an idempotency key, so a retried request after a timeout returns the original result instead of double-sending.
- 05
A webhook on every state change.
Accepted, delivered, opened, clicked, bounced, complained. Each one HMAC-signed, replay-protected, idempotent, the same envelope on every channel.
Already sending somewhere else? Switch in an afternoon.
The call you already make barely changes: swap the client, keep your templates, point your webhooks at one endpoint. Migration guides cover SendGrid, Amazon SES, Mailgun, and Resend.
import sgMail from "@sendgrid/mail";
sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
await sgMail.send({
from: "hello@yourdomain.com",
to: "delivered@messagebird.dev",
subject: "Your invite is ready",
html: "<p>Welcome aboard, Ada.</p>",
});
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
await bird.email.send({
from: "hello@yourdomain.com",
to: ["delivered@messagebird.dev"],
subject: "Your invite is ready",
html: "<p>Welcome aboard, Ada.</p>",
});
One message or a hundred, one call.
Batch up to 100 independent messages in one request, each with its own recipient and variables. The batch validates as a unit: one bad message rejects the call with a 422, so you never half-send. A single idempotency key makes the whole request safe to retry.
import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { Digest } from "./emails/digest";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const messages = await Promise.all(
users.map(async (u) => ({
from: "Acme <hello@yourdomain.com>",
to: [u.email],
subject: "Your weekly digest",
html: await render(<Digest user={u} />),
})),
);
const { data: batch, error } = await bird.email
.sendBatch(messages, { idempotencyKey: `digest-${runId}` })
.safe();
if (error) throw error;
console.log(`queued ${batch.data.length} messages`);
Attach your own context to every send.
Tags are a first-class, filterable dimension: slice delivery and engagement by campaign, template, or experiment in the stats API (up to 20 per message). Metadata is arbitrary JSON, up to 2 KB, that round-trips untouched on every read and webhook, so your own IDs ride along with the message.
await bird.email.send({
from: "Acme <hello@yourdomain.com>",
to: ["delivered@messagebird.dev"],
subject: "Your invite is ready",
html: "<p>Welcome aboard, Ada.</p>",
tags: [{ name: "campaign", value: "spring-2026" }],
metadata: { user_id: "u_2bX91", order_id: "ord_5512" },
});
Watch every message through its whole life.
A send returns 202 immediately; the outcome arrives as a webhook per recipient. Verify one signature, switch on the type: the same envelope you already handle for SMS, voice, and WhatsApp.
import { bird } from "@/lib/bird";
export async function POST(req: Request) {
const event = bird.webhooks.unwrap(
await req.text(),
Object.fromEntries(req.headers),
);
switch (event.type) {
case "email.delivered":
await markDelivered(event.data.email_id);
break;
case "email.bounced":
await flag(event.data.recipient, event.data.bounce_type);
break;
}
return new Response(null, { status: 204 });
}
Hard bounces, complaints, and unsubscribes also update your suppression list automatically, so a bad address never costs you reputation twice.
email.acceptedThe send was accepted and is being prepared for delivery.email.processedQueued for the recipient's mail server.email.deliveredThe recipient's mail server accepted the message.email.deferredTemporarily refused, and we will retry.email.bouncedPermanently failed: bounce type and SMTP code in the payload.email.openedThe recipient opened the message. Can fire more than once.email.clickedThe recipient clicked a tracked link.email.complainedThe recipient reported the message as spam.email.unsubscribedThe recipient opted out through a tracked unsubscribe link.
Test every outcome before you go live.
In the sandbox the recipient address decides the result, so your account state doesn't have to. Send to delivered@messagebird.dev for a clean delivery, or to bounce@, softbounce@, deferred@, complaint@, and suppressed@ to drive each failure path through the real pipeline and the real webhooks. No domain to verify, no risk to your reputation. Production is deliberately gated: you verify a domain first, and a new domain or dedicated IP ramps through warmup before it carries full volume.
Go deeper in the docs.
Read the sending guide, wire up email events and webhooks, or, if you're coming from another provider, follow a migration guide from SendGrid, SES, Mailgun, or Resend.
The rest of the Email platform
One API, one set of keys. Explore the other capabilities.
About 40% of the world's commercial email already runs on Bird.
Transactional and marketing email on infrastructure we've run for a decade. Sending is one capability of the Bird Email API: deliverability, dedicated IPs, suppression, and analytics ship with it.