Bird API

openapi: 3.1.0
info:
  title: Bird API
  version: 1.0.0
  description: |
    The Bird API: one REST API for email, SMS, WhatsApp, verification, and
    Realtime. Manage workspaces, organizations, teams, sending domains,
    dedicated IPs, suppressions, contacts and audiences, and outbound message
    delivery across every channel.

    Setting a `User-Agent` header is recommended but not required. Official Bird
    SDKs set it automatically (format: `bird-<language>/<version>`). The header is
    used for operational logging and customer-support diagnostics; the API never
    rejects requests that omit it.

    Rate limits are advertised on every response from a rate-limited endpoint as
    IETF `RateLimit` and `RateLimit-Policy` headers (Structured Fields per RFC
    9651; spec draft-ietf-httpapi-ratelimit-headers-11). On 429 responses, a
    `Retry-After` header in seconds is also returned. Clients should pace
    themselves against the `r` (remaining) and `t` (seconds until reset) params
    in the `RateLimit` header rather than only reacting to 429s.

    The full API reference is at https://bird.com/docs/api, and the guides and
    official SDKs at https://bird.com/docs.
servers:
  - url: https://{region}.platform.bird.com
    description: |
      Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
    variables:
      region:
        default: us1
        enum:
          - us1
          - eu1
        description: The region your organization's data is hosted in.
  - url: https://platform.bird.com
    description: Region-independent endpoint for authentication and account administration.
  - url: http://localhost:8080
    description: Local development.
security:
  - BearerAuth: []
tags:
  - name: workspaces
    description: Workspace management.
  - name: realtime-apps
    description: Realtime app management.
  - name: realtime-events
    description: |
      Publish events to a Realtime app's channels from your server (the data plane). Sending to several channels at once broadcasts to all of them.
  - name: email-messages
    description: |
      Send emails to recipients you address explicitly in `to`, `cc`, and `bcc`. Use this for transactional sends (receipts, password resets, alerts) and for marketing sends where you already have the recipient addresses on hand. The same endpoint accepts every content type. Set `category` to control suppression policy.
  - name: email-broadcasts
    description: |
      Send one email to a stored audience. Create a broadcast as a draft, then send it immediately or schedule it for later; scheduled and in-progress broadcasts can be canceled. The audience's contacts at send time become the recipient set after suppressions are applied. The recipients endpoint returns each recipient's delivery state.
  - name: email-contacts
    description: |
      Contacts are the people you send broadcasts to. Each contact is unique by email address within a workspace and carries optional name fields and custom properties for personalization. Custom properties are defined once per workspace via the contact properties API and then set per contact.
  - name: email-audiences
    description: |
      Audiences are the recipient lists broadcasts are sent to. An audience holds a set of contacts that you manage through the API. The contacts in the audience at send time become the broadcast's recipients after suppressions are applied. A contact can belong to multiple audiences.
  - name: email-stats
    description: Email analytics, including daily and hourly delivery statistics, tag breakdowns, and a KPI summary.
  - name: sms-messages
    description: |
      Send SMS messages to recipients you address by phone number, and read their delivery status and lifecycle events. Each message is one recipient and one body; set `category` to control opt-out policy and per-country compliance.
  - name: sms-templates
    description: Create and publish multilingual workspace SMS templates and browse built-in templates. Published workspace versions preserve their language content; built-in versions reflect the current catalogue.
  - name: sms-stats
    description: SMS analytics, including daily and hourly lifecycle counts, dimension breakdowns, and a KPI summary.
  - name: verify-verifications
    description: |
      Send a one-time passcode to a recipient and check the code they enter. Create a verification to send a passcode over email or SMS, then submit the recipient's code to verify it.
  - name: whatsapp-messages
    description: |
      Send WhatsApp messages, whether a template, free-form content, or interactive content the recipient can tap, and read the messages your workspace sent and received, including their current delivery status and lifecycle events.
  - name: whatsapp-templates
    description: |
      Browse the WhatsApp message templates available to your workspace, approved by Meta and ready to send.
  - name: whatsapp-stats
    description: WhatsApp analytics, including daily and hourly delivery statistics and a KPI summary.
  - name: domains
    description: Sending domain management and DNS verification.
  - name: email-suppressions
    description: Email suppression list management.
  - name: email-templates
    description: |
      Reusable email templates and their versions, with stored subject, HTML, and plain-text content you manage and reference when sending.
  - name: email-inbound-addresses
    description: |
      Addresses generated for receiving mail. Forward a mailbox to an inbound address to parse each message into a received email.
  - name: email-inbound-messages
    description: |
      Emails received on your behalf, including each parsed message, its body, raw MIME content, and attachments.
  - name: email-mailboxes
    description: |
      Durable mailbox identities for agents. A mailbox owns an address, applies receive policy through allow/block rules, and remembers conversations for its retention tier.
  - name: email-inbound-routes
    description: |
      Routing rules that direct inbound mail on your domains into mailboxes, or drop it, in priority order.
  - name: email-threads
    description: |
      Conversations in a mailbox. Threads group related inbound and outbound messages and carry read state, labels, and participants.
  - name: email-smtp-configs
    description: |
      Default IP pool, category, tags, and open and click tracking settings for messages submitted over SMTP with a given API key.
  - name: webhooks
    description: Webhook endpoint management.
  - name: numbers
    description: Phone number catalog and purchasing.
  - name: docs
    description: Search our developer documentation.
  - name: voice-calls
    description: Call records (CDR) for the workspace, in flight and completed.
  - name: whatsapp-numbers
    description: |
      Connect phone numbers from Meta's embedded signup flow and check their WhatsApp setup status.
  - name: whatsapp-business-accounts
    description: |
      Read the WhatsApp Business Accounts your workspace has connected, so a template can be created on the account you choose.
  - name: sms-keyword-rules
    description: |
      Manage the response when someone sends a keyword to one of your numbers. Each supported country starts with opt-out, opt-in, and help keywords. Create a rule to replace a default response or add campaign keywords.
  - name: lookup
    description: |
      Inspect a recipient before sending. Phone-number lookups return carrier, portability, number type, reachability, roaming, SIM-change, and fraud-risk data when requested. Email lookups return deliverability, confidence, failure reasons, and suggested corrections for likely misspellings.
  - name: sms-suppressions
    description: Sender and subscriber pairs that block SMS delivery.
  - name: email-competitive
    description: |
      Watch competitor brands and see how their email compares with yours. Figures about a competitor are estimates from an email panel, which observes a sample of real inboxes; figures about your own sending are counted rather than estimated wherever that is possible.
  - name: preferences
    description: Stated messaging preferences (consent grants and opt-outs) recorded per handle across email, SMS, and WhatsApp, with causally ordered writes.
  - name: email-inbox-insights
    description: |
      Inbox placement, seed tests, and sending reputation for the workspace's
      own sending domains, measured from a panel of real mailboxes.

      Rates here are percentages carrying a `_percent` suffix (`87.4`).
      Competitive Insights reports the same kind of figure as a fraction
      (`0.874`), so a client reading both products scales one of them.


# --- truncated at 32 KB (4697 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bird/refs/heads/main/openapi/messagebird-bird-api-openapi.yml