Introduction
The Bird API is a unified REST API for everything the platform does. This reference documents every public endpoint, generated from the same OpenAPI specification that drives the official SDKs, so the request and response shapes here are exactly what the wire carries.
The reference sidebar groups the most-used resources: Sending Email, Email Stats, Suppressions, Verify, Webhooks, and Documentation (the docs search API). Other public endpoints, including sending domains, inbound email, contacts and audiences, SMS, and WhatsApp, are reachable through search and the deep links in their guides. Workspaces, API keys, and dedicated IPs are managed in the dashboard rather than the public API.
Resource pages are deep-linked from the guides: when a guide mentions an endpoint, the link lands on its reference entry here.
Conventions
Every endpoint follows the same conventions. They are stated once here rather than repeated on each page.
- Base path — all endpoints live under /v1 on a regional host such as https://us1.platform.bird.com. See Base URLs & regions.
- Authentication — requests carry an API key as a bearer token: Authorization: Bearer bk_us1_.... See Authentication.
- JSON, snake_case — request and response bodies are JSON with snake_case field names (created_at, workspace_id), and requests must set Content-Type: application/json.
- Timestamps — all timestamps are RFC 3339 strings in UTC, in fields suffixed _at (created_at, delivered_at). Resource timestamps like created_at are server-assigned and read-only; a few request fields, such as scheduled_at, are timestamps you supply.
- Typed resource IDs — every ID carries a type prefix: em_ for email messages, dom_ for sending domains, whk_ for webhook endpoints, sup_ for suppressions, and so on. The prefix makes an ID self-describing in logs and prevents passing one resource's ID where another's is expected.
- Partial updates use PATCH — the API never uses PUT. A PATCH request changes only the fields you include; omitted fields are left untouched.
- Errors — every error response carries the same envelope, with a type for coarse branching, a stable code, a human-readable message, and the request_id to quote when contacting support. See Errors.
- Pagination — list endpoints use cursor-based pagination with a shared parameter set. See Pagination.
- Idempotency — mutating endpoints accept an Idempotency-Key header so retries are safe. See Idempotency.
Recommended clients
You can call the API with any HTTP client, but the official clients handle authentication, region selection, retries, and pagination for you:
- The official SDKs for TypeScript, Go, and Python — typed methods over the curated public surface
- The Bird CLI — the API from your terminal, also suited to scripts and agents
Read next
- Authentication — how requests authenticate at the wire level
- Base URLs & regions — regional hosts and the region model
- Pagination — cursors, page sizes, and sorting
- Idempotency — safe retries for mutating requests
- Errors — the error envelope and the full error catalog