Quickstart

Send your first message with Bird in under five minutes.

Get a test API key

Open the dashboard and copy a test key — it'll look like bird_test_xxxxxxxx. Test keys send only to the sanctioned test recipients listed below, are free, and ship with full feature parity to live keys. Production unlocks when you add a payment method and verify a sender.

Install the SDK

pnpm add @bird/sdk
# npm install @bird/sdk
# yarn add @bird/sdk
# bun add @bird/sdk

Send your first message

import { BirdClient } from "@bird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email.send({
  to: ["delivered@bird.dev"],
  from: "Bird Test <onboarding@bird.dev>",
  subject: "Hello from Bird",
  text: "If you're reading this, the quickstart worked.",
});

if (error) throw error;
console.log(data.id); // email_2bX91...

SMS

const { data, error } = await bird.sms.send({
  to: "+15005550006",
  from: "+18885550101",
  text: "Your code is 482917.  Don't share it.",
});

Voice

const { data, error } = await bird.voice.calls.create({
  to: "+15005550010",
  from: "+18885550101",
  flow: {
    steps: [
      { type: "say", text: "Your code is four, eight, two, nine, one, seven." },
      { type: "hangup" },
    ],
  },
});

const { data, error } = await bird.whatsapp.send({
  to: "+15005550009",
  template: "order_confirmed",
  variables: { name: "Ada", order_id: "A-2491" },
});

What just happened

You hit POST /v1/emails and sent a real message to delivered@bird.dev — a sanctioned test recipient that always accepts a send and emits delivery events without touching the production carrier network. Every Bird call returns the same { data, error } envelope: data is the typed resource on success, error is the structured envelope documented at /docs/errors on failure. The send shows up in the dashboard under Logs within a second, with the full request, response, and per-step carrier trace.

Next steps

Verify a sending domain — graduate from test keys to live sends.
Subscribe to webhooks — email.delivered, sms.failed, call.completed, and the rest.
Handle errors — every type slug and what to do about it.
Drop the MCP server in your IDE — let Claude and Cursor send through Bird.