My first Bird email.
\",\n});\n\nconsole.log(msg.id, msg.status);\n```\n\nThe region is inferred from the API key prefix (`bk_{region}_ā¦`). For a local or self-hosted server, pass `baseUrl` (which overrides region resolution).\n\n## Client defaults\n\nSet channel defaults and the webhook secret once at construction. Defaulted fields become optional on each call (the per-call value wins), enforced by the types.\n\n```ts\nconst bird = new BirdClient({\n apiKey: process.env.BIRD_API_KEY!,\n email: { from: \"hello@acme.com\" }, // now optional in email.send\n webhooks: { secret: process.env.BIRD_WEBHOOK_SECRET! },\n});\n\nawait bird.email.send({ to: [\"customer@example.com\"], subject: \"Hi\", html: \"ā¦\" });\n```\n\n## Email\n\n```ts\nawait bird.email.send({ from, to, subject, html }); // resolves when accepted (202)\nawait bird.email.get(messageId); // aggregate delivery status\n\n// `await` yields the first page; `for await` walks every message across pages.\nfor await (const message of bird.email.list()) {\n console.log(message.id);\n}\n```\n\n## WhatsApp\n\n```ts\nawait bird.whatsapp.send({ to, template }); // resolves when accepted (202); `from` is required except for a Bird-managed template\nawait bird.whatsapp.get(messageId); // delivery status + failure detail\n\n// `await` yields the first page; `for await` walks every message across pages.\nfor await (const message of bird.whatsapp.list()) {\n console.log(message.id);\n}\n\nconst { data } = await bird.whatsapp.listEvents(messageId); // full lifecycle timeline, not paginated\n```\n\n## Lookup\n\nEvery answer is billed. A phone number lookup bills once for the base answer plus once per **delivered** property; an email lookup bills once per answered address. Nothing is billed for a failed lookup, and nothing is billed for a property that came back unanswered, so read `status` before you read a value.\n\n```ts\nconst number = await bird.lookup.phoneNumber({ phone_number, type: [\"score\"] });\nnumber.country_code; // base answer: always present, always billed\nif (number.score?.status === \"ok\") number.score.value; // only `ok` carries a value, and only `ok` is billed\n\nconst address = await bird.lookup.email({ email });\naddress.result; // valid | neutral | risky | undeliverable | typo: an open vocabulary\naddress.delivery_confidence; // 0-100, always present: the safe fallback for a verdict you don't know\n```\n\nPass an `Idempotency-Key` so a retry replays the stored answer instead of buying a second one.\n\n## Webhooks\n\n`unwrap` verifies a delivery's Standard Webhooks signature and returns a typed, discriminated event. **Pass the raw request body** ā never the parsed JSON. Set the signing secret once via `webhooks: { secret }` on the client (or pass `{ secret }` per call).\n\n```ts\nconst event = bird.webhooks.unwrap(rawBody, request.headers);\nswitch (event.type) {\n case \"email.delivered\":\n console.log(event.email_id, event.recipient); // narrowed; fields are flat\n break;\n default: // unknown future events land here ā forward-compatible\n}\n```\n\n> Endpoint management (registering/listing webhook endpoints) is not in this release; it returns once the delivery substrate stabilises.\n\n## Errors\n\nMethods **throw** on failure with a typed error hierarchy you narrow with `instanceof`:\n\n\n\n```ts\nimport { BirdRateLimitError, BirdValidationError, BirdAPIError } from \"@messagebird/sdk\";\n\ntry {\n await bird.email.send({\n from: { email: \"onboarding@messagebird.dev\", name: \"Bird\" },\n to: [\"delivered@messagebird.dev\"],\n subject: \"Hello from Bird\",\n html: \"My first Bird email.
\",\n });\n} catch (err) {\n if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);\n else if (err instanceof BirdValidationError) console.error(err.details);\n else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);\n else throw err;\n}\n```\n\nEvery API error carries `statusCode`, `requestId`, and `type`. The core retries safely on `429`/`5xx`/network failures (mutations reuse one idempotency key across attempts).\n\nPrefer to branch on a value instead of catching? Use `.safe()`:\n\n\n\n```ts\nconst { data, error } = await bird.email\n .send({\n from: { email: \"onboarding@messagebird.dev\", name: \"Bird\" },\n to: [\"delivered@messagebird.dev\"],\n subject: \"Hello from Bird\",\n html: \"My first Bird email.
\",\n })\n .safe();\nif (error) console.error(error.message);\nelse console.log(data.id);\n```\n\nAnd `.withResponse()` exposes transport metadata (status, headers, request id) on success:\n\n```ts\nconst { data, response } = await bird.email.list().withResponse();\nresponse.headers.get(\"ratelimit-remaining\");\n```\n\n## Escape hatch\n\nFor endpoints the typed resources don't cover yet, `request