Send email

One API for every email you send.

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.

Start sending Read the sending guide

Create your account, then create an API key and send a test message.

Set up in:

CursorCopied!

welcome.tsx

200 · 1.2s

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..."

welcome.tsx

200 · 1.2s

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..."

Already sending through SMTP?

Keep your existing SMTP client and connect it to Bird’s relay. Use the SMTP setup page for regional hosts, TLS ports and authentication. If your application needs to receive and parse messages, start with inbound email.

Set up SMTP relay Receive inbound email

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.

Make the first request from your application.

Create an account and API key, then follow the sending guide with a test recipient.

Start sending

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.

sendgrid.ts

SendGrid

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>",
});

bird.ts

Bird

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.

digest.ts

202 · batch

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.

tagged.ts

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.

app/api/webhooks/bird/route.ts

signed

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 and complaints update recipient suppressions. Unsubscribes record an opt-out preference. Those records are checked when processing later sends.

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.

Test the behavior around the send.

A working send call is the beginning of an integration. Rehearse bounces and complaints, handle duplicate webhook deliveries and decide how your application schedules messages or receives replies.

Continue with the workflow you need

Choose the product or guide that matches the next job.

Email sandboxExercise delivery outcomes with documented test addresses.Scheduled messagesSet a future time for inline content and understand cancellation.Batch sendingSubmit independent messages together for a one-off recipient list.Email integration libraryFind setup, migration and troubleshooting guides.

Put it into practice.

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideGetting started with email Follow the learning pathBuild your first integration

Try the practice and get an implementation brief

Questions about sending email

Can I send both transactional and marketing email?

Yes, both go through the same send API. The only difference is the category field, which decides how suppressions and unsubscribes apply. Pick transactional for password resets and receipts, and marketing for campaigns.

What happens if a request times out and I retry it?

Send an Idempotency-Key header with each logical send. If the first request succeeded but you never saw the response, replaying it with the same key gives you the original result back with an Idempotency-Replay header, rather than sending the email twice.

Can I schedule a send for later?

Set scheduled_at to any time between 30 seconds and 30 days ahead. The send comes back accepted straight away and stays scheduled until it goes out, so you can cancel it at any point before then.

Can I attach files?

Yes, as base64 in the attachments array. To show an image inline, give it a content_id and reference that from your HTML with cid:. Keep the raw files at or below 15 MB so the message still fits the 20 MB cap once it is encoded, and note that executable and script content types are refused before the send.

Connect sending to the rest of your workflow

TemplatesStored, versioned email templates, personalized per recipient at send.DeliverabilityAuthentication, managed IP warmup, recipient suppressions and delivery signals.AnalyticsDelivery by domain, provider and IP, with separate engagement breakdowns.Email API overviewThe full Email API: sending, deliverability, IPs, suppression, analytics, and broadcasts.

Send your first message with Bird.

Create an API key, test your send and connect delivery events. Build from the integration you can already run.

Start sending Follow the first-send guide