Email API for
Node.js.
Send inside a trusted service request or enqueue work for a background job. The application owns its job identity and correlation with the returned email ID.
To a traceable send.
See the first send.
npm install @messagebird/sdk tsxnpx tsx send.mtsimport { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
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);
Onboarding sender and sandbox recipient only. This page does not send an email or contain a key.
ZIP with the displayed request, setup notes and an empty key template. A sandbox code sample, not a complete application. SDK version in the sample: 0.67.0; review current maintained setup before adapting it.
em_01ky7ma8y2es1s2akzk53tmjn0 accepted
The returned ID lets you retrieve the message and follow recipient events. Acceptance does not prove delivery or inbox placement.
If your sender is not verified
A sender outside your verified domain or the onboarding domain is refused before sending. Correct the sender setup; a rejected request is not a delivery event.
Sending domains guideIf the response is missing
Keep the original operation unresolved and inspect its record before repeating it. The SDK reuses identity for retries within one call; a new invocation normally creates a new operation. Your application owns durable job identity and deliberate replay. Completed responses are retained for three hours; after expiry, the same key can start a new operation. Retention does not make side effects atomic. Follow the idempotency guide before replaying. This sample does not provide a retry queue.
Idempotency and recovery guide ↗SDK request and retry optionsRuntime and installation.
Bird’s TypeScript quickstart uses the ESM-only @messagebird/sdk on Node.js 20.3+ and runs its sample with tsx.
Choose where to send.
Use a service request when the caller needs immediate acceptance. Use a worker when your workflow needs its own queue and recovery. A 202 is acceptance; track delivery separately.
Track delivery and retries.
Persist your operation identity and the accepted email ID. A fresh SDK call after an ambiguous result needs deliberate idempotency handling; do not equate a job retry with a new message. A transport error or “send failed” log can leave acceptance unknown; reconcile the original operation before retrying.
Prepare for
production sending.
Verify a production domain, keep your key on the server, and follow the recipient outcome separately from request acceptance.
For example, 10,000 signups with one welcome and one follow-up imply 20,000 planned sends before other traffic. Confirm actual processed units and peak daily volume, then compare included units, domain/webhook limits, overage and the send ceiling. Count dedicated IPs or other Email products separately where applicable. Sandbox testing is not an unlimited free-production offer.
Current Email plans and usage rates ↗ · Compare provider responsibilities and commercial units ↗