> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Bird

The Bird connector lets your AI agent act in each user's Bird account. Each user connects their own Bird access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 457 tools.

**Authentication:** Bearer Token
**Categories:** Communication, Marketing
**Tools:** 457: 252 read, 155 write, 50 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BIRD)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Bird connection

   In **AgentKit > Connections**, create a Bird connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'bird'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Bird:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'bird_amb_business_accounts_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "bird"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Bird:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="bird_amb_business_accounts_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Bird credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'bird_amb_attachment_get',
  toolInput: {
    attachment_id: '<attachment_id>',
  },
  connector: 'bird',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="bird_amb_attachment_get",
    tool_input={
        "attachment_id": "<attachment_id>",
    },
    connection_name="bird",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `bird_amb_attachment_get`

Get Apple Messages Attachment · Read-only

Return the metadata of an attachment by its `aat_` ID.
Returns an object with id, business_account_id, origin, message_id, name, mime_type, size, expires_at, created_at.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `attachment_id` (`string`, required): Attachment identifier. Starts with `aat_`. Example: aat_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"attachment_id":"<attachment_id>"}`

### `bird_amb_business_account_events_list`

List Apple Business Account Events · Read-only

Return account activity with event time, summary and source metadata, newest first by default.
Returns data, an array of items with id, type, summary, metadata, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs business_account_id from bird_amb_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_business_account_get`

Get Apple Messages for Business Record · Read-only

Return your workspace's Apple Messages for Business record, including its current status with Apple.
Returns an object with id, apple_business_id, name, status, status_reason, invitations_enabled, created_at, updated_at, next, account_review_status, finish_setup_url.
Use this when you have the ID. Use bird_amb_business_accounts_list to find one.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, required): Bird business account ID (abz_) or Apple business UUID. Both resolve within the current workspace. Example: abz_01jbx7k3m9p2q5r8s4t6v0w1yz

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_business_account_submissions_list`

List Apple Messages for Business Submissions · Read-only

Return review attempts with frozen evidence for this business, newest first, with fresh private evidence URLs.
Returns data, an array of items with id, business_account_id, apple_business_id, name, readiness_attachment, use_cases_attachment, video_attachment, status, status_reason, decided_by, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs business_account_id from bird_amb_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_business_accounts_list`

List Apple Messages for Business Records · Read-only

Return a paginated list of your workspace's Apple Messages for Business records.
Returns data, an array of items with id, apple_business_id, name, status, status_reason, invitations_enabled, created_at, updated_at, next, account_review_status, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_business_account_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_amb_channel_settings_get`

Get Apple Messages for Business Channel Settings · Read-only

Return the channel settings for your workspace's Apple Messages for Business record: its entry points, default locale, and the brand name and logo shown on the landing page customers use to connect it.
Returns an object with entry_points, default_locale, brand_name, logo_asset_id.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_conversation_get`

Get Apple Messages Conversation · Read-only

Return one conversation, including closed conversations.
Returns an object with inbox_status, recipient, routing, routing_change, last_message, id, business_account_id, status, origin, device_capabilities, supported_content_kinds, locale and more.
Use this when you have the ID. Use bird_amb_conversations_list to find one.
Needs conversation_id from bird_amb_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_amb_conversation_messages_list`

List Apple Messages Messages in a Conversation · Read-only

Return the messages in a conversation, newest first, both received and sent.
Returns data, an array of items with id, conversation_id, business_account_id, from, to, direction, status, kind, source, text, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs conversation_id from bird_amb_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
- `direction` (`string`, optional): Filter to received (`inbound`) or sent (`outbound`) messages. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_amb_conversation_stats_summary_get`

Get Aggregate Apple Messages for Business Conversation Statistics · Read-only

Return one aggregate row of Apple Messages for Business conversation lifecycle counts (`started`, `reopened`, `closed`, `conversations`) for the requested period.
Returns an object with period, attribution, counts, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset such as `+05:45` is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `to`. When omitted, it defaults to 30 days before `to` for day windows or 168 hours (7 days) before `to` for hour windows. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `from`. When omitted, it defaults to today for day windows or the current hour for hour windows in that timezone. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_amb_conversation_stats_timeseries_get`

Get Apple Messages for Business Conversation Statistics Time Series · Read-only

Get Apple Messages for Business conversation statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, counts, plus period, attribution.
Use this for trends over time. Use bird_amb_conversation_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to today in that timezone when omitted. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_amb_conversations_list`

List Apple Messages Conversations · Read-only

Return the conversations your business has with customers on Apple Messages for Business, newest first by last message.
Returns data, an array of items with inbox_status, recipient, routing, routing_change, last_message, id, business_account_id, status, origin, device_capabilities, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_conversation_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `assigned_to` (`string`, optional): Return conversations assigned to this workspace member. Pass `me` for the signed-in user or `unassigned` for conversations without an assignee. An API key cannot use `me` and receives a `422` response. Example: unassigned
- `business_account_id` (`string`, optional): Filter to conversations belonging to this business. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `group_id` (`string`, optional): Filter to conversations with this entry point group, as sent in Apple's groupID. Conversations whose entry point carried no group match only when this filter is omitted. Example: support
- `inbox_status` (`string`, optional): Filter by workspace inbox status. Omit to include open and resolved conversations. Example: open. One of: `open`, `resolved`.
- `intent_id` (`string`, optional): Filter to conversations with this entry point intent, as sent in Apple's intentID. Conversations whose entry point carried no intent match only when this filter is omitted. Example: order_status
- `label` (`array`, optional): Return conversations carrying this label, matched in any casing. Repeat the parameter to require every supplied label. A name the workspace doesn't have matches nothing. Example: ["billing"]
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `queue` (`string`, optional): Filter to conversations in this queue. Pass an empty string to match unrouted conversations, the ones no routing rule has claimed. Example: support
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter to conversations with this status. Omit to return both open and closed conversations. Example: open. One of: `open`, `closed`.

Example input: `{}`

### `bird_amb_inbound_stats_breakdown_get`

Get Inbound Apple Messages for Business Statistics Breakdown · Read-only

Get inbound Apple Messages for Business statistics for a period grouped by one dimension (dimension): businesses, intents. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_amb_inbound_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/amb/stats/inbound/. Example: businesses. One of: `businesses`, `intents`.
- `from` (`string`, optional): Inclusive start of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Must not be after `to`. Max window 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-06-14
- `limit` (`integer`, optional): Maximum number of business rows to return, ranked by received volume descending. Example: 50
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Max window 365 days. Defaults to today in that timezone when omitted. Example: 2026-07-13

Example input: `{"dimension":"businesses"}`

### `bird_amb_inbound_stats_summary_get`

Get Aggregate Inbound Apple Messages for Business Statistics · Read-only

Return one aggregate row of inbound Apple Messages for Business counts for the requested period.
Returns an object with period, attribution, received, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset such as `+05:45` is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `to`. When omitted, it defaults to 30 days before `to` for day windows or 168 hours (7 days) before `to` for hour windows. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `from`. When omitted, it defaults to today for day windows or the current hour for hour windows in that timezone. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_amb_inbound_stats_timeseries_get`

Get Inbound Apple Messages for Business Statistics Time Series · Read-only

Get inbound Apple Messages for Business statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, received, plus period, attribution.
Use this for trends over time. Use bird_amb_inbound_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to today in that timezone when omitted. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_amb_message_events_list`

List Apple Messages Events for a Message · Read-only

Return a message's lifecycle events in chronological order, one entry per status transition (`amb.accepted`, `amb.sent`, `amb.send_failed`, `amb.received`).
Returns data, an array of items with id, type, occurred_at, error.
Needs message_id from bird_amb_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message identifier. Starts with `amb_`. Example: amb_01krdgeqcxet5s7t44vh8rt9mg
- `type` (`string`, optional): Keep only events of this exact type (for example `amb.sent` or `amb.send_failed`). Omit for the full timeline.

Example input: `{"message_id":"<message_id>"}`

### `bird_amb_message_get`

Get Apple Messages Message · Read-only

Return a single Apple Messages for Business message: its current status, the content it carries, and failure detail when it failed.
Returns an object with id, conversation_id, business_account_id, from, to, direction, status, kind, source, text, rich_link, interactive and more.
Use this when you have the ID. Use bird_amb_messages_list to find one.
Needs message_id from bird_amb_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message identifier. Starts with `amb_`. Example: amb_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>"}`

### `bird_amb_messages_list`

List Apple Messages Messages · Read-only

Return your business's Apple Messages for Business messages across conversations, newest first, both received and sent.
Returns data, an array of items with id, conversation_id, business_account_id, from, to, direction, status, kind, source, text, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_message_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, optional): Filter to messages belonging to this business. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Filter to outbound messages sent with this category, exact match. Example: order_update
- `conversation_id` (`string`, optional): Filter to messages belonging to this conversation. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `direction` (`string`, optional): Filter to received (`inbound`) or sent (`outbound`) messages. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `kind` (`string`, optional): Filter to messages whose content is this shape. Example: text. One of: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`.
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reference` (`string`, optional): Keep only messages whose `reference` is exactly this value. The match is case-sensitive, and several messages can share a reference. Example: INV-1234
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter to messages with this status. Example: accepted. One of: `accepted`, `sent`, `send_failed`, `rejected`, `received`.
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.

Example input: `{}`

### `bird_amb_routing_rule_get`

Get Apple Messages for Business Routing Rule · Read-only

Return a single routing rule by ID, including its `business_account_id`, match condition (`match_kind`, `match_intent_id`, `match_group_id`), target `queue`, `precedence`, and `is_default` status.
Returns an object with created_at, updated_at, id, business_account_id, match_kind, match_intent_id, match_group_id, queue, precedence, is_default.
Use this when you have the ID. Use bird_amb_routing_rules_list to find one.
Needs routing_rule_id from bird_amb_routing_rules_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `routing_rule_id` (`string`, required): ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"routing_rule_id":"<routing_rule_id>"}`

### `bird_amb_routing_rules_list`

List Apple Messages for Business Routing Rules · Read-only

Return the workspace's Apple Messages for Business routing rules, highest precedence first.
Returns data, an array of items with created_at, updated_at, id, business_account_id, match_kind, match_intent_id, match_group_id, queue, precedence, is_default.
Use this to browse or filter. Use bird_amb_routing_rule_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, optional): Keep only routing rules belonging to this business. Omit to return rules across all businesses in the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{}`

### `bird_amb_stats_breakdown_get`

Get Outbound Apple Messages for Business Statistics Breakdown · Read-only

Get outbound Apple Messages for Business statistics for a period grouped by one dimension (dimension): businesses, message kinds, intents, groups, categories, tags, error codes. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_amb_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/amb/stats/. Example: businesses. One of: `businesses`, `message-kinds`, `intents`, `groups`, `categories`, `tags`, `error-codes`.
- `from` (`string`, optional): Inclusive start of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Must not be after `to`. Max window 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-06-14
- `limit` (`integer`, optional): Maximum number of business rows to return, ranked by accepted volume descending. Example: 50
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Max window 365 days. Defaults to today in that timezone when omitted. Example: 2026-07-13

Example input: `{"dimension":"businesses"}`

### `bird_amb_stats_summary_get`

Get Aggregate Outbound Apple Messages for Business Statistics · Read-only

Return one aggregate row of outbound Apple Messages for Business counts and latency percentiles (`p50`, `p95`, and `p99`) for the requested period.
Returns an object with monthly_active_contacts, period, attribution, counts, latency, first_response, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, optional): Restrict the statistics to a single business. Mutually exclusive with the other dimension filters (`message_kind`, `intent`, `group`, `category`, `tag`); only one may be set per request. Matches the `business_account_id` key on a row of the per-business breakdown. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Restrict the statistics to a single message category. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `group`, `tag`); only one may be set per request. Matches the `category` key on a row of the per-category breakdown. Example: order_update
- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. The comparison window carries any dimension filter set on the request, so a filtered comparison compares like with like. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset such as `+05:45` is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `to`. When omitted, it defaults to 30 days before `to` for day windows or 168 hours (7 days) before `to` for hour windows. Example: 2026-05-01
- `group` (`string`, optional): Restrict the statistics to a single entry-point group. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `category`, `tag`); only one may be set per request. Matches the `group` key on a row of the per-group breakdown. Example: sales
- `intent` (`string`, optional): Restrict the statistics to a single entry-point intent. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `group`, `category`, `tag`); only one may be set per request. Matches the `intent` key on a row of the per-intent breakdown. Example: order_support
- `message_kind` (`string`, optional): Restrict the statistics to a single message content kind. Mutually exclusive with the other dimension filters (`business_account_id`, `intent`, `group`, `category`, `tag`); only one may be set per request. Matches the `message_kind` key on a row of the per-content-kind breakdown. Example: text. One of: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`.
- `tag` (`string`, optional): Restrict the statistics to a single tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `group`, `category`); only one may be set per request. A row of the per-tag breakdown carries the same pair in its single `tag` key. Example: campaign:spring_launch
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `from`. When omitted, it defaults to today for day windows or the current hour for hour windows in that timezone. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_amb_stats_timeseries_get`

Get Outbound Apple Messages for Business Statistics Time Series · Read-only

Get outbound Apple Messages for Business statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, counts, latency, plus period, attribution.
Use this for trends over time. Use bird_amb_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `business_account_id` (`string`, optional): Restrict the statistics to a single business. Mutually exclusive with the other dimension filters (`message_kind`, `intent`, `group`, `category`, `tag`); only one may be set per request. Matches the `business_account_id` key on a row of the per-business breakdown. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Restrict the statistics to a single message category. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `group`, `tag`); only one may be set per request. Matches the `category` key on a row of the per-category breakdown. Example: order_update
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `group` (`string`, optional): Restrict the statistics to a single entry-point group. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `category`, `tag`); only one may be set per request. Matches the `group` key on a row of the per-group breakdown. Example: sales
- `intent` (`string`, optional): Restrict the statistics to a single entry-point intent. Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `group`, `category`, `tag`); only one may be set per request. Matches the `intent` key on a row of the per-intent breakdown. Example: order_support
- `message_kind` (`string`, optional): Restrict the statistics to a single message content kind. Mutually exclusive with the other dimension filters (`business_account_id`, `intent`, `group`, `category`, `tag`); only one may be set per request. Matches the `message_kind` key on a row of the per-content-kind breakdown. Example: text. One of: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`.
- `tag` (`string`, optional): Restrict the statistics to a single tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). Mutually exclusive with the other dimension filters (`business_account_id`, `message_kind`, `intent`, `group`, `category`); only one may be set per request. A row of the per-tag breakdown carries the same pair in its single `tag` key. Example: campaign:spring_launch
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to today in that timezone when omitted. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_amb_suppression_get`

Get Apple Messages for Business Suppression · Read-only

Return the suppression episode for the given ID, including one that has already ended.
Returns an object with id, business_account_id, address, address_type, reason, origin, applies_to, source_message_id, source_event_id, source_end_message_id, effective_at, created_at and more.
Use this when you have the ID. Use bird_amb_suppressions_list to find one.
Needs suppression_id from bird_amb_suppressions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression episode to retrieve or end. Example: asp_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_amb_suppressions_list`

List Apple Messages for Business Suppressions · Read-only

Return a paginated list of the workspace's active Apple Messages for Business suppressions: customers who have opted out of one brand, or of the whole workspace.
Returns data, an array of items with id, business_account_id, address, address_type, reason, origin, applies_to, source_message_id, source_event_id, source_end_message_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_suppression_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address` (`string`, optional): Prefix filter on the suppressed phone number or opaque identifier (case-insensitive). A complete value returns only that address; a partial value returns every match. Example: +15551234567
- `address_type` (`string`, optional): Keep only suppressions of this kind. Example: opaque_user_id. One of: `phone_number`, `opaque_user_id`.
- `business_account_id` (`string`, optional): Keep only suppressions for this brand, including the workspace-wide ones that block it too. Omit to see suppressions for every brand in the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reason` (`string`, optional): Keep only suppressions with this reason. Example: manual
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_amb_template_get`

Get Apple Messages Template · Read-only

Return one Apple Messages template's metadata, policies, language states, draft revision, and draft and live version IDs.
Returns an object with id, workspace_id, slug, name, description, scope, status, category, content_kind, customize_before_use, draft_version_id, live_version_id and more.
Use this when you have the ID. Use bird_amb_templates_list to find one.
Needs template_ref from bird_amb_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`amt_…`) or slug. Built-in templates use a `bird_` slug. Write operations accept workspace templates because built-in templates are read-only. Example: bird_otp_verification

Example input: `{"template_ref":"<template_ref>"}`

### `bird_amb_template_version_get`

Get Apple Messages Template Version · Read-only

Return one version with its variables and text in every language.
Returns an object with id, template_id, version_number, status, revision, variables, languages, default_language, created_at, published_at.
Use this when you have the ID. Use bird_amb_template_versions_list to find one.
Needs template_ref from bird_amb_templates_list; version_id from bird_amb_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`amt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version to read or reset. Example: amv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_amb_template_version_language_get`

Get Apple Messages Template Version's Language · Read-only

Return one language's full text, revision, content hash, and update time.
Returns an object with language, text, rich_link, interactive, revision, content_hash, updated_at.
Use this when you have the ID. Use bird_amb_template_version_languages_list to find one.
Needs template_ref from bird_amb_templates_list; version_id from bird_amb_template_versions_list; language from bird_amb_template_version_languages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Case and separator differences are accepted and canonicalized. Example: pt-BR
- `template_ref` (`string`, required): The template's ID (`amt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version that holds the language. Example: amv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_amb_template_version_languages_list`

List Apple Messages Template Version's Languages · Read-only

Return the languages a version holds, ordered by canonical language tag, without their text.
Returns data, an array of items with language, revision, content_hash, updated_at.
Use this to browse or filter. Use bird_amb_template_version_language_get when you already have the ID.
Needs template_ref from bird_amb_templates_list; version_id from bird_amb_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`amt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version whose languages to list. Example: amv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_amb_template_versions_list`

List Apple Messages Template's Versions · Read-only

Return a cursor-paginated version history, newest first.
Returns data, an array of items with id, template_id, version_number, status, revision, variables, default_language, available_languages, created_at, published_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_template_version_get when you already have the ID.
Needs template_ref from bird_amb_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`amt_…`) or slug. Example: order-shipped
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"template_ref":"<template_ref>"}`

### `bird_amb_templates_list`

List Apple Messages Templates · Read-only

Return Apple Messages templates as a cursor-paginated list.
Returns data, an array of items with id, workspace_id, slug, name, description, scope, status, category, content_kind, customize_before_use, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_amb_template_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Return templates in this category. Example: transactional. One of: `transactional`, `marketing`.
- `content_kind` (`string`, optional): Return templates whose live or draft content is this kind. Example: text. One of: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `language` (`string`, optional): Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match. Example: pt-BR
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `q` (`string`, optional): A case-insensitive substring search across slug, name, and description. Example: jane
- `scope` (`string`, optional): Filter by who owns the template. Use `system` for built-in templates and `workspace` for templates your workspace created. Example: system. One of: `system`, `workspace`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Return templates with this lifecycle status. Example: active. One of: `draft`, `pending`, `active`, `rejected`, `inactive`.

Example input: `{}`

### `bird_asset_folder_get`

Get Media-library Folder by ID · Read-only

Return one folder from the workspace's media library, including its resolved path.
Returns an object with created_at, updated_at, id, name, parent_id, path.
Use this when you have the ID. Use bird_asset_folders_list to find one.
Needs folder_id from bird_asset_folders_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `folder_id` (`string`, required): ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"folder_id":"<folder_id>"}`

### `bird_asset_folders_list`

List Workspace Media-library Folders · Read-only

Return the workspace's media-library folders as a flat list, each carrying its `parent_id` and its resolved `path`, most recently created first.
Returns data, an array of items with created_at, updated_at, id, name, parent_id, path, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_asset_folder_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_asset_get`

Get Media-library Asset by ID · Read-only

Return one media-library asset. An asset that has been removed from the library is returned with `deleted_at` set rather than as a missing resource, because its URL keeps serving and messages already sent still reference it.
Returns an object with created_at, updated_at, id, url, thumbnail_url, name, content_type, kind, size_bytes, width, height, alt_text and more.
Use this when you have the ID. Use bird_assets_list to find one.
Needs asset_id from bird_assets_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"asset_id":"<asset_id>"}`

### `bird_asset_references_list`

List Editable Resources That Use an Asset · Read-only

Return editable resources that reference this asset.
Returns data, an array of items with resource_type, resource_id, resource_name, usage, plus truncated.
Needs asset_id from bird_assets_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"asset_id":"<asset_id>"}`

### `bird_asset_upload_session_get`

Get Media-library Upload Session · Read-only

Return the upload session and its saved publication receipt.
Returns an object with id, state, expires_at, name, alt_text, folder_id, file, result, last_error, next, asset.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `upload_id` (`string`, required): ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"upload_id":"<upload_id>"}`

### `bird_assets_list`

List Workspace Media-library Assets · Read-only

Return a cursor page of the workspace's media-library assets, most recently created first.
Returns data, an array of items with created_at, updated_at, id, url, thumbnail_url, name, content_type, kind, size_bytes, width, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_asset_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `content_type` (`string`, optional): Return only assets stored with this media type. Example: image/png. One of: `image/png`, `image/jpeg`, `image/gif`, `video/mp4`, `video/webm`, `video/quicktime`, `audio/mpeg`, `audio/mp4`, `audio/ogg`, `audio/wav`, `application/pdf`.
- `deleted` (`string`, optional): Whether to include assets that have been removed from the library. Removed assets keep serving at their original URL, so they remain listable. Example: exclude. One of: `exclude`, `include`, `only`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `folder_id` (`string`, optional): Return only the assets filed directly in this folder. Subfolders are not included, and a folder that does not exist matches nothing. Cannot be combined with `root_only`. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `kind` (`string`, optional): Return only assets in this category. This groups exact `content_type` values into images, video, audio, and documents. Example: image. One of: `image`, `video`, `audio`, `document`.
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `q` (`string`, optional): A case-insensitive substring match against the asset's name. Example: jane
- `root_only` (`boolean`, optional): Return only the assets at the top level of the library, filed in no folder. Cannot be combined with `folder_id`. Example: false
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_audience_contacts_list`

List Audience's Contacts · Read-only

List the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first.
Returns data, an array of items with contact, joined_at, audiences, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs audience_id from bird_audiences_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience whose contacts to list. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): Case-insensitive substring match against a contact's email address, first name, last name, or the digits in its international phone number. Example: acme.com
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"audience_id":"<audience_id>"}`

### `bird_audience_get`

Get Audience · Read-only

Return a single audience: its name, description, and type.
Returns an object with id, name, description, type, created_at, updated_at.
Use this when you have the ID. Use bird_audiences_list to find one.
Needs audience_id from bird_audiences_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience to fetch. Example: adn_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"audience_id":"<audience_id>"}`

### `bird_audience_membership_get`

Get Audience Membership · Read-only

Return the exact number of audience members at the source evaluation instant, including contacts without email and unsubscribed contacts.
Returns an object with membership.
Needs audience_id from bird_audiences_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience whose membership to read. Example: adn_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"audience_id":"<audience_id>"}`

### `bird_audience_membership_statistics_get`

Get Audience Membership Statistics · Read-only

Return the first successful observation for each requested UTC date, in chronological order.
Returns data, an array of items with bucket, total, observed_at, plus period.
Needs audience_id from bird_audiences_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience whose observations to read. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `from` (`string`, optional): Inclusive first UTC date. Defaults to 30 days before to, yielding 31 inclusive dates. Example: 2026-01-15
- `to` (`string`, optional): Inclusive last UTC date. Defaults to today in UTC; future dates are rejected. At most 365 inclusive dates. Example: 2026-01-15

Example input: `{"audience_id":"<audience_id>"}`

### `bird_audiences_list`

List Audiences · Read-only

Return a paginated list of audiences in the workspace, newest first.
Returns data, an array of items with id, name, description, type, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_audience_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): Case-insensitive substring match against the audience's name. Example: newsletter
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_available_number_get`

Get Available Phone Number · Read-only

Return a single phone number available for purchase, whether it is already in inventory or can be acquired for you.
Returns an object with number, country_code, number_type, capabilities, ownership_registration_required, ownership_address_scope, ownership_address_area_name, pricing.
Use this when you have the ID. Use bird_available_numbers_list to find one.
Needs number from bird_available_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number` (`string`, required): Phone number in E.164 format. The leading `+` is optional. Example: +14155550123

Example input: `{"number":"<number>"}`

### `bird_available_numbers_list`

List Available Phone Numbers · Read-only

Return phone numbers available for purchase in a country.
Returns data, an array of items with number, country_code, number_type, capabilities, ownership_registration_required, ownership_address_scope, ownership_address_area_name, pricing, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_available_number_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country_code` (`string`, required): ISO 3166-1 alpha-2 country code to search in. Example: US
- `capabilities` (`array`, optional): Filter by capability. Repeat the parameter to require several at once: `capabilities=sms&capabilities=voice` returns only numbers that support both. Example: ["example"]
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `number_type` (`string`, optional): Return only numbers of this physical type after applying the country and prefix filters. Example: +14155550123
- `prefix` (`string`, optional): Return only numbers that start with these digits, matched right after the country dial code: with `country_code=US`, `prefix=212` matches +1 212 area-code numbers and `prefix=833` matches 833 toll-free numbers. Digits only. Leave out the country dial code and any national dialing prefix such as a leading 0. Short codes never match a prefix search. Example: 1415
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"country_code":"<country_code>"}`

### `bird_compliance_attachments_list`

List Registration Attachments · Read-only

Return the registration attachments uploaded for the workspace, most recent first.
Returns data, an array of items with created_at, updated_at, id, filename, content_type, size_bytes, description, status, download_url, preview_url, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_compliance_identities_list`

List Identities · Read-only

Return the parties this workspace has stored, newest first.
Returns data, an array of items with id, name, answers, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_compliance_identity_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`, `name`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_compliance_identity_get`

Get Identity · Read-only

Return one of this workspace's parties, with the business details it holds.
Returns an object with id, name, answers, created_at, updated_at.
Use this when you have the ID. Use bird_compliance_identities_list to find one.
Needs identity_id from bird_compliance_identities_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `identity_id` (`string`, required): Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"identity_id":"<identity_id>"}`

### `bird_compliance_requirements_get`

Get What a Registration Needs · Read-only

Return everything a country requires before a registration can be approved, in the order to present it, along with what you have already supplied and where each item stands.
Returns an object with next, subject_kind, subject_id, program, country_code, satisfied, needs_input, review_pending, answers_editable, resubmission_allowed, reason, guidance and more.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country_code` (`string`, required): The destination country. For `identity` send `ZZ`, the international coordinate: your business registers once, not per country. Example: US
- `subject_kind` (`string`, required): What you are registering. Example: sms_sender. One of: `sms_sender`, `number`, `number_emergency`, `identity`.
- `identity_id` (`string`, optional): Prefill the business details from a party you have already described. Requirements that ask about the party come back carrying its answers, marked `prefilled`; requirements about this sender never prefill because you write the sender's intended use fresh each time. Anything you have already filed for this registration wins over the party's answer. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
- `program` (`string`, optional): The programme to read. Optional alongside `subject_id`, because a registration is under exactly one programme and that is the one used; supply it there only to confirm the programme you expect, since one that is not the registration's own returns a 422, as does supplying one at all for a country that runs no registration programme. Required when `subject_id` is omitted, because there is then no registration to resolve it from and a country can run more than one. Example: example
- `subject_id` (`string`, optional): The registration to answer for. Omit it to read the form on its own, before you hold anything to register: the requirements come back unanswered, which is what to do when you are deciding whether to take a number or a sender on in the first place. Omitting it makes `program` required, since the coordinate is otherwise resolved from the subject. When you do supply it, it is an `scr_` id when `subject_kind` is `sms_sender`, an `nda_` id when it is `number`, an `nes_` id when it is `number_emergency`, and a `cid_` party id when it is `identity`. Example: scr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"country_code":"<country_code>","subject_kind":"sms_sender"}`

### `bird_compliance_submission_get`

Get Submission · Read-only

Return every answer on a submission and where each one stands.
Returns an object with next, id, subject_kind, subject_id, program, country_code, identity_id, satisfied, items, created_at, updated_at, closed_at and more.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `submission_id` (`string`, required): Submission ID. Example: csb_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"submission_id":"<submission_id>"}`

### `bird_contact_get`

Get Contact · Read-only

Return a single contact, including its custom `data` values and the channels it can be reached on.
Returns an object with id, email, phone_number, first_name, last_name, external_id, data, audiences, created_at, updated_at.
Use this when you have the ID. Use bird_contacts_list to find one.
Needs contact_id from bird_contacts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, required): ID of the contact to fetch. Example: con_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"contact_id":"<contact_id>"}`

### `bird_contact_preferences_list`

List Contact's Preferences · Read-only

Return the preferences on record for the contact's current handles: rows keyed to their email address on the email channel, and to their phone number on SMS and WhatsApp.
Returns data, an array of items with id, channel, handle, sender_scope, topic_id, status, coverage, effective_at, origin, source, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs contact_id from bird_contacts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, required): ID of the contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"contact_id":"<contact_id>"}`

### `bird_contact_properties_list`

List Contact Properties · Read-only

Return a paginated list of the workspace's contact properties, newest first.
Returns data, an array of items with id, key, type, fallback_value, archived, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_contact_property_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_contact_property_get`

Get Contact Property · Read-only

Return a single contact property: its immutable key and type, the fallback value, and whether it is archived.
Returns an object with id, key, type, fallback_value, archived, created_at, updated_at.
Use this when you have the ID. Use bird_contact_properties_list to find one.
Needs property_id from bird_contact_properties_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `property_id` (`string`, required): ID of the contact property to fetch. Example: prp_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"property_id":"<property_id>"}`

### `bird_contacts_list`

List Contacts · Read-only

List contacts in the workspace, optionally filtered and sorted.
Returns data, an array of contacts with id, email, phone number, name fields and custom properties, plus next_cursor for the next page.
Use this to browse or find contacts. Use bird_contact_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page. Example: user@example.com
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `external_id` (`string`, optional): Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page. Example: user_12345
- `identifier` (`string`, optional): Filter to contacts that have a specific identifier on file. Example: email. One of: `email`, `phone_number`.
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `phone_number` (`array`, optional): Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set `limit` to at least the number of values you pass. The default `limit` is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so `phone_number=a&phone_number=b&email=c` asks for a contact whose phone number is `a` or `b` and whose email is `c`. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page. Example: ["+31612345678", "+31698765432"]
- `q` (`string`, optional): Case-insensitive substring match against the contact's email address, first name, last name, or phone number. Phone matching is over the digits of the international form, so a full pasted number, a formatted number, or trailing digits all match; a national form with a leading trunk zero does not. Example: acme.com
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_broadcast_clicked_links_list`

List Email Broadcast's Clicked Links · Read-only

Return the destination URLs a broadcast's recipients clicked, grouped by URL and sorted by click count.
Returns data, an array of items with url, name, click_count, recipient_count, plus total.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): ID of the broadcast whose clicked links to read. Example: eb_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_counts_get`

Get Email Broadcast's Audience Counts · Read-only

Return a live estimate of how many contacts the broadcast can reach, narrowing from everyone in its audience down to the ones the send would go to. - `total` is every contact in the audience. - `addressable` is how many of those have an email address. - `sendable` is how many addressable contacts a...
Returns an object with broadcast_id, status, next, total, addressable, sendable.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_events_list`

List Email Events for a Broadcast · Read-only

Return the per-recipient delivery timeline for a broadcast, oldest first, as a cursor page.
Returns data, an array of items with id, type, occurred_at, recipient_id, bounce_type, bounce_class, bounce_code, bounce_description, rejection_reason, sending_ip, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): ID of the broadcast whose event timeline to read. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `type` (`string`, optional): Filter by event type, for example `email.bounced` or `email.opened`. A broadcast timeline is recipient-scoped, so `email.scheduled` and `email.canceled` never appear on it; a canceled broadcast reports that in its own `status`. Example: email.delivered

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_get`

Get Email Broadcast · Read-only

Return one broadcast, with its audience reference and counters.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Use this when you have the ID. Use bird_email_broadcasts_list to find one.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_preview`

Preview Email Broadcast for a Contact · Read-only

Render a broadcast's template for one contact using the saved broadcast plus any changes in this request, without saving or sending.
Returns the rendered subject, html and text, plus a fingerprint to pass to bird_email_broadcast_test_send.
Use this to check content before sending. Use bird_email_broadcast_validate to check the whole broadcast for errors.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `contact_id` (`string`, optional): The workspace contact whose values fill `bird.contact.` inputs. Required when the template or envelope reads contact data. Present values are used as they are, and a property's fallback applies only when the contact has no value for it. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `from` (`object`, optional): Replaces the sender for this request. Give it as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. Example: Jane Doe <jane@acme.com>
- `headers` (`object`, optional): Replaces the custom headers for this request rather than adding to them. Up to 25 of them, each value up to 998 characters. The header rules for updating a broadcast apply. Example: {"X-Campaign": "spring-launch"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `reply_to` (`array`, optional): Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
- `template` (`object`, optional): Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_recipients_list`

List Email Recipients of a Broadcast · Read-only

Return recipient-level delivery state for a broadcast, paginated.
Returns data, an array of items with id, parent_id, role, recipient, name, subject, copy_of_recipient_id, status, rejection_reason, bounce_type, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): ID of the broadcast whose recipients to read. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `to` (`string`, optional): Return only the recipient at this address. Exact match, normalised to lowercase before comparison, so it returns at most one row. Example: user@example.com

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_send_quota_get`

Get Email Send Allowance for a Broadcast · Read-only

Return how many recipients the organization's email send allowance covers.
Returns an object with recipients, allowed, limited_by, limit, remaining, resets_at, limit_reason, broadcasts, on_insufficient_funds, can_start.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): ID of the broadcast to check the email send allowance for. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `send_at` (`string`, optional): The proposed send time as an RFC 3339 date-time. If a daily or monthly window resets at or before this time, the check uses its full allowance. Otherwise, it uses the allowance remaining now. The check estimates your send quota at this time using current limits without subtracting broadcasts that are scheduled but have not sent yet, including those scheduled before this time. It does not reflect plan changes or temporary limit changes that take effect before this time. Must be at least 30 seconds and no more than 365 days in the future, the same range accepted by `scheduled_at`. Omit `send_at` to check a send now. A scheduled broadcast's `scheduled_at` is used only if you pass it as `send_at`. Does not change `broadcasts`. The broadcast count allowance is used when you submit the send or schedule request. Example: 2026-11-02T09:00:00Z

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_validate`

Validate Email Broadcast · Read-only

Check the saved broadcast or the changes supplied in this request against the template's published content.
Returns an object with ready_for_admission, resolution, problems, unused_parameters, base_parameters, override_parameters.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `from` (`object`, optional): Replaces the sender for this request. Give it as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. Example: Jane Doe <jane@acme.com>
- `headers` (`object`, optional): Replaces the custom headers for this request rather than adding to them. Up to 25 of them, each value up to 998 characters. The header rules for updating a broadcast apply. Example: {"X-Campaign": "spring-launch"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `reply_to` (`array`, optional): Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
- `template` (`object`, optional): Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcasts_list`

List Email Broadcasts · Read-only

Return a paginated list of broadcasts in the workspace, newest first.
Returns data, an array of items with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_broadcast_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, optional): Filter by audience. Only broadcasts that use this audience are returned. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): Case-insensitive literal substring match against the broadcast's tags or the referenced template's name. With `email_management` read access, also matches the subject in the effective language of the template version resolved when this broadcast's execution starts. Draft and scheduled broadcasts have no execution subject to search. Percent signs, underscores, and backslashes are literal characters. Example: jane
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Filter by lifecycle status. Repeat the parameter to match more than one status, for example `?status=accepted&status=sending`.
- `tag` (`string`, optional): Filter by tag. Pass `name` to match any broadcast that has that tag name, or pass `name:value` to match a specific tag pair, for example `campaign:spring_launch`.

Example input: `{}`

### `bird_email_competitive_brand_campaign_get`

Get Email One Campaign a Watched Brand Sent · Read-only

Return one campaign an email panel observed a watched brand sending.
Returns an object with id, subject, sent_at, image_url, reach, read_rate, has_creative, discount_percent, inbox_rate, spam_rate.
Use this when you have the ID. Use bird_email_competitive_brand_campaigns_list to find one.
Needs campaign_id from bird_email_competitive_brand_campaigns_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `campaign_id` (`string`, required): The campaign to return, taken from the brand's campaign list. Example: 3914827265
- `watchlist_brand_id` (`string`, required): The watched brand that sent the campaign. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"campaign_id":"<campaign_id>","watchlist_brand_id":"<watchlist_brand_id>"}`

### `bird_email_competitive_brand_campaigns_list`

Get Email Campaigns a Watched Brand Sent · Read-only

Return a page of campaigns an email panel observed a watched brand sending over the period, in the requested order.
Returns data, an array of items with id, subject, sent_at, image_url, reach, read_rate, has_creative, discount_percent, inbox_rate, spam_rate, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_competitive_brand_campaign_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `watchlist_brand_id` (`string`, required): The watchlist entry whose campaigns to return. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `range` (`integer`, optional): How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30. Example: 30. One of: `7`, `30`, `90`.
- `sort` (`string`, optional): Field to sort campaigns by. Example: sent_at. One of: `sent_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"watchlist_brand_id":"<watchlist_brand_id>"}`

### `bird_email_competitive_brand_get`

Get Email Watched Brand's Figures · Read-only

Return one watched brand's figures for the period, together with how each mailbox provider treated its mail and how that compares with your own.
Returns an object with period, brand, providers.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `watchlist_brand_id` (`string`, required): The watchlist entry to act on. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
- `range` (`integer`, optional): How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30. Example: 30. One of: `7`, `30`, `90`.

Example input: `{"watchlist_brand_id":"<watchlist_brand_id>"}`

### `bird_email_competitive_brand_send_time_get`

Get Email When a Watched Brand Sends · Read-only

Return how a watched brand's sending is spread across the week: one figure per weekday and hour of the day, over the last 90 days, with the hour of the day it sends most of its mail in.
Returns an object with period, timezone, panel_status, cells, peak_send_window.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `watchlist_brand_id` (`string`, required): The watchlist entry whose sending pattern to return. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
- `timezone` (`string`, optional): IANA timezone identifier to report send times in; defaults to UTC. The grid is folded into this zone before it is summed, so a send lands on the weekday and hour it happened at locally rather than the one it happened at in UTC. A zone this API does not know returns 422 rather than falling back to UTC, so an axis is never labelled with a zone the figures were not folded into. Example: America/New_York

Example input: `{"watchlist_brand_id":"<watchlist_brand_id>"}`

### `bird_email_competitive_brands_search`

Search Email Brands to Add to the Watchlist · Read-only

Search for brands by name and returns the ones that can be watched, each with the domain its figures would describe and the identifier to add it with.
Returns data, an array of items with brand_id, name, sending_domains.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): A brand name, or a sending domain to look up the brand behind it. Example: everlane

Example input: `{"q":"<q>"}`

### `bird_email_competitive_notable_campaigns_list`

Get Email Notable Campaigns Across Watched Brands · Read-only

Return the campaigns worth a second look across every brand the workspace watches, surfaced for what they did rather than for when they were sent.
Returns data, an array of items with watchlist_brand_id, brand_name, signal, claim, evidence, mailbox_provider, campaign, plus period, panel_status, truncated.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `range` (`integer`, optional): How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30. Example: 30. One of: `7`, `30`, `90`.

Example input: `{}`

### `bird_email_competitive_volume_series_get`

Get Email Send Volume Over Time for Watched Brands · Read-only

Return daily send volume for the watched brands you name, plus a line for your own sending, over one shared axis.
Returns data, an array of items with watchlist_brand_id, is_workspace, name, sending_domains, panel_status, source, points, plus period.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `brand_ids` (`array`, optional): Which watched brands to plot, in the order you want the lines. Omit to get only your own line. An id your workspace does not watch is rejected rather than skipped, so a chart cannot quietly lose a line. Example: ["cwb_01krdgeqcxet5s7t44vh8rt9mg"]
- `range` (`integer`, optional): How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30. Example: 30. One of: `7`, `30`, `90`.

Example input: `{}`

### `bird_email_competitive_watchlist_get`

Get Email Competitor Watchlist with Its Latest Figures · Read-only

Return every competitor brand on the workspace's watchlist, plus a row for your own sending, each with estimated send volume and how it changed against the previous period, how often the brand sends, inbox placement, estimated read rate, audience overlap with you, and the most recent campaign seen.
Returns data, an array of items with watchlist_brand_id, is_workspace, name, industry, sending_domains, esp, list_size, panel_status, sends, sends_change_percent, plus period, summary.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `range` (`integer`, optional): How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30. Example: 30. One of: `7`, `30`, `90`.

Example input: `{}`

### `bird_email_domain_events_list`

List Domain Events · Read-only

Return the domain's activity history, newest first by default: - Registration. - A configuration change to settings, return path, or tracking. - A verification status transition for the domain or one of its individual DNS records.
Returns data, an array of items with id, type, summary, metadata, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs domain_id from bird_email_domains_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain_id` (`string`, required): ID of the domain whose events to list. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_domain_get`

Get Sending Domain · Read-only

Return the domain with its capability statuses and every DNS record's current verification state.
Returns an object with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, receiving, dns_records and more.
Use this when you have the ID. Use bird_email_domains_list to find one.
Needs domain_id from bird_email_domains_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain_id` (`string`, required): ID of the domain to fetch. Example: dom_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_domains_list`

List Sending Domains · Read-only

Return all sending domains for the current workspace, newest first by default.
Returns data, an array of items with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_domain_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `name` (`string`, optional): Substring match against the domain name (case-insensitive). Example: sk-test-sample
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`, `name`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_health_get`

Get Email Sending Health and Deliverability Limits · Read-only

Return your workspace's sending-health verdict for the requested window, together with reference deliverability limits and the boundaries used to classify risk.
Returns an object with period, status, signals.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, UTC. Defaults to 7 days before `to` when omitted. Example: 2026-05-19
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, UTC. Defaults to today (UTC) when omitted. Window may not exceed 365 days. Day boundaries are always UTC; unlike the statistics reads, this one takes no `timezone`. Example: 2026-05-25

Example input: `{}`

### `bird_email_inbound_address_get`

Get Email Inbound Address · Read-only

Return a single inbound address: the `address` you forward a mailbox to, and the `label` you gave it.
Returns an object with id, address, label, created_at, updated_at.
Use this when you have the ID. Use bird_email_inbound_addresses_list to find one.
Needs inbound_address_id from bird_email_inbound_addresses_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbound_address_id` (`string`, required): Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"inbound_address_id":"<inbound_address_id>"}`

### `bird_email_inbound_addresses_list`

List Email Inbound Addresses · Read-only

Return a paginated list of the workspace's inbound addresses.
Returns data, an array of items with id, address, label, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_inbound_address_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_inbound_message_attachments_list`

List Received Email's Attachments · Read-only

Return metadata for each attachment on a received email: - The `attachment_id`. - The declared filename. - The MIME type. - The size.
Returns data, an array of items with id, filename, content_type, size.
Needs inbound_message_id from bird_email_inbound_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbound_message_id` (`string`, required): Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"inbound_message_id":"<inbound_message_id>"}`

### `bird_email_inbound_message_body_get`

Get Received Email's Body · Read-only

Return the parsed, decoded body of a received email as JSON: the `html` and `text` parts, each `null` when the message had no such part.
Returns an object with html, text.
Needs inbound_message_id from bird_email_inbound_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbound_message_id` (`string`, required): Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"inbound_message_id":"<inbound_message_id>"}`

### `bird_email_inbound_message_get`

Get Received Email · Read-only

Return the parsed metadata for a received email: - Addresses. - Subject. - Threading headers. - The mailbox and conversation that received it, when a mailbox did. - Authentication results. - The attachment manifest.
Returns an object with id, from, to, cc, subject, message_id, in_reply_to, references, mailbox_id, thread_id, authentication, spf_pass and more.
Use this when you have the ID. Use bird_email_inbound_messages_list to find one.
Needs inbound_message_id from bird_email_inbound_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbound_message_id` (`string`, required): Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"inbound_message_id":"<inbound_message_id>"}`

### `bird_email_inbound_messages_list`

List Received Emails · Read-only

Return a paginated list of received emails for the workspace, newest first.
Returns data, an array of items with id, from, to, cc, subject, message_id, in_reply_to, references, mailbox_id, thread_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_inbound_message_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Filter to messages whose sender address matches this value exactly. Sender addresses are stored lowercase, so pass the address in lowercase to match reliably. Example: alice@example.com
- `inbound_address_id` (`string`, optional): Filter to messages received on a specific inbound address. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `mailbox_id` (`string`, optional): Filter to messages received by a specific mailbox. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg
- `received_after` (`string`, optional): Filter to messages received at or after this time. Example: 2026-01-15T09:30:00Z
- `received_before` (`string`, optional): Filter to messages received at or before this time. Example: 2026-01-15T09:30:00Z
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_inbound_route_get`

Get Email Inbound Route · Read-only

Return a single inbound route: - Its match rule. - Its action. - Its target mailbox. - Its priority. - Its enabled state.
Returns an object with id, domain, match_type, match_value, action, target_mailbox_id, priority, enabled, created_at, updated_at.
Use this when you have the ID. Use bird_email_inbound_routes_list to find one.
Needs route_id from bird_email_inbound_routes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `route_id` (`string`, required): Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"route_id":"<route_id>"}`

### `bird_email_inbound_routes_list`

List Email Inbound Routes · Read-only

Return a paginated list of the workspace's inbound routes in evaluation order, lowest priority number first.
Returns data, an array of items with id, domain, match_type, match_value, action, target_mailbox_id, priority, enabled, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_inbound_route_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, optional): Filter to routes on this domain. Example: mail.acme.com
- `enabled` (`boolean`, optional): Set to `true` for active routes or `false` for routes skipped during evaluation. Example: false
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_inbox_insights_authentication_get`

Get Email Authentication Standing for a Sending Domain · Read-only

Return whether the domain's mail authenticates and who sends as the domain: SPF and DKIM pass rates, the DMARC standing with its published policy and a conservative ready-for-reject judgement, and a per-source table showing every system observed sending under the domain's name, forwarders and unide...
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, window, compared_to, spf, dkim, dmarc, sources.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `compare` (`string`, optional): Include the prior equal-length period, populating `compared_to`. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 30 days before `to`. It may be at most 30 days before `to`, which is also the default, so a request naming neither date is already at the limit. Asking for more answers `422`: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side. Example: 2026-07-19
- `to` (`string`, optional): Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_blocklists_get`

Check Email Whether a Sending Domain's Infrastructure Is Blocklisted · Read-only

Check the sending IPs behind a sending domain against the blocklists receivers consult, and returns what is listed now plus the listings seen recently against each target.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, active_count, targets.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to check: one of the workspace's verified sending domains, exactly as it appears there. Inspect the returned targets and their statuses for lookup coverage. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_complaints_get`

Get Email Google-reported Spam Rate for a Sending Domain · Read-only

Return how often the domain's mail is reported as spam by Gmail recipients, as Google Postmaster measures it: the rate for the period and a time series for charting.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, window, compared_to, rate, series.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `compare` (`string`, optional): Include the prior equal-length period, populating `compared_to` and the rate's delta. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 30 days before `to`. It may be at most 30 days before `to`, which is also the default, so a request naming neither date is already at the limit. Asking for more answers `422`: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side. Example: 2026-07-19
- `group_by` (`string`, optional): Bucket size for the series. Defaults to day. Example: day. One of: `day`, `week`, `month`.
- `to` (`string`, optional): Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_domains_get`

List Sending Domains and Their Inbox Insights Status · Read-only

Return a page of sending domains this workspace can report on, in alphabetical order by default, and whether Inbox Insights is switched on for each.
Returns data, an array of items with domain, monitored, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: asc. One of: `asc`, `desc`.
- `search` (`string`, optional): Substring match against the sending domain (case-insensitive). Example: jane
- `sending_domain` (`string`, optional): Exact sending domain to return. Matching is case-insensitive. Example: mail.example.com
- `sort` (`string`, optional): Field to sort by. Defaults to `domain`. Example: domain. One of: `domain`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_inbox_insights_industry_benchmark_get`

Get Email Industry Placement Benchmark for a Sending Domain · Read-only

Return how senders in a sending domain's industry place: the median inbox rate across the industry's measured senders, how many senders that median covers, and the industry the domain was classified into.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, industry, median_inbox_rate_percent, window_days, cohort_size, status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain whose industry to benchmark: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_placement_get`

Get Inbox Placement for a Sending Domain · Read-only

Return where a sending domain's measured mail landed over the period (inbox or spam): the domain-wide rates, a per-provider table, a time series, the Gmail tab split, and optionally per-IP detail for the domain's sending infrastructure.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, window, compared_to, summary, providers, series, gmail_tabs and more.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `compare` (`string`, optional): Include the prior equal-length period, populating `compared_to` and every delta field. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints, so figures from the two sources cover the same days. Defaults to 30 days before `to`. It may be at most 30 days before `to`, which is also the default, so a request naming neither date is already at the limit. Asking for more answers `422`: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side. Example: 2026-07-19
- `group_by` (`string`, optional): Bucket size for the series. Defaults to day. Example: day. One of: `day`, `week`, `month`.
- `include_ip_details` (`boolean`, optional): Include per-IP placement detail for the domain's sending infrastructure. Off by default; only the sending-infrastructure view needs it. Example: false
- `series_providers` (`array`, optional): Providers to break the series down by, named as the provider table names them. Each named provider adds one series line; without this, the series carries the domain-wide line only. The provider table is never filtered by this parameter. Example: ["gmail", "yahoo"]
- `to` (`string`, optional): Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_seed_test_configuration_get`

Get Email Choices Available for a New Seed Test · Read-only

Return what a new seed test can be configured with for a sending domain: the seed pools the account can use, the regions seeds can be placed in, and the engagement behaviours the seeds can simulate.
Returns an object with resource, domain, list_types, regions, engagement_profiles.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain a test would be registered for: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_seed_tests_list`

Get Email Seed Tests for a Sending Domain · Read-only

Return the seed tests run for a sending domain over the period, newest first, together with the newest test's full results and the organization's seed-test allowance for the current billing period.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, window, compared_to, tests, latest, quota.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `from` (`string`, optional): First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 90 days before `to`, which is the span the history view shows. It may be at most 90 days before `to`, which is also the default, so a request naming neither date is already at the limit. Asking for more answers `422`. To reach older tests, request an earlier period. Example: 2026-05-20
- `to` (`string`, optional): Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_spam_traps_get`

Get Email Spam-trap Hits for a Sending Domain · Read-only

Return the spam-trap hits recorded against a sending domain over the period: the total, a split by the kind of trap, a split by the trap network that observed them, and the individual hits with the sending IP and trap age behind each.
Returns an object with resource, domain, measurement, generated_at, freshness, cached_at, window, compared_to, total, delta, by_type, by_source and more.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sending_domain` (`string`, required): The sending domain to report on: one of the workspace's verified sending domains, exactly as it appears there. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `compare` (`string`, optional): Include the prior equal-length period, populating `compared_to` and `delta`. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints. Defaults to 30 days before `to`. It may be at most 30 days before `to`, which is also the default, so a request naming neither date is already at the limit. Asking for more answers `422`: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side. Example: 2026-07-19
- `to` (`string`, optional): Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17

Example input: `{"sending_domain":"<sending_domain>"}`

### `bird_email_message_content_get`

Get Email Stored Message Content · Read-only

Return the stored HTML and text bodies for a sent message.
Returns an object with html, text.
Needs message_id from bird_email_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message whose stored content to fetch. A broadcast records one message per recipient, and List email messages returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg
- `recipient_id` (`string`, optional): Recipient whose accepted template values to render. Required for a message with multiple recipient snapshots; omission returns 422. A single recipient is selected automatically. An unknown recipient or one belonging to another message returns 404. Get the ID from the message's recipients listing. Example: er_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>"}`

### `bird_email_message_events_list`

List Email Events for a Message · Read-only

Return the message's per-recipient event timeline, oldest first, as a cursor page.
Returns data, an array of items with id, type, occurred_at, recipient_id, bounce_type, bounce_class, bounce_code, bounce_description, rejection_reason, sending_ip, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs message_id from bird_email_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message whose timeline to read. A broadcast records one message per recipient, and List email messages returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `type` (`string`, optional): Filter by event type, for example `email.bounced` or `email.opened`.

Example input: `{"message_id":"<message_id>"}`

### `bird_email_message_get`

Get Email Message · Read-only

Return a single message with its aggregate delivery `status` and per-state recipient counts.
Returns an object with id, from, to, cc, bcc, subject, subject_recipient_id, category, reply_to, status, accepted_count, processed_count and more.
Use this when you have the ID. Use bird_email_messages_list to find one.
Needs message_id from bird_email_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message to fetch. A broadcast records one message per recipient, and List email messages returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>"}`

### `bird_email_message_recipients_list`

List Email Recipients of a Message · Read-only

Return the message's per-recipient delivery state as a cursor page: each entry is one `to`/`cc`/`bcc` recipient with its role, current `status`, rejection or bounce detail when delivery failed, and open/click counts.
Returns data, an array of items with id, parent_id, role, recipient, name, subject, copy_of_recipient_id, status, rejection_reason, bounce_type, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs message_id from bird_email_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message whose recipients to list. A broadcast records one message per recipient, and List email messages returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"message_id":"<message_id>"}`

### `bird_email_messages_list`

List Email Messages · Read-only

Return the workspace's sent and scheduled messages, newest first, as a cursor page.
Returns data, an array of items with id, from, to, cc, bcc, subject, subject_recipient_id, category, reply_to, status, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_message_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, optional): Filter messages by broadcast ID. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Filter by category. Example: marketing. One of: `marketing`, `transactional`.
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Filter by sender address. Exact match against the message `from` field. The address is normalized to lowercase before comparison. Example: noreply@acme.com
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reference` (`string`, optional): Keep only messages whose `reference` is exactly this value. The match is case-sensitive, and several messages can share a reference. Example: INV-1234
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter by aggregate delivery status. Example: scheduled. One of: `scheduled`, `accepted`, `processed`, `deferred`, `delivered`, `partial_failure`, `bounced`, `complained`, `rejected`, `canceled`.
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.
- `to` (`string`, optional): Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message. The address is normalized to lowercase before comparison. Example: delivered@messagebird.dev

Example input: `{}`

### `bird_email_smtp_config_get`

Get Email SMTP Config · Read-only

Return the SMTP send-option config stored for the given API key.
Returns an object with api_key_id, ip_pool_id, category, tags, track_opens, track_clicks, created_at, updated_at.
Use this when you have the ID. Use bird_email_smtp_configs_list to find one.
Needs api_key_id from bird_email_smtp_configs_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, required): ID of the API key the config applies to, the same key your SMTP client authenticates with. Example: key_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"api_key_id":"<api_key_id>"}`

### `bird_email_smtp_configs_list`

List Email SMTP Configs · Read-only

Return the SMTP send-option configs stored for API keys in this workspace, as a cursor page.
Returns data, an array of items with api_key_id, ip_pool_id, category, tags, track_opens, track_clicks, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_smtp_config_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Sort by `created_at`, the default and only supported field. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_stats_breakdown_get`

Get Email Statistics Breakdown · Read-only

Get email statistics for a period grouped by one dimension (dimension): sending ips, sending domains, mailbox providers, mailbox provider regions, recipient domains, templates. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_email_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/email/stats/. Example: sending-ips. One of: `sending-ips`, `sending-domains`, `mailbox-providers`, `mailbox-provider-regions`, `recipient-domains`, `templates`.
- `category` (`string`, optional): Not supported on breakdown endpoints. Supplying it returns `422`. To compare categories, use `GET /v1/email/stats/categories`. The summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). It defaults to 30 days before `to` when you leave it out. When `include_trend=true` and `trend_grain=hourly`, that default tightens to 29 days before `to` instead, so the defaulted window still fits inside the 720-hour trend cap. Example: 2026-05-01
- `include_trend` (`boolean`, optional): When true, each row also gets a `trend` array: a short per-bucket series showing that IP's delivery rates over the window. A trend point's open and click rates read `0` in a bucket that had deliveries and `null` in one that had none, because a sending IP has no engagement data. This only works when `limit` is 50 or fewer and the window is at most 90 days for `trend_grain=daily` or 720 hours for `trend_grain=hourly`. Ask for more and you get a `422`. When you leave `from` out and use `trend_grain=hourly`, the default window tightens to 29 days before `to` (720 hours total), so a request built entirely from defaults always fits inside the cap. Example: false
- `limit` (`integer`, optional): Maximum number of IP rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank IPs by, applied descending. Sorting by `bounces.block` puts the IPs whose reputation is most likely degraded at the top. A row whose rate is undefined because its denominator is zero sorts last. It defaults to `delivered`. A sending IP has no engagement, so engagement metrics aren't sortable here, and neither are `processed`, `rejected`, or `oob_bounces`. Example: delivered. One of: `delivered`, `bounced`, `complained`, `deferred`, `bounces.hard`, `bounces.soft`, `bounces.admin`, `bounces.block`, `bounces.undetermined`, `delivery_rate`, `bounce_rate`, `complaint_rate`, `bounces.hard_rate`, `bounces.soft_rate`, `bounces.admin_rate`, `bounces.block_rate`, `bounces.undetermined_rate`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25
- `trend_grain` (`string`, optional): Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: daily. One of: `daily`, `hourly`.

Example input: `{"dimension":"sending-ips"}`

### `bird_email_stats_by_bounce_code_get`

Get Email Bounces by SMTP Error Code · Read-only

Return bounce counts for the requested period, grouped by the SMTP error code the receiving mail server returned.
Returns data, an array of items with smtp_error_code, bounced, bounces, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Not supported on breakdown endpoints. Supplying it returns `422`. To compare categories, use `GET /v1/email/stats/categories`. The summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `limit` (`integer`, optional): Maximum number of bounce-code rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. It defaults to `bounced`. Only the bounce counts are sortable here, because this breakdown has no rate fields. Example: bounced. One of: `bounced`, `bounces.hard`, `bounces.soft`, `bounces.admin`, `bounces.block`, `bounces.undetermined`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{}`

### `bird_email_stats_by_broadcast_get`

Get Email Statistics by Broadcast · Read-only

Return aggregate delivery and engagement counts grouped by broadcast for the requested period, so each broadcast's deliverability and engagement can be compared side by side.
Returns data, an array of items with broadcast_id, delivery, engagement, latency, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Not supported on breakdown endpoints. Supplying it returns a `422`. To compare categories, use `GET /v1/email/stats/categories`. The summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (UTC when omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `limit` (`integer`, optional): Maximum number of broadcast rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. Any count or rate in the response may be used; rows whose rate is undefined (zero denominator) sort last. Defaults to `processed`. Example: processed. One of: `processed`, `delivered`, `bounced`, `complained`, `deferred`, `rejected`, `oob_bounces`, `bounces.hard`, `bounces.soft`, `bounces.admin`, `bounces.block`, `bounces.undetermined`, `opens`, `opens_non_prefetched`, `unique_opens`, `unique_opens_non_prefetched`, `clicks`, `unique_clicks`, `unsubscribes`, `delivery_rate`, `bounce_rate`, `complaint_rate`, `open_rate`, `click_rate`, `unsubscribe_rate`, `bounces.hard_rate`, `bounces.soft_rate`, `bounces.admin_rate`, `bounces.block_rate`, `bounces.undetermined_rate`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (UTC when omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{}`

### `bird_email_stats_by_category_get`

Get Email Statistics by Category · Read-only

Return delivery and engagement counts for the requested period, grouped by category, so you can compare deliverability and engagement between your transactional and marketing traffic.
Returns data, an array of items with category, delivery, engagement, latency, trend, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). It defaults to 30 days before `to` when you leave it out. When `include_trend=true` and `trend_grain=hourly`, that default tightens to 29 days before `to` instead, so the defaulted window still fits inside the 720-hour trend cap. Example: 2026-05-01
- `include_trend` (`boolean`, optional): When true, each row also gets a `trend` array: a short per-bucket series showing that category's delivery and engagement rates over the window. This only works when `limit` is 50 or fewer and the window is at most 90 days for `trend_grain=daily` or 720 hours for `trend_grain=hourly`. Ask for more and you get a `422`. When you leave `from` out and use `trend_grain=hourly`, the default window tightens to 29 days before `to` (720 hours total), so a request built entirely from defaults always fits inside the cap. Example: false
- `limit` (`integer`, optional): Maximum number of category rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. Any count or rate in the response can be used. A row whose rate is undefined because its denominator is zero sorts last. It defaults to `processed`. Example: processed. One of: `processed`, `delivered`, `bounced`, `complained`, `deferred`, `rejected`, `oob_bounces`, `bounces.hard`, `bounces.soft`, `bounces.admin`, `bounces.block`, `bounces.undetermined`, `opens`, `opens_non_prefetched`, `unique_opens`, `unique_opens_non_prefetched`, `clicks`, `unique_clicks`, `unsubscribes`, `delivery_rate`, `bounce_rate`, `complaint_rate`, `open_rate`, `click_rate`, `unsubscribe_rate`, `bounces.hard_rate`, `bounces.soft_rate`, `bounces.admin_rate`, `bounces.block_rate`, `bounces.undetermined_rate`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25
- `trend_grain` (`string`, optional): Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: daily. One of: `daily`, `hourly`.

Example input: `{}`

### `bird_email_stats_by_complaint_type_get`

Get Email Complaints by Type · Read-only

Return spam-complaint counts for the requested period, grouped by the feedback-loop complaint type the mailbox provider reported, for example `abuse`, `fraud`, or `virus`.
Returns data, an array of items with feedback_type, complained, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Not supported on breakdown endpoints. Supplying it returns `422`. To compare categories, use `GET /v1/email/stats/categories`. The summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `limit` (`integer`, optional): Maximum number of complaint-type rows to return, ranked by `complained` descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. It defaults to `complained`, the only sortable metric for this breakdown. Example: complained. One of: `complained`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{}`

### `bird_email_stats_by_tag_get`

Get Email Statistics by Tag · Read-only

Return delivery and engagement counts for the requested period, grouped by tag.
Returns data, an array of items with tag, delivery, engagement, latency, trend, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Not supported on breakdown endpoints. Supplying it returns `422`. To compare categories, use `GET /v1/email/stats/categories`. The summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). It defaults to 30 days before `to` when you leave it out. When `include_trend=true` and `trend_grain=hourly`, that default tightens to 29 days before `to` instead, so the defaulted window still fits inside the 720-hour trend cap. Example: 2026-05-01
- `include_trend` (`boolean`, optional): When true, each row also gets a `trend` array: a short per-bucket series showing that tag's delivery and engagement rates over the window. This only works when `limit` is 50 or fewer and the window is at most 90 days for `trend_grain=daily` or 720 hours for `trend_grain=hourly`. Ask for more and you get a `422`. When you leave `from` out and use `trend_grain=hourly`, the default window tightens to 29 days before `to` (720 hours total), so a request built entirely from defaults always fits inside the cap. Example: false
- `limit` (`integer`, optional): Maximum number of tag rows to return, ranked by the `sort` field descending. Example: 50
- `name` (`string`, optional): Restrict the breakdown to this tag name. Names match case-sensitively. Example: sk-test-sample
- `sort` (`string`, optional): Metric to rank rows by, applied descending. Any count or rate in the response can be used. A row whose rate is undefined because its denominator is zero sorts last. It defaults to `processed`. Example: processed. One of: `processed`, `delivered`, `bounced`, `complained`, `deferred`, `rejected`, `oob_bounces`, `bounces.hard`, `bounces.soft`, `bounces.admin`, `bounces.block`, `bounces.undetermined`, `opens`, `opens_non_prefetched`, `unique_opens`, `unique_opens_non_prefetched`, `clicks`, `unique_clicks`, `unsubscribes`, `delivery_rate`, `bounce_rate`, `complaint_rate`, `open_rate`, `click_rate`, `unsubscribe_rate`, `bounces.hard_rate`, `bounces.soft_rate`, `bounces.admin_rate`, `bounces.block_rate`, `bounces.undetermined_rate`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25
- `trend_grain` (`string`, optional): Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: daily. One of: `daily`, `hourly`.

Example input: `{}`

### `bird_email_stats_engagement_breakdown_get`

Get Email Engagement Statistics Breakdown · Read-only

Get email engagement statistics for a period grouped by one dimension (dimension): locations, clients. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_email_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/email/stats/. Example: locations. One of: `locations`, `clients`.
- `category` (`string`, optional): Not supported on breakdown endpoints; supplying it returns `422`. To compare categories use `GET /v1/email/stats/categories`; the summary, daily, and hourly statistics accept `category` as a filter. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Start date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `group_by` (`string`, optional): Location granularity for each row. `country` (default) groups by country; `region` groups by region within country; `city` groups by city within region. Each row reports the location hierarchy down to the chosen level. Example: country. One of: `country`, `region`, `city`.
- `limit` (`integer`, optional): Maximum number of location rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. It defaults to `unique_opens`. Only engagement counts are sortable. This breakdown has no rates. Example: unique_opens. One of: `opens`, `opens_non_prefetched`, `unique_opens`, `unique_opens_non_prefetched`, `clicks`, `unique_clicks`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in `YYYY-MM-DD`, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{"dimension":"locations"}`

### `bird_email_stats_query`

Query Email Delivery and Engagement Metrics · Read-only

Query email delivery, engagement and latency metrics with filters, one grouping dimension and a time grain, for reports such as weekly deliveries by recipient domain for a campaign.
Returns one summary, or a page of groups each with its full series of the selected metrics.
Use this for custom reports. Use bird_email_stats_summary_get for a quick period total and bird_email_stats_breakdown_get for ranked breakdowns.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Inclusive start, as a calendar date or RFC 3339 instant. Use the same form for from and to. Instants round down to a local quarter-hour; use Z when timezone is supplied. Example: 2026-09-23
- `metrics` (`array`, required): Distinct metrics to return. Unselected metrics are absent. delivered and unique engagement counts estimate distinct message recipients. opens, opens_non_prefetched, clicks, unsubscribes, and oob_bounces estimate deduplicated events. effective_delivered and all_bounces are derived counts. Counts need not add up across buckets or groups. unique_opens and unique_clicks count message recipients, not distinct people across messages. Use returned period metrics; do not reconstruct totals from buckets or average rates or percentiles. delivered counts message recipients with a delivery event without subtracting later bounces. effective_delivered is max(delivered - oob_bounces, 0). open_rate uses unique_opens_non_prefetched divided by effective_delivered; click_rate uses unique_clicks divided by effective_delivered. Example: ["delivered", "bounce_rate"]
- `to` (`string`, required): Inclusive end. Dates include the whole local day; instants round down to a local quarter-hour and include that quarter-hour. Dates allow up to 365 local days; instants allow up to 720 hours, subject to available history. Preserve this original bound when following cursors. Example: 2026-09-24
- `ending_before` (`string`, optional): Grouped requests only. Opaque prev_cursor for backward navigation, or refresh_cursor to read groups before the anchor in the current sort order. Mutually exclusive with starting_after. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `filters` (`object`, optional): Filter recorded event context with include/exclude predicates. Include values combine with OR; dimensions combine with AND. Exclude-only predicates retain missing values. Tag filters require one case-sensitive name; a name without values requires presence. Each predicate accepts at most 20 distinct values across include and exclude. Every selected metric must support every filter dimension, using the same compatibility rules as group_by. Resolve template and IP-pool names to IDs before filtering. Broadcast filters use IDs. Current names do not establish historical attribution. Example: {"sending_domain": {"include": ["example"], "exclude": ["example"]}, "category": {"include": ["marketing"], "exclude": ["marketing"]}}
- `grain` (`string`, optional): Time buckets in the requested timezone. Weeks start on Monday; months start on the first day. Half days start at midnight and noon. Edge buckets count events inside the normalized period. Example: week. One of: `quarter_hour`, `hour`, `half_day`, `day`, `week`, `month`.
- `group_by` (`string`, optional): Group by one recorded event dimension. Omit for a single ungrouped summary with optional series. Grouping by `tag` requires `filters.tag.name`. Missing values form a null group when the metric supports that dimension. A null value means the event lacks that attribution; it does not explain how the message was created or establish membership in another dimension such as a campaign. Every selected metric must support the grouping dimension and every filter dimension. Unsupported combinations return validation error `E04074`, even when the workspace has no events. - `sending_domain`, `category`, `template_id`, `tag`: all metrics. - `recipient_domain`, `ip_pool_id`, `broadcast_id`: all metrics except `sends_accepted`. - `mailbox_provider`, `mailbox_provider_region`: all metrics except `sends_accepted`, `accepted`, and `rejected`. Example: recipient_domain. One of: `sending_domain`, `category`, `template_id`, `tag`, `recipient_domain`, `mailbox_provider`, `mailbox_provider_region`, `sending_ip`, `ip_pool_id`, `broadcast_id`, `country`, `region`, `city`, `agent_family`, `os_family`, `device_family`, `smtp_error_code`, `feedback_type`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `limit` (`integer`, optional): Grouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series. Example: 25
- `order` (`string`, optional): Grouped requests only. Defaults to desc. Example: asc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Grouped requests only. Rank groups by this selected metric; defaults to the first metrics entry. Undefined values sort last in either direction. Ties use the dimension value ascending, with null last. Example: sends_accepted. One of: `sends_accepted`, `accepted`, `processed`, `delivered`, `bounced`, `hard_bounced`, `soft_bounced`, `admin_bounced`, `block_bounced`, `undetermined_bounced`, `complained`, `deferred`, `rejected`, `oob_bounces`, `opens`, `opens_non_prefetched`, `clicks`, `unsubscribes`, `unique_opens`, `unique_opens_non_prefetched`, `unique_clicks`, `confirmed_unique_opens`, `confirmed_unique_opens_non_prefetched`, `effective_delivered`, `all_bounces`, `delivery_rate`, `bounce_rate`, `complaint_rate`, `deferral_rate`, `open_rate`, `click_rate`, `unsubscribe_rate`, `oob_rate`, `processing_p50_ms`, `processing_p95_ms`, `processing_p99_ms`, `total_p50_ms`, `total_p95_ms`, `total_p99_ms`.
- `starting_after` (`string`, optional): Grouped requests only. Opaque next_cursor from the previous response. Mutually exclusive with ending_before. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `timezone` (`string`, optional): IANA timezone for dates and bucket boundaries. Defaults to UTC. Example: UTC

Example input: `{"from":"<from>","metrics":["delivered","bounce_rate"],"to":"<to>"}`

### `bird_email_stats_summary_get`

Get Aggregate Email Statistics · Read-only

Return a single-row aggregate across the requested period covering delivery, bounce, complaint, open, and click counts plus the derived rates, along with processing, delivery, and total latency percentiles (p50/p95/p99).
Returns an object with period, sends_accepted, delivery, engagement, latency, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Restrict the statistics to a category or a comma-separated union of categories: `transactional` or `marketing`. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window: a calendar day (`YYYY-MM-DD`) or an RFC 3339 instant (rounded down to the hour). Interpreted in `timezone` (a calendar day names a local day; an instant is rounded down to the local hour), or in UTC when `timezone` is omitted. A numeric UTC offset (for example `+05:45`) is rejected when `timezone` is set; use a calendar day or a `Z` (UTC) instant. Must use the same form as `to`. Defaults to 30 days before `to` for day windows, or 168 hours (7 days) before `to` for hour windows, when omitted. Example: 2026-05-01
- `recipient_domain` (`string`, optional): Restrict the statistics to a recipient mailbox domain or a comma-separated union of domains (the part of the recipient address after the `@`, for example `gmail.com`). Mutually exclusive with the other dimension filters; only one may be set per request.
- `sending_domain` (`string`, optional): Restrict the statistics to a sending domain or a comma-separated union of sending domains (the part of the From address after @). Mutually exclusive with the other dimension filters; only one may be set per request. Example: mail.acme.com
- `sending_ip` (`string`, optional): Restrict the statistics to a sending IP or a comma-separated union of IPs. Mutually exclusive with the other dimension filters; only one may be set per request. A sending IP is assigned only after a message reaches delivery, so this filter reports delivery-side metrics only. Accepted, processed, rejected, complaint, and engagement counts are `0`, and processing latency is `null`. Complaint, open, and click rates are `0` when deliveries exist and `null` otherwise. Example: 192.0.2.55
- `tag` (`string`, optional): Restrict the statistics to a tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). To combine values of one tag name, separate complete pairs with commas, such as `campaign:spring,campaign:summer`. Different tag names cannot be combined. Mutually exclusive with the other dimension filters; only one may be set per request. Example: campaign:spring_launch
- `template` (`string`, optional): Restricts the statistics to a template or a comma-separated union of templates, identified by ID (`emt_…`) or name. This parameter is mutually exclusive with other dimension filters. Example: welcome-email
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (`YYYY-MM-DD`) or an RFC 3339 instant (rounded down to the hour). Interpreted in `timezone` (a calendar day names a local day; an instant is rounded down to the local hour), or in UTC when `timezone` is omitted. A numeric UTC offset is rejected when `timezone` is set; use a calendar day or a `Z` (UTC) instant. Must use the same form as `from`. Defaults to today for day windows, or the current hour for hour windows, in that timezone, when omitted. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_email_stats_timeseries_get`

Get Email Statistics Time Series · Read-only

Get email statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, sends_accepted, delivery, engagement, latency, plus period.
Use this for trends over time. Use bird_email_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `category` (`string`, optional): Restrict the statistics to a category or a comma-separated union of categories: `transactional` or `marketing`. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
- `from` (`string`, optional): Start date (inclusive), `YYYY-MM-DD`. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `recipient_domain` (`string`, optional): Restrict the statistics to a recipient mailbox domain or a comma-separated union of domains (the part of the recipient address after the `@`, for example `gmail.com`). Mutually exclusive with the other dimension filters; only one may be set per request.
- `sending_domain` (`string`, optional): Restrict the statistics to a sending domain or a comma-separated union of sending domains (the part of the From address after @). Mutually exclusive with the other dimension filters; only one may be set per request. Example: mail.acme.com
- `sending_ip` (`string`, optional): Restrict the statistics to a sending IP or a comma-separated union of IPs. Mutually exclusive with the other dimension filters; only one may be set per request. A sending IP is assigned only after a message reaches delivery, so this filter reports delivery-side metrics only. Accepted, processed, rejected, complaint, and engagement counts are `0`, and processing latency is `null`. Complaint, open, and click rates are `0` when deliveries exist and `null` otherwise. Example: 192.0.2.55
- `tag` (`string`, optional): Restrict the statistics to a tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). To combine values of one tag name, separate complete pairs with commas, such as `campaign:spring,campaign:summer`. Different tag names cannot be combined. Mutually exclusive with the other dimension filters; only one may be set per request. Example: campaign:spring_launch
- `template` (`string`, optional): Restricts the statistics to a template or a comma-separated union of templates, identified by ID (`emt_…`) or name. This parameter is mutually exclusive with other dimension filters. Example: welcome-email
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), `YYYY-MM-DD`. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_email_suppression_get`

Get Email Suppression · Read-only

Return one suppression record: - The address. - Why it is suppressed (`reason`). - How the record came to exist (`origin`). - Which message categories it blocks (`applies_to`).
Returns an object with id, email, scope, reason, origin, applies_to, source_email_id, source_recipient_id, created_at.
Use this when you have the ID. Use bird_email_suppressions_list to find one.
Needs suppression_id from bird_email_suppressions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression record, as returned when the suppression was created or listed. Example: sup_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_email_suppressions_list`

List Email Suppressions · Read-only

Return the workspace's suppressed email addresses as a paginated list, newest first.
Returns data, an array of items with id, email, scope, reason, origin, applies_to, source_email_id, source_recipient_id, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_suppression_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): Case-insensitive prefix filter on the address. Returns every suppression whose address starts with this value. A full address finds that address's records, while a fragment such as `alice` finds every address beginning with it. The same address can match several records, one per suppression reason. Example: user@example.com
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reason` (`string`, optional): Return only suppressions with this reason: - `hard_bounce`: Delivery permanently failed. - `complaint`: The recipient reported a message as spam. - `unsubscribe`: The recipient opted out. Deprecated: unsubscribes are now recorded as messaging preferences rather than suppressions, so no new records carry this reason. The filter returns legacy records until they are moved to messaging preferences. - `manual`: Added through the API or dashboard. Example: hard_bounce. One of: `hard_bounce`, `complaint`, `unsubscribe`, `manual`.
- `scope_type` (`string`, optional): Return only suppressions with this scope. Every suppression is workspace-wide, so `workspace` returns all of them without narrowing the results. The other five values, `category`, `audience`, `topic`, `contact` and `domain`, always come back with an empty page. Example: workspace. One of: `workspace`, `category`, `audience`, `topic`, `contact`, `domain`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_email_template_broadcasts_list`

List Email Broadcasts Blocking a Template Delete · Read-only

Return the broadcasts that block deleting this template, as a cursor page, newest first.
Returns data, an array of items with id, status, scheduled_at, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs template_ref from bird_email_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. A built-in `system` template's `bird_` slug also resolves here, but a system template can never be referenced by a broadcast, so this always returns an empty page for one. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_get`

Get Email Template · Read-only

Return a template's metadata, language states, sendable languages, draft revision, and draft and published version IDs.
Returns an object with editor_url, id, workspace_id, slug, name, description, scope, status, category, source, theme, draft_version_id and more.
Use this when you have the ID. Use bird_email_templates_list to find one.
Needs template_ref from bird_email_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Write operations (update, delete) accept a workspace template only, because a `system` template is immutable. Example: bird_welcome

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_language_get`

Get Email One Language of a Version · Read-only

Return one language's content from a version (its subject and bodies) plus the `revision` to send back when saving it.
Returns an object with language, revision, content_hash, updated_at, content, compatibility_severity, compatibility.
Use this when you have the ID. Use bird_email_template_version_languages_list to find one.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list; language from bird_email_template_version_languages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Example: pt-BR
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_parameters_get`

Get Published Email Template Parameters · Read-only

Get the parameters and variables used by the template's published content in one language.
Returns an object with template_id, observed_version_id, requested_language, effective_language, requirements_fingerprint, parameters, variables.
Needs template_ref from bird_email_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Workspace template ID, workspace template slug, or built-in template slug. Example: welcome_email
- `language` (`string`, optional): Language of the template's published content. Omission uses the template's default language. Example: pt-BR

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_preview`

Get Email Template Preview · Read-only

Render an email template with sample parameter values (and optionally a contact) without sending anything.
Returns the rendered subject, html and text bodies.
Use this to preview a draft or a specific published version. Use bird_email_template_get for the stored template source.
Needs template_ref from bird_email_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): The template to preview: a workspace template's id (`emt_…`) or slug, or a built-in `system` template's `bird_` slug. Example: welcome-email
- `contact` (`string`, optional): Render the template the way this contact would receive it. Every `{{ bird.contact.… }}` token takes its value from the contact's record, narrowed to the attributes the template reads and filled from each property's `fallback_value` where the contact holds no value: the same values a broadcast to this contact would send. Values are read as the contact stands right now, so a preview reflects an edit to their record as soon as you make it. A `bird.contact.…` value you also pass in `parameters` wins for that one attribute, so you can preview a contact with one field changed without editing them. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `content` (`object`, optional): Render this content rather than the template's stored draft. It is what an editor uses to show a change as it is made, since nothing has to be saved first. The content is treated exactly as a draft would be: personalization is filled in the same way, a plain-text body is derived from the HTML when you omit it, and content that could not be published is refused with the same error. `version` asks for a published version's own content, so the two cannot be combined. Example: {"subject": "Welcome to Acme, {{ bird.contact.first_name }}!", "preview_text": "{{ bird.contact.first_name }}, your order is on its way"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `language` (`string`, optional): Which of the template's languages to render. Omit it to render the default language. When the template does not have the language you ask for, its own `on_missing_language` setting decides whether a close match is rendered instead or the request is rejected. It is the same choice the send makes. Example: pt-BR
- `parameters` (`object`, optional): Sample values for the variables the template uses, for this one preview only. A variable takes its value under its own name. A `bird.` value nests to match the token, so `{"bird": {"contact": {"first_name": "Ada"}}}` fills `{{ bird.contact.first_name }}`. A preview is more forgiving than a send: a parameter you leave out renders as empty here rather than being rejected. `parameters` is capped at 16 KB once serialized. Example: {"bird": {"contact": {"first_name": "Ada"}}, "animal": "otter"}
- `version` (`string`, optional): Preview a specific published version by its id, instead of the current draft. Example: emv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_version_get`

Get Email Template Version · Read-only

Return a single version of an email template: - Its lifecycle metadata (`status`, `version_number`, `published_at`). - The content it froze in every language. - Its `variables`: the parameters you supply when sending and the values Bird fills in for each recipient, told apart by `system`.
Returns an object with id, template_id, version_number, status, revision, variables, languages, default_language, created_at, published_at, updated_by.
Use this when you have the ID. Use bird_email_template_versions_list to find one.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here, to its one permanently published version. Discarding a draft requires a workspace template, because a `system` template has no draft and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version to read or reset. Example: emv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_version_languages_list`

List Email Version's Languages · Read-only

Return every language the version holds, ordered by language tag, without the content itself, so listing a template with twenty-five languages stays small.
Returns data, an array of items with language, revision, content_hash, updated_at, has_html, has_text.
Use this to browse or filter. Use bird_email_template_language_get when you already have the ID.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. A built-in `system` template's `bird_` slug also resolves here, to its one permanently published version. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version whose languages to list. Example: emv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_versions_list`

List Email Template Versions · Read-only

Return the template's versions as a cursor page (the current draft plus all published versions), newest first.
Returns data, an array of items with id, template_id, version_number, status, revision, variables, default_language, available_languages, created_at, published_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_template_version_get when you already have the ID.
Needs template_ref from bird_email_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. A built-in `system` template's `bird_` slug also resolves here, to its one permanently published version. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_templates_list`

List Email Templates · Read-only

Return a paginated list of email templates, newest first.
Returns data, an array of items with id, workspace_id, slug, name, description, scope, status, category, source, theme, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_template_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Return only `transactional` or `marketing` templates; omit to return both categories. Example: transactional. One of: `transactional`, `marketing`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): A case-insensitive substring search across the template's slug, name, and description. Example: jane
- `scope` (`string`, optional): Filter by who owns the template. Use `system` for our built-in templates and `workspace` for the ones your workspace created. Leave it out to get both. Example: system. One of: `system`, `workspace`.
- `source` (`string`, optional): Return only templates authored in this format. Example: example
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `theme` (`string`, optional): Filter by the visual theme a built-in template is designed in. Only our built-in templates have a theme, so naming one returns built-ins alone. Example: arcane. One of: `arcane`, `barebone`, `matte`, `protocol`, `studio`.

Example input: `{}`

### `bird_email_thread_get`

Get Email Thread · Read-only

Return a single conversation. Fetch the messages in the conversation with List messages in a thread.
Returns an object with id, mailbox_id, channel, contact_id, subject, participants, participant_names, message_count, unread_count, last_message_at, last_direction, folder and more.
Use this when you have the ID. Use bird_email_threads_list to find one.
Needs thread_id from bird_email_threads_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"thread_id":"<thread_id>"}`

### `bird_email_thread_message_attachments_list`

List Email Thread Message's Attachments · Read-only

Return the attachments on a message in a conversation.
Returns data, an array of items with id, filename, content_type, size.
Needs thread_id from bird_email_threads_list; message_id from bird_email_thread_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_email_thread_message_body_get`

Get Email Thread Message's Original Body · Read-only

Return the original rendered HTML and plain-text body of a message in a conversation.
Returns an object with html, text.
Needs thread_id from bird_email_threads_list; message_id from bird_email_thread_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_email_thread_message_get`

Get Email Message in a Thread · Read-only

Return a single message in a conversation, including its extracted plain text.
Returns an object with scheduled_message_id, scheduled_at, mailbox_id, notice, id, direction, channel, thread_id, from, from_name, to, cc and more.
Use this when you have the ID. Use bird_email_thread_messages_list to find one.
Needs thread_id from bird_email_threads_list; message_id from bird_email_thread_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_email_thread_messages_list`

List Email Messages in a Thread · Read-only

Return the messages in a conversation, newest first, both received and sent.
Returns data, an array of items with scheduled_message_id, scheduled_at, mailbox_id, notice, id, direction, channel, thread_id, from, from_name, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_thread_message_get when you already have the ID.
Needs thread_id from bird_email_threads_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `direction` (`string`, optional): Filter to received (`inbound`) or sent (`outbound`) messages. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include` (`string`, optional): Set to `extracted_text` to inline each message's extracted plain text. Example: extracted_text. One of: `extracted_text`.
- `label` (`string`, optional): Filter to messages that have this label. `trash` lists trashed messages. Any other label, whether that is `archive`, `spam`, `blocked`, `unread` or one of your own, lists the messages that have it and are not in the trash. When omitted, every message that is not trashed is returned, whichever folder the conversation is in. A custom label name matches in any casing. Example: unread
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"thread_id":"<thread_id>"}`

### `bird_email_threads_list`

List Email Threads · Read-only

Return a paginated list of conversations across the workspace's mailboxes, most recently active first.
Returns data, an array of items with id, mailbox_id, channel, contact_id, subject, participants, participant_names, message_count, unread_count, last_message_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_email_thread_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): Filter to conversations whose most recent message is at or after this time. Use the response cursors for pagination. Example: 2026-01-15T09:30:00Z
- `before` (`string`, optional): Filter to conversations whose most recent message is at or before this time. Use the response cursors for pagination. Example: 2026-01-15T09:30:00Z
- `contact_id` (`string`, optional): Filter to conversations linked to a specific contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `folder` (`string`, optional): Filter to a folder. Defaults to inbox when neither folder nor custom labels are supplied. Example: inbox. One of: `inbox`, `archive`, `spam`, `blocked`, `sent`, `trash`.
- `labels` (`array`, optional): Match every listed custom label. Repeat labels to supply more than one. System label names are refused. Names match in any casing. Example: ["urgent"]
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `mailbox_id` (`string`, optional): Filter to conversations in a mailbox by ID or email address in this workspace. An unknown or ambiguous email address returns 404; a valid mailbox ID with no matching threads returns an empty page. Example: concierge@inbox.ai
- `participant` (`string`, optional): Conversations involving this address, matching the sender or any recipient. The match is case-insensitive and matches on any part of the address, so a fragment works as well as the whole address. Example: billing@acme.com
- `read_state` (`string`, optional): Filter to read or unread conversations. Omit for either state. Example: read. One of: `read`, `unread`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `subject` (`string`, optional): Conversations whose subject contains this text (case-insensitive). Example: quarterly invoice

Example input: `{}`

### `bird_esim_assignment_get`

Get eSIM Assignment · Read-only

Return the assigned person. An unassigned eSIM or a resource outside this workspace returns 404.
Returns an object with id, subscriber_id, esim_id, created_at, updated_at.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): The esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_compatible_offers_list`

List Offers an eSIM Can Take · Read-only

Return offers currently compatible with this eSIM’s network, package capacity, and existing packages.
Returns data, an array of items with id, name, revision, zone_id, speed, stackable, phone, pricing, product, status, plus as_of.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): Identifier of the eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `recurring_only` (`boolean`, optional): Keep only offers with recurring service configured. Enrollment still checks supplier support and the published recurring price. Example: false

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_credentials_get`

Get eSIM Install Credentials · Read-only

Return installation details for an eSIM, including an iOS installation link, an activation code, and manual setup components.
Returns an object with esim_id, ios_install_url, android_install_url, qr_code_url, activation_code, smdp_address, matching_id, confirmation_code, apn, data_roaming_required, instructions.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `accept_language` (`string`, optional): Preferred languages for the instructions field, as a standard weighted Accept-Language list. Bird serves the first one it stocks, then a variant sharing a requested base language, then English. Example: en

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_deliveries_list`

List eSIM's Credential Deliveries · Read-only

Return the credential deliveries sent for this eSIM, newest first (the most recent 50), each with its outcome.
Returns data, an array of items with id, channel, to, status, failure_code, created_at, settled_at, install_link.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): Identifier of the eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_get`

Get eSIM · Read-only

Return one eSIM: lifecycle status, device installation state, current data packages with balances, service-period timestamps, and the most recent network attachment.
Returns an object with subscriber_id, id, status, mode, iccid, phone_number, capabilities, order_id, display_name, installation, packages, zone_balances and more.
Use this when you have the ID. Use bird_esims_list to find one.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_offer_checkout_options_get`

Get eSIM Checkout Options · Read-only

Return published one-time terms and automatic renewal availability for a new eSIM, including tax-inclusive totals and current funding shortfalls.
Returns an object with offer_id, one_time, recurrence.
Needs offer_id from bird_esim_offers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `offer_id` (`string`, required): The offer. Example: eof_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"offer_id":"<offer_id>"}`

### `bird_esim_offer_get`

Get eSIM Offer · Read-only

Return one eSIM offer with its pricing and embedded coverage zone.
Returns an object with id, name, revision, zone_id, zone, speed, stackable, phone, pricing, product, status, created_at.
Use this when you have the ID. Use bird_esim_offers_list to find one.
Needs offer_id from bird_esim_offers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `offer_id` (`string`, required): Offer ID. Example: eof_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"offer_id":"<offer_id>"}`

### `bird_esim_offer_recurrence_get`

Get Recurring eSIM Offer Terms · Read-only

Return the published whole-package recurring price and calendar-month or fixed-day cadence.
Returns an object with delivery_mode, offer_id, model, interval_count, revision, price.
Needs offer_id from bird_esim_offers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `offer_id` (`string`, required): The offer. Example: eof_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"offer_id":"<offer_id>"}`

### `bird_esim_offer_requirements_get`

Get Country Identification Requirements for an eSIM Offer · Read-only

Return identification guidance as a JSON Schema for each country in the offer's coverage zone.
Returns an object with countries.
Needs offer_id from bird_esim_offers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `offer_id` (`string`, required): Offer ID. Example: eof_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"offer_id":"<offer_id>"}`

### `bird_esim_offers_list`

List eSIM Offers · Read-only

Return the eSIM offers your workspace can order as a cursor-paginated list.
Returns data, an array of items with id, name, revision, zone_id, speed, stackable, phone, pricing, product, status, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_offer_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Keep only offers whose coverage zone includes this country (ISO 3166-1 alpha-2). Example: US
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Possible values: created_at. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter by offer availability. Omitted, only active offers are returned. Example: draft. One of: `draft`, `active`, `retired`.
- `zone_id` (`string`, optional): Keep only offers selling this coverage zone. Example: ezn_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{}`

### `bird_esim_order_get`

Get Order · Read-only

Return one order. Poll until `status` is `completed` or `failed`; a completed order names the eSIM and package it produced.
Returns an object with created_at, updated_at, id, status, mode, offer_id, offer_revision, zone_id, esim_id, subscriber_id, recurring_subscription_id, package_id and more.
Use this when you have the ID. Use bird_esim_orders_list to find one.
Needs order_id from bird_esim_orders_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`string`, required): Order ID. Example: eor_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"order_id":"<order_id>"}`

### `bird_esim_orders_list`

List Orders · Read-only

Return the workspace's orders as a cursor-paginated list, newest first.
Returns data, an array of items with created_at, updated_at, id, status, mode, offer_id, offer_revision, zone_id, esim_id, subscriber_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_order_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `completed_after` (`string`, optional): Keep only orders completed at or after this timestamp. Combine it with `completed_before` to select a completion window, which is what the analytics spend and completion figures are counted by; `created_after` selects when an order was placed instead. Orders that never completed are excluded. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `completed_before` (`string`, optional): Keep only orders completed before this timestamp. Combine it with `completed_after` to select a completion window. Orders that never completed are excluded. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `esim_id` (`string`, optional): Keep only orders for this eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `mode` (`string`, optional): Keep only orders created in this mode. Without it, both live and test orders are returned. Example: live. One of: `live`, `test`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Keep only orders whose `status` matches; repeat the parameter to match any of several. Example: ["scheduled"]

Example input: `{}`

### `bird_esim_package_get`

Get Data Package · Read-only

Return one data package with its balance, validity, speed class, and status.
Returns an object with id, order_id, offer_id, zone_id, zone_name, countries, status, speed, balance, activated_at, expires_at, price and more.
Use this when you have the ID. Use bird_esim_packages_list to find one.
Needs esim_id from bird_esims_list; package_id from bird_esim_packages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `package_id` (`string`, required): Data package ID. Example: epk_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"esim_id":"<esim_id>","package_id":"<package_id>"}`

### `bird_esim_packages_list`

List eSIM's Data Packages · Read-only

Return the eSIM's data packages with per-zone balances, validity, and status, newest first and in full: an eSIM holds at most package_limit concurrent packages.
Returns data, an array of items with id, order_id, offer_id, zone_id, zone_name, countries, status, speed, balance, activated_at.
Use this to browse or filter. Use bird_esim_package_get when you already have the ID.
Needs esim_id from bird_esims_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_recurring_periods_list`

List Recurring eSIM Periods · Read-only

Return funded periods with their original charges, confirmed credits, and delivery orders.
Returns data, an array of items with delivery_mode, period_start, period_end, status, net_amount, tax_amount, total_amount, wallet_transaction_id, refund_transaction_id, order_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs subscription_id from bird_esim_recurring_subscriptions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subscription_id` (`string`, required): The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"subscription_id":"<subscription_id>"}`

### `bird_esim_recurring_subscription_get`

Get Recurring eSIM Subscription · Read-only

Return the current paid period separately from package delivery and cancellation state.
Returns an object with delivery_mode, id, esim_id, initial_order_id, subscriber_id, offer_id, status, billing_status, current_period_start, current_period_end, cancel_at_period_end, latest_order_id and more.
Use this when you have the ID. Use bird_esim_recurring_subscriptions_list to find one.
Needs subscription_id from bird_esim_recurring_subscriptions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subscription_id` (`string`, required): The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"subscription_id":"<subscription_id>"}`

### `bird_esim_recurring_subscriptions_list`

List Recurring eSIM Subscriptions · Read-only

Return recurring services for assigned eSIMs in this workspace.
Returns data, an array of items with delivery_mode, id, esim_id, initial_order_id, subscriber_id, offer_id, status, billing_status, current_period_start, current_period_end, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_recurring_subscription_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `esim_id` (`string`, optional): Filter by esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `subscriber_id` (`string`, optional): Return eSIMs assigned to this subscriber. Example: esub_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{}`

### `bird_esim_settings_get`

Get eSIM Settings · Read-only

Return your workspace’s eSIM settings, including defaults for fields you have not changed.
Returns an object with credential_delivery_enabled.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_esim_subscriber_get`

Get eSIM Subscriber · Read-only

Return the contact reference for a subscriber in this workspace.
Returns an object with id, contact_id, created_at, updated_at.
Use this when you have the ID. Use bird_esim_subscribers_list to find one.
Needs subscriber_id from bird_esim_subscribers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subscriber_id` (`string`, required): The subscriber id. Example: esub_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"subscriber_id":"<subscriber_id>"}`

### `bird_esim_subscribers_list`

List eSIM Subscribers · Read-only

Return person references in this workspace, newest first.
Returns data, an array of items with id, contact_id, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_subscriber_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, optional): The contact id. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_esim_zone_get`

Get eSIM Coverage Zone · Read-only

Return one coverage zone with its authoritative country list.
Returns an object with id, name, revision, type, countries, created_at.
Use this when you have the ID. Use bird_esim_zones_list to find one.
Needs zone_id from bird_esim_zones_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `zone_id` (`string`, required): Zone ID. Example: ezn_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"zone_id":"<zone_id>"}`

### `bird_esim_zones_list`

List eSIM Coverage Zones · Read-only

Return the coverage zones behind the offer catalog as a cursor-paginated list.
Returns data, an array of items with id, name, revision, type, countries, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_zone_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Keep only zones that include this country (ISO 3166-1 alpha-2). Example: US
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Possible values: created_at. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_esims_list`

List eSIMs · Read-only

Return your workspace's eSIMs as a cursor-paginated list, newest first.
Returns data, an array of items with subscriber_id, id, status, mode, iccid, phone_number, display_name, renewal, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_esim_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `display_name` (`string`, optional): Keep only eSIMs whose `display_name` contains this text, ignoring case. An eSIM you have not named has no `display_name`, so it never matches. Example: field team
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `iccid` (`string`, optional): Filter by ICCID (exact match). Example: example
- `iccid_prefix` (`string`, optional): Keep only eSIMs whose ICCID starts with these digits. Use it when you hold only the first part of an ICCID. Pass `iccid` instead when you hold the whole number. Example: 89445002
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `mode` (`string`, optional): Keep only eSIMs created in this mode. Without it, both live and test eSIMs are returned. Example: live. One of: `live`, `test`.
- `phone_number` (`string`, optional): Keep only eSIMs whose mobile network has reported this phone number, matched as a whole number rather than as a fragment. Give it in international form, with or without the leading `+`: `+31612345678` and `31612345678` select the same eSIMs. An eSIM matches on any number its mobile network has ever reported for the profile, so a number that has since moved on still finds the eSIM that held it. An eSIM whose number no network has reported yet never matches. Example: +31612345678
- `renewal` (`array`, optional): Keep only eSIMs whose recurring subscription that has not ended is in this status, or that have none (`none`); repeat the parameter to match any of several. Example: ["pending"]
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Keep only eSIMs whose current `status` matches; repeat the parameter to match any of several. Example: ["provisioning"]
- `subscriber_id` (`string`, optional): Return eSIMs assigned to this subscriber. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any eSIM carrying that tag name, or `name:value` to match a specific tag pair (e.g. `trip:summer`). A trailing colon (`name:`) matches the name alone, the same as `name`. A term with an empty name is rejected. Repeat the parameter to AND-combine several tag filters. Example: ["onboarding"]

Example input: `{}`

### `bird_mailbox_get`

Get Mailbox · Read-only

Return a single mailbox by ID or email address in this workspace.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Use this when you have the ID. Use bird_mailboxes_list to find one.
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_labels_list`

List Mailbox's Labels · Read-only

Return the labels available in a mailbox. First, the built-in system labels: - The placements `inbox`, `archive`, `spam`, `blocked`, and `sent`. - `trash`. - `unread`.
Returns data, an array of items with name, type.
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_messages_list`

List Mailbox's Messages · Read-only

Return the messages in a mailbox across all of its conversations, newest first.
Returns data, an array of items with scheduled_message_id, scheduled_at, mailbox_id, notice, id, direction, channel, thread_id, from, from_name, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `after` (`string`, optional): Filter to messages that occurred at or after this time. Page through results with `starting_after` or `ending_before` instead of this value. Example: 2026-01-15T09:30:00Z
- `before` (`string`, optional): Filter to messages that occurred at or before this time. Page through results with `starting_after` or `ending_before` instead of this value. Example: 2026-01-15T09:30:00Z
- `direction` (`string`, optional): Filter to received (`inbound`) or sent (`outbound`) messages. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include` (`string`, optional): Set to `extracted_text` to inline each message's extracted plain text. Example: extracted_text. One of: `extracted_text`.
- `label` (`string`, optional): Filter to messages that have this label. `trash` lists trashed messages. Any other label, whether that is `archive`, `spam`, `blocked`, `unread` or one of your own, lists the messages that have it and are not in the trash. When omitted, received messages in the inbox and all sent messages are returned. A custom label name matches in any casing. Example: unread
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter sent messages by combined delivery status: `accepted`, `sent`, `delivered`, or `failed`. Example: accepted. One of: `accepted`, `sent`, `delivered`, `failed`.

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_receive_rules_list`

List Email Receive Rules · Read-only

Return a paginated list of the mailbox's receive rules, oldest first.
Returns data, an array of items with id, mailbox_id, action, entry, entry_type, note, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `action` (`string`, optional): Return only `allow` or `block` rules; omit to return both actions. Example: allow. One of: `allow`, `block`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_scheduled_message_get`

Get Scheduled Mailbox Send · Read-only

Read the scheduled send and its dispatch, failure or cancellation state.
Returns an object with id, mailbox_id, thread_id, message_id, status, scheduled_at, cancel_on_reply, failure_reason, cancellation_reason, subject, snippet, recipients and more.
Use this when you have the ID. Use bird_mailbox_scheduled_messages_list to find one.
Needs mailbox_id from bird_mailboxes_list; scheduled_message_id from bird_mailbox_scheduled_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
- `scheduled_message_id` (`string`, required): Scheduled send identifier from scheduled_message_id in the acceptance response. Example: msm_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"mailbox_id":"<mailbox_id>","scheduled_message_id":"<scheduled_message_id>"}`

### `bird_mailbox_scheduled_messages_list`

List Scheduled Mailbox Sends · Read-only

List scheduled sends separately from conversation messages, including completed and canceled records.
Returns data, an array of items with id, mailbox_id, thread_id, message_id, status, scheduled_at, cancel_on_reply, failure_reason, cancellation_reason, subject, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_mailbox_scheduled_message_get when you already have the ID.
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Filter by scheduling state. Example: scheduled. One of: `scheduled`, `sending`, `sent`, `failed`, `canceled`.
- `thread_id` (`string`, optional): Filter by the reserved conversation identifier. Example: thr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_stats_get`

Get Mailbox Email Statistics · Read-only

Return the mailbox's sent and received email statistics over a time window: a period-wide summary plus a bucketed series.
Returns data, an array of items with bucket, sends_accepted, delivery, engagement, latency, received, plus period, summary.
Needs mailbox_id from bird_mailboxes_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `from` (`string`, optional): Inclusive start of the window: a calendar day (`YYYY-MM-DD`, `day` granularity only) or an RFC 3339 instant rounded down to the hour (`hour` granularity only). Interpreted in `timezone`, or in UTC when `timezone` is omitted. A numeric UTC offset is rejected when `timezone` is set; use a calendar day or a `Z` (UTC) instant. Must use the same form as `to`. Defaults to 30 days before `to` at `day` granularity and 7 days before `to` at `hour`, when omitted. Example: 2026-07-01
- `granularity` (`string`, optional): Granularity of the series: `day` (default) or `hour`. Echoed back as `period.grain`. Example: day. One of: `day`, `hour`.
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (`YYYY-MM-DD`, `day` granularity only) or an RFC 3339 instant rounded down to the hour (`hour` granularity only). Interpreted in `timezone`, or in UTC when `timezone` is omitted. A numeric UTC offset is rejected when `timezone` is set; use a calendar day or a `Z` (UTC) instant. Must use the same form as `from`. Defaults to today (day) or the current hour (hour) in that timezone when omitted. Window may not exceed 365 days at `day` or 30 days at `hour` granularity. Example: 2026-07-21

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailboxes_list`

List Mailboxes · Read-only

Return a paginated list of the workspace's mailboxes, newest first.
Returns data, an array of items with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_mailbox_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address` (`string`, optional): Filter to the mailbox with exactly this address. Example: concierge@inbox.ai
- `domain` (`string`, optional): Filter to mailboxes whose address is on this domain. Example: inbox.ai
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_deleted` (`boolean`, optional): Include mailboxes deleted within their 30-day restore window. Defaults to false, so only active and suspended mailboxes are returned. A deleted mailbox has `deleted_at` set. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): Case-insensitive substring match on the mailbox's `address`, `name`, or `display_name`. Example: concierge
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `state` (`string`, optional): Return only `active` or `suspended` mailboxes. Use `include_deleted` for restorable deleted mailboxes. Example: active. One of: `active`, `suspended`.

Example input: `{}`

### `bird_number_get`

Get Allocated Number · Read-only

Return a single phone number allocated to your workspace, whether it is a dedicated number you bought or a shared number managed for you.
Returns an object with name, reference, id, kind, number, country_code, number_type, capabilities, status, allocated_at, releases_at, released_at and more.
Use this when you have the ID. Use bird_numbers_list to find one.
Needs number_id from bird_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): Identifier of the number, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"number_id":"<number_id>"}`

### `bird_numbers_list`

List Your Allocated Numbers · Read-only

Return a paginated list of the phone numbers currently allocated to your workspace, newest first.
Returns data, an array of items with name, reference, id, kind, number, country_code, number_type, capabilities, status, allocated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_number_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `capabilities` (`array`, optional): Filter by capability. Repeat the parameter to require several at once: `capabilities=sms&capabilities=voice` returns only numbers that support both. Example: ["example"]
- `country_code` (`string`, optional): Filter by the country a number belongs to, as an ISO 3166-1 alpha-2 code. Example: US
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `number` (`string`, optional): Return only the number matching these digits. Give a full number with its country code, however your own records spell it: `+12025550188`, `12025550188`, `0012025550188`, and `+1 202 555 0188` all resolve to the same number. Spacing and punctuation are fine once a leading `+` or `00` marks the country code, or when `country_code` names the country; a grouped spelling without either is refused rather than guessed at, and a national spelling (bare digits without the country code) matches only when `country_code` names the country. A short code is matched on its bare digits instead, and since the same short code can be allocated in more than one country, pass `country_code` alongside it to name which one. This filter narrows the list like the others rather than replacing them, so a country or capability filter still applies. To match a range of numbers rather than one, use `prefix`. Example: +14155550123
- `number_type` (`string`, optional): Return only allocated numbers of this physical type after applying the country and prefix filters. Example: +14155550123
- `prefix` (`string`, optional): Return only numbers that start with these digits. With `country_code`, the digits are national ones, matched right after the country dial code: with `country_code=US`, `prefix=212` returns the +1 212 area-code numbers allocated to you. Leave out the dial code and any national dialing prefix such as a leading 0; short codes never match a country-anchored prefix search. Without `country_code`, the digits are matched from the start of each stored number, ignoring a leading `+`, so short codes are reachable and a full number in digits finds itself. Digits only: up to 10 of them with `country_code`, 15 without. Example: 1415
- `reference` (`string`, optional): Return numbers with this exact reference. Matching is case-sensitive. Example: example
- `search` (`string`, optional): Matches part of the number, name, or reference, ignoring case. Number matching also ignores phone formatting such as spaces, parentheses, and hyphens. Name and reference matching preserves punctuation. Characters such as percent and underscore match literally. Example: jane
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_numbers_order_get`

Get Number Order · Read-only

Return a single number order by id, including its current lifecycle state and, once completed, the number it produced.
Returns an object with id, number, country_code, number_type, status, number_id, failure_reason, completed_at, created_at, updated_at.
Use this when you have the ID. Use bird_numbers_orders_list to find one.
Needs order_id from bird_numbers_orders_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_id` (`string`, required): Identifier of the order. Example: nor_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"order_id":"<order_id>"}`

### `bird_numbers_orders_list`

List Your Number Orders · Read-only

Return your workspace's number orders, newest first.
Returns data, an array of items with id, number, country_code, number_type, status, number_id, failure_reason, completed_at, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_numbers_order_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Return only orders with status `charging`, `ordering`, `pending`, `completed`, or `failed`. Example: active

Example input: `{}`

### `bird_preference_get`

Get Preference · Read-only

Return one preference: the key it is about, the current statement on it, and the statement's provenance.
Returns an object with id, channel, handle, sender_scope, topic_id, status, coverage, effective_at, origin, source, consented_at, contact_id and more.
Use this when you have the ID. Use bird_preferences_list to find one.
Needs preference_id from bird_preferences_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `preference_id` (`string`, required): ID of the preference, as returned when it was recorded or listed. The ID stays stable while the key holds a record; deleting and re-recording the same key mints a new one. Example: prf_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"preference_id":"<preference_id>"}`

### `bird_preferences_list`

List Preferences · Read-only

Return the workspace's recorded preferences, most recently created first.
Returns data, an array of items with id, channel, handle, sender_scope, topic_id, status, coverage, effective_at, origin, source, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_preference_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `channel` (`string`, optional): Return only preferences on this channel. Example: sms
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `handle` (`string`, optional): Return only preferences for this exact handle: an email address or an E.164 phone number. Requires `channel`, since a handle only means something on its channel. Example: +15550001234
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_realtime_app_get`

Get Realtime App · Read-only

Return a single Realtime app with its configuration and connection details (`app_id`, `region`).
Returns an object with created_at, updated_at, client_events, connection_counting, connection_count_events, watchlist_events, authorized_connections, id, app_id, name, region, status.
Use this when you have the ID. Use bird_realtime_apps_list to find one.
Needs realtime_app_id from bird_realtime_apps_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"realtime_app_id":"<realtime_app_id>"}`

### `bird_realtime_app_keys_list`

List Realtime App's Keys · Read-only

Return the app's keys, oldest first. Non-revoked only by default; pass include_revoked=true to include revoked keys.
Returns data, an array of items with id, key, secret, revoked_at, created_at.
Needs realtime_app_id from bird_realtime_apps_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
- `include_revoked` (`boolean`, optional): When true, include revoked keys in the response. Example: false

Example input: `{"realtime_app_id":"<realtime_app_id>"}`

### `bird_realtime_apps_list`

List Realtime Apps · Read-only

Return the workspace's Realtime apps as a paginated list, filterable by a case-insensitive `name` substring.
Returns data, an array of items with created_at, updated_at, client_events, connection_counting, connection_count_events, watchlist_events, authorized_connections, id, app_id, name, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_realtime_app_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `name` (`string`, optional): Substring match against the app name (case-insensitive). Example: sk-test-sample
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`, `name`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_realtime_regions_list`

List Realtime Regions · Read-only

Return the regions a Realtime app can be created in.
Returns data, an array of items with id.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_sms_inbound_stats_breakdown_get`

Get Inbound SMS Statistics Breakdown · Read-only

Get inbound SMS statistics for a period grouped by one dimension (dimension): countries, operators, numbers. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_sms_inbound_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/sms/stats/inbound/. Example: countries. One of: `countries`, `operators`, `numbers`.
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `limit` (`integer`, optional): Maximum rows to return, ranked by volume. Defaults to 50; the maximum is 200, and asking for more returns 422 rather than silently returning fewer. Example: 50
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{"dimension":"countries"}`

### `bird_sms_inbound_stats_summary_get`

Get Aggregate Inbound SMS Statistics · Read-only

Return the total number of messages your numbers received over the period, using the time the carrier received each message.
Returns an object with period, received, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `compare` (`string`, optional): Set to `previous_period` to include the received-message count for the immediately preceding window of equal length. The response also includes the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window, either a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The form you use selects the grain the total is resolved at. Interpreted in `timezone`, or in UTC when `timezone` is omitted. Must use the same form as `to`. A numeric UTC offset (for example `+05:45`) is rejected when `timezone` is set; pass a calendar day or a `Z` instant instead. Defaults to 30 days before `to` for day windows, or 168 hours before `to` for hour windows. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, in the same form as `from`. Defaults to today, or the current hour for an hour window. A day window may not exceed 365 days and an hour window 720 hours. Example: 2026-05-25

Example input: `{}`

### `bird_sms_inbound_stats_timeseries_get`

Get Inbound SMS Statistics Time Series · Read-only

Get inbound SMS statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, received, plus period.
Use this for trends over time. Use bird_sms_inbound_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_sms_keyword_rule_get`

Get SMS Keyword Rule · Read-only

Return one keyword rule, either one of Bird's defaults or one you created, including every keyword that matches it and the reply it sends.
Returns an object with id, scope, operation, country, language, number, keywords, effective_keywords, reply, reply_suffix, reply_disabled_at, mandatory and more.
Use this when you have the ID. Use bird_sms_keyword_rules_list to find one.
Needs id from bird_sms_keyword_rules_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"id":"<id>"}`

### `bird_sms_keyword_rules_list`

List SMS Keyword Rules · Read-only

Return the default and workspace keyword rules that apply to inbound messages, most specific first.
Returns data, an array of items with id, scope, operation, country, language, number, keywords, effective_keywords, reply, reply_suffix.
Use this to browse or filter. Use bird_sms_keyword_rule_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Keep only rules that apply in this country, as an ISO 3166-1 alpha-2 code. Omit for every country the default catalog covers, plus your own rules. Example: NL
- `from_country` (`string`, optional): The country a sender is messaging from, as an ISO 3166-1 alpha-2 code. Use it with `number` to see what someone in that country gets, which can differ from what a local sender gets. Ignored without `number`. Example: CA
- `number` (`string`, optional): Keep only the rules that apply to this number of yours, in E.164 format or as a short code, ordered the way they are applied to an inbound message. Example: +18005551234
- `operation` (`string`, optional): Keep only rules for this operation. Omit for all of them. Example: stop
- `scope` (`string`, optional): Keep only default rules (`system`) or only the rules you created (`workspace`). Omit for both. Example: system. One of: `system`, `workspace`.

Example input: `{}`

### `bird_sms_message_events_list`

List Events for an SMS Message · Read-only

Return the lifecycle event timeline for a message, in chronological order.
Returns data, an array of items with id, type, occurred_at, carrier, mcc_mnc, error.
Needs message_id from bird_sms_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the SMS message (`sms_` prefix), as returned when the message was accepted. Example: sms_01krdgeqcxet5s7t44vh8rt9mg
- `type` (`string`, optional): Filter by event type, such as `sms.delivered` or `sms.failed`. Example: example

Example input: `{"message_id":"<message_id>"}`

### `bird_sms_message_get`

Get SMS Message · Read-only

Return a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed.
Returns an object with id, direction, status, to, from, text, binary, category, requested_language, resolved_language, template_id, template_version_id and more.
Use this when you have the ID. Use bird_sms_messages_list to find one.
Needs message_id from bird_sms_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message, as returned in the send response's `id` field. Example: sms_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>"}`

### `bird_sms_messages_list`

List SMS Messages · Read-only

Return the workspace's SMS messages as a cursor-paginated list, newest first.
Returns data, an array of items with id, direction, status, to, from, text, binary, category, requested_language, resolved_language, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_message_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Filter by category. Example: transactional. One of: `transactional`, `marketing`, `authentication`, `service`.
- `country` (`string`, optional): Filter by destination country, as an ISO 3166-1 alpha-2 code. An outbound message's country is the recipient's; a received message's is the country of the Bird number it arrived on. Example: US
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `direction` (`string`, optional): Filter by direction. Omit for both. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `error_code` (`array`, optional): Keep only messages whose failure reason (`last_error.code`) matches; repeat the parameter to match any of several. Accepts any SMS error code, including codes added later, such as `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, `workspace_suspended`, or `unknown`. With a `status` or `error_code` filter a page can hold fewer messages than `limit`, or none; keep paging until `next_cursor` is null. Example: ["example"]
- `from` (`string`, optional): Filter by sender (E.164, alphanumeric, or short code; exact match). Example: +15557654321
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reference` (`string`, optional): Keep only messages whose `reference` is exactly this value. The match is case-sensitive, and several messages can share a reference. Example: INV-1234
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships. With a `status` or `error_code` filter a page can hold fewer messages than `limit`, or none; keep paging until `next_cursor` is null. Example: ["example"]
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.
- `to` (`string`, optional): Filter by recipient phone number (E.164 exact match). Example: +14155550100

Example input: `{}`

### `bird_sms_messaging_profile_get`

Get SMS Messaging Profile · Read-only

Return one messaging profile, including its senders, reply numbers, and sending defaults.
Returns an object with id, name, senders, inbound, default_category, validity_period, cost_center, options, callback_events, created_at, updated_at.
Use this when you have the ID. Use bird_sms_messaging_profiles_list to find one.
Needs profile_id from bird_sms_messaging_profiles_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `profile_id` (`string`, required): ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"profile_id":"<profile_id>"}`

### `bird_sms_messaging_profiles_list`

List SMS Messaging Profiles · Read-only

Return your workspace's messaging profiles, newest first.
Returns data, an array of items with id, name, senders, inbound, default_category, validity_period, cost_center, options, callback_events, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_messaging_profile_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_sms_sender_get`

Get SMS Sender · Read-only

Return one of your workspace's SMS senders with its per-country registration status.
Returns an object with id, sender, source_kind, sender_type, country_code, number_id, status, next, destinations, created_at, updated_at.
Use this when you have the ID. Use bird_sms_senders_list to find one.
Needs sender_id from bird_sms_senders_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sender_id` (`string`, required): ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"sender_id":"<sender_id>"}`

### `bird_sms_sender_requirements_list`

List SMS What a Sender Needs to Send · Read-only

Return the countries a sender can reach, each country's requirements, and the current registration status.
Returns data, an array of items with sender_id, country_code, registration_mode, sender_id_behavior, program, status, next, destination_enabled, has_compliance_requirements, category, plus programs.
Needs sender_id from bird_sms_senders_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sender_id` (`string`, required): ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg
- `country_code` (`string`, optional): Ask about one destination country. Omit to return every country relevant to the sender. Example: US

Example input: `{"sender_id":"<sender_id>"}`

### `bird_sms_senders_list`

List Your SMS Senders · Read-only

Return the dedicated numbers and alphanumeric senders your workspace holds, newest first, with each sender's per-country registration status.
Returns data, an array of items with id, sender, source_kind, sender_type, country_code, number_id, status, next, destinations, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_sender_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `number_id` (`string`, optional): Return the sender for one number you hold, using the ID from List workspace numbers. Exactly one sender exists per number, so this returns at most one result. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. `created_at` (the default) sorts newest first with the default `order`. `sender` sorts alphabetically by the sender's own value (phone number, short code, or alphanumeric sender string), all treated as plain text. Example: created_at. One of: `created_at`, `sender`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `type` (`string`, optional): Filter senders by source type: a dedicated number, shared shortcode, or alphanumeric sender string. Example: example

Example input: `{}`

### `bird_sms_stats_breakdown_get`

Get Outbound SMS Statistics Breakdown · Read-only

Get outbound SMS statistics for a period grouped by one dimension (dimension): originators, countries, categories, error codes, carriers, tags, cost centers. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_sms_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/sms/stats/. Example: originators. One of: `originators`, `countries`, `categories`, `error-codes`, `carriers`, `tags`, `cost-centers`.
- `from` (`string`, optional): Start date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted; with `include_trend=true` and `trend_grain=hourly` the default tightens to keep the window within the 720-hour trend cap. Example: 2026-05-01
- `include_trend` (`boolean`, optional): When true, each row also carries a `trend` array: a short per-bucket lifecycle-count series for that row over the window. Returned only when `limit` is 50 or fewer and the window is at most 90 days (trend_grain=daily) or 720 hours (trend_grain=hourly); a larger request returns 422. Example: false
- `limit` (`integer`, optional): Maximum number of originator rows to return, ranked by the `sort` field descending. Example: 50
- `sort` (`string`, optional): Metric to rank rows by, applied descending. Any lifecycle count or derived rate in the response may be used; rows whose rate is undefined (zero denominator) sort last. Defaults to `accepted`. Example: accepted. One of: `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `expired`, `delivery_rate`, `failure_rate`.
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25
- `trend_grain` (`string`, optional): Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: daily. One of: `daily`, `hourly`.

Example input: `{"dimension":"originators"}`

### `bird_sms_stats_by_status_get`

Get Outbound SMS Statistics by Status · Read-only

Return one row per lifecycle status with activity in the requested period, ordered by count descending.
Returns data, an array of items with status, count, plus period, total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): Start date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{}`

### `bird_sms_stats_summary_get`

Get Aggregate Outbound SMS Statistics · Read-only

Return one aggregate row for the requested period.
Returns an object with period, delivery, latency, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `carrier` (`string`, optional): Restrict the statistics to a single delivery carrier. Mutually exclusive with the other dimension filters; only one may be set per request. Example: Verizon
- `category` (`string`, optional): Restrict the statistics to a single category. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `cost_center` (`string`, optional): Restrict the statistics to messages sent with this cost center. The match is exact. Mutually exclusive with the other dimension filters; only one may be set per request. Example: CC001234
- `country` (`string`, optional): Restrict the statistics to a single destination country, as an ISO 3166-1 alpha-2 code. Mutually exclusive with the other dimension filters; only one may be set per request. Example: US
- `from` (`string`, optional): Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset such as `+05:45` is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `to`. When omitted, it defaults to 30 days before `to` for day windows or 168 hours (7 days) before `to` for hour windows. Example: 2026-05-01
- `originator` (`string`, optional): Restrict the statistics to a single originator (the sender address messages were sent from). Mutually exclusive with the other dimension filters; only one may be set per request. Matches the message `from`. Example: BirdSMS
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `from`. When omitted, it defaults to today for day windows or the current hour for hour windows in that timezone. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_sms_stats_timeseries_get`

Get Outbound SMS Statistics Time Series · Read-only

Get outbound SMS statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, delivery, plus period.
Use this for trends over time. Use bird_sms_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `carrier` (`string`, optional): Restrict the statistics to a single delivery carrier. Mutually exclusive with the other dimension filters; only one may be set per request. Example: Verizon
- `category` (`string`, optional): Restrict the statistics to a single category. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
- `cost_center` (`string`, optional): Restrict the statistics to messages sent with this cost center. The match is exact. Mutually exclusive with the other dimension filters; only one may be set per request. Example: CC001234
- `country` (`string`, optional): Restrict the statistics to a single destination country, as an ISO 3166-1 alpha-2 code. Mutually exclusive with the other dimension filters; only one may be set per request. Example: US
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `originator` (`string`, optional): Restrict the statistics to a single originator (the sender address messages were sent from). Mutually exclusive with the other dimension filters; only one may be set per request. Matches the message `from`. Example: BirdSMS
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_sms_suppression_get`

Get SMS Suppression · Read-only

Return one suppression: the sender and subscriber it covers, why messages are stopped, how the record came to exist, what it blocks, and whether it is still in force.
Returns an object with id, destination, originator, reason, origin, applies_to, blocking, source_sms_id, effective_at, ended_at, ended_reason, ended_effective_at and more.
Use this when you have the ID. Use bird_sms_suppressions_list to find one.
Needs suppression_id from bird_sms_suppressions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression, as returned when it was created or listed. Example: ssu_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_sms_suppressions_list`

List SMS Suppressions · Read-only

Return the suppressions currently stopping your messages, most recent opt-out first.
Returns data, an array of items with id, destination, originator, reason, origin, applies_to, blocking, source_sms_id, effective_at, ended_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_suppression_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `destination` (`string`, optional): Return only suppressions for this exact subscriber number in E.164 form. Prefix matching is unsupported. Example: +15550001234
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `originator` (`string`, optional): Return only suppressions covering this sender. Example: +15557654321
- `reason` (`string`, optional): Return only suppressions with this reason: - `keyword_stop`: The subscriber texted a stop keyword to the sender. - `carrier_opted_out`: Their carrier reported the opt-out. - `manual`: Added through the API or dashboard. Example: keyword_stop. One of: `keyword_stop`, `carrier_opted_out`, `manual`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_sms_template_get`

Get SMS Template · Read-only

Return one SMS template's metadata, policies, language states, draft revision, and draft and live version IDs.
Returns an object with id, workspace_id, slug, name, description, scope, status, category, draft_version_id, live_version_id, published_version_id, revision and more.
Use this when you have the ID. Use bird_sms_templates_list to find one.
Needs template_ref from bird_sms_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`smt_…`) or slug. Built-in templates use a `bird_` slug. Write operations accept workspace templates because built-in templates are read-only. Example: bird_otp_verification

Example input: `{"template_ref":"<template_ref>"}`

### `bird_sms_template_version_get`

Get SMS Template Version · Read-only

Return one version with its variables and text in every language.
Returns an object with id, template_id, version_number, status, revision, variables, languages, default_language, created_at, published_at.
Use this when you have the ID. Use bird_sms_template_versions_list to find one.
Needs template_ref from bird_sms_templates_list; version_id from bird_sms_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`smt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version to read or reset. Example: smv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_sms_template_version_language_get`

Get SMS Template Version's Language · Read-only

Return one language's full text, revision, content hash, and update time.
Returns an object with language, text, revision, content_hash, updated_at.
Use this when you have the ID. Use bird_sms_template_version_languages_list to find one.
Needs template_ref from bird_sms_templates_list; version_id from bird_sms_template_versions_list; language from bird_sms_template_version_languages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Case and separator differences are accepted and canonicalized. Example: pt-BR
- `template_ref` (`string`, required): The template's ID (`smt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version that holds the language. Example: smv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_sms_template_version_languages_list`

List SMS Template Version's Languages · Read-only

Return the languages a version holds, ordered by canonical language tag, without their text.
Returns data, an array of items with language, revision, content_hash, updated_at.
Use this to browse or filter. Use bird_sms_template_version_language_get when you already have the ID.
Needs template_ref from bird_sms_templates_list; version_id from bird_sms_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`smt_…`) or slug. Example: order-shipped
- `version_id` (`string`, required): The version whose languages to list. Example: smv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_sms_template_versions_list`

List SMS Template's Versions · Read-only

Return a cursor-paginated version history, newest first.
Returns data, an array of items with id, template_id, version_number, status, revision, variables, default_language, available_languages, created_at, published_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_template_version_get when you already have the ID.
Needs template_ref from bird_sms_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's ID (`smt_…`) or slug. Example: order-shipped
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"template_ref":"<template_ref>"}`

### `bird_sms_templates_list`

List SMS Templates · Read-only

Return SMS templates as a cursor-paginated list. The workspace's templates come first, newest first, followed by our built-in templates by default.
Returns data, an array of items with id, workspace_id, slug, name, description, scope, status, category, draft_version_id, live_version_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_sms_template_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Return templates in this category. Example: transactional. One of: `transactional`, `marketing`, `authentication`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `language` (`string`, optional): Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match. Example: pt-BR
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `q` (`string`, optional): A case-insensitive substring search across slug, name, and description. Example: jane
- `scope` (`string`, optional): Filter by who owns the template. Use `system` for built-in templates and `workspace` for templates your workspace created. Example: system. One of: `system`, `workspace`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Return templates with this lifecycle status. Example: active. One of: `draft`, `pending`, `active`, `rejected`, `inactive`.

Example input: `{}`

### `bird_voice_call_recordings_list`

List Voice Call's Recordings and Transcripts · Read-only

Return everything captured across every leg of one call: its stored audio, each leg's view of it, and every transcription attempt over it.
Returns an object with media, recordings, transcripts, truncated.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `call_id` (`string`, required): The call to read, a vcs_ ID. Every leg carries its call's ID as call_id; bird_voice_legs_list returns legs with it. Example: vcs_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"call_id":"<call_id>"}`

### `bird_voice_call_transcript_get`

Get Voice Call's Transcript · Read-only

Return one transcript for the whole call: the cues of every party's stream in spoken order, each pointing into parties at the party its stream was captured from.
Returns an object with call_id, parties, cues, complete.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `call_id` (`string`, required): The call to read, a vcs_ ID. Every leg carries its call's ID as call_id; bird_voice_legs_list returns legs with it. Example: vcs_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"call_id":"<call_id>"}`

### `bird_voice_destinations_list`

List Voice Destination Countries · Read-only

Return every country the Voice service supports, each annotated with whether your workspace has enabled calling to it, whether the platform supports calling it (`status`), and any daily spend limit you set for it with today's usage.
Returns data, an array of items with country_code, country_name, dial_code, region, super_region, enabled, status, high_risk_destination, daily_spend_limit, plus total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_voice_leg_get`

Get Voice Leg · Read-only

Return a single leg at any point in its lifecycle.
Returns an object with id, call_id, workspace_id, direction, from, to, overdial_suffix, actor, sip_trunk_id, sip_call_id, status, sip_response_code and more.
Use this when you have the ID. Use bird_voice_legs_list to find one.
Needs leg_id from bird_voice_legs_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `leg_id` (`string`, required): ID of the call leg to retrieve, as returned by the leg list or webhook events. Example: vcl_01k0p3v9wera3v6q6xw3e9y2mh

Example input: `{"leg_id":"<leg_id>"}`

### `bird_voice_legs_list`

List Voice Legs · Read-only

Return a paginated list of the workspace's legs, ordered by start time descending.
Returns data, an array of items with id, call_id, workspace_id, direction, from, to, overdial_suffix, actor, sip_trunk_id, sip_call_id, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_voice_leg_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `call_id` (`string`, optional): Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated. Example: vcs_01krdgeqcxet5s7t44vh8rt9mg
- `direction` (`string`, optional): Return only legs in this direction. Example: outbound. One of: `inbound`, `outbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Return only legs placed from this calling party, matched exactly. Give a number in international form: `+14155551234`, `14155551234`, and `0014155551234` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. A `usr_` ID matches the recorded calling party exactly as given; it does not establish who placed the call. Use `number` instead to match part of a number, or either side of the leg. Example: +14155551234
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `number` (`string`, optional): Return only legs where the calling or called number contains this value. Matches a partial number, so a country or area-code prefix returns every leg to or from it. Combines with `from`/`to`, which match one side exactly. Example: +14155550123
- `sip_trunk_id` (`string`, optional): Return only legs carried by this SIP trunk. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `started_after` (`string`, optional): Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp. Example: 2026-01-15T09:30:00Z
- `started_before` (`string`, optional): Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp. Example: 2026-01-15T09:30:00Z
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Return only legs with one of these statuses, comma-separated. In-flight and final statuses may be combined freely. Example: ["answered"]
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.
- `to` (`string`, optional): Return only legs placed to this called party number, matched as a whole number rather than as a fragment. Give it in international form: `+16505559876`, `16505559876`, and `0016505559876` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. A `usr_`, `vrg_` or `vsq_` ID matches a browser's call to that workspace user, ring group or sequence, exactly as given. Use `number` instead to match part of a number, or either side of the leg. Example: +16505559876

Example input: `{}`

### `bird_voice_number_get`

Get Voice Number · Read-only

Return one of the numbers your workspace can use for voice.
Returns an object with id, phone_number, country_code, name, provider, directions, inbound_configuration, created_at.
Use this when you have the ID. Use bird_voice_numbers_list to find one.
Needs number_id from bird_voice_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): ID of the voice number to retrieve or update, as returned by the voice number list. Example: vnu_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"number_id":"<number_id>"}`

### `bird_voice_numbers_list`

List Numbers You Can Use for Voice · Read-only

List the phone numbers your workspace can use for voice: the voice-capable numbers we allocated to you, and the numbers from other carriers you registered and verified.
Returns data, an array of items with id, phone_number, country_code, name, provider, directions, inbound_configuration, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_voice_number_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: asc. One of: `asc`, `desc`.
- `provider` (`string`, optional): Filter by number source. `allocation` selects numbers we allocated to your workspace. `verified_number` selects numbers from another carrier that you registered for use as caller IDs. Example: allocation. One of: `allocation`, `verified_number`.
- `route` (`string`, optional): Filter by the answer incoming calls get. A number without a route of its own matches the route of your workspace's default. - `reject`: rejects incoming calls. - `trunk`: delivers calls to a SIP trunk. - `forward`: connects calls to the configured forwarding number. - `sequence`: runs the selected voice sequence entry. - `ring_group`: rings the group's online members. Numbers with an unsupported route are excluded when this filter is set. Example: reject. One of: `reject`, `trunk`, `forward`, `sequence`, `ring_group`.
- `search` (`string`, optional): Matches part of the phone number or name, ignoring case. Characters such as `%` and `_` match literally. Example: jane
- `sort` (`string`, optional): Field to sort by. Example: phone_number. One of: `phone_number`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_voice_ring_group_get`

Get Voice Ring Group · Read-only

Return one ring group. The default group's ID is `vrg_` followed by the workspace ID's suffix.
Returns an object with id, name, is_default, online_member_count, created_at, updated_at.
Use this when you have the ID. Use bird_voice_ring_groups_list to find one.
Needs ring_group_id from bird_voice_ring_groups_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ring_group_id` (`string`, required): ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"ring_group_id":"<ring_group_id>"}`

### `bird_voice_ring_group_members_list`

List Voice Ring Group's Members · Read-only

Return the ring group's members, in the order they joined.
Returns data, an array of items with user_id, created_at.
Needs ring_group_id from bird_voice_ring_groups_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ring_group_id` (`string`, required): ID of the ring group whose members to list or add to. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"ring_group_id":"<ring_group_id>"}`

### `bird_voice_ring_groups_list`

List Voice Ring Groups · Read-only

Return the workspace's ring groups. The first is always the default group, which is not stored: it rings the users who are online in the browser phone.
Returns data, an array of items with id, name, is_default, online_member_count, created_at, updated_at.
Use this to browse or filter. Use bird_voice_ring_group_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_voice_settings_get`

Get Voice Settings · Read-only

Return the voice settings for your workspace. `inbound_configuration.route` is what happens to calls for every Bird number that has no inbound route of its own.
Returns an object with inbound_configuration, daily_spend_limit.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_voice_trunk_gateway_get`

Get Voice SIP Trunk Gateway · Read-only

Return a single gateway by ID. Returns a 404 `not_found_error` if the trunk or the gateway does not exist in the workspace.
Returns an object with id, trunk_id, sip_uri, priority, origination_format, destination_format, created_at, updated_at.
Use this when you have the ID. Use bird_voice_trunk_gateways_list to find one.
Needs trunk_id from bird_voice_trunks_list; gateway_id from bird_voice_trunk_gateways_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `gateway_id` (`string`, required): ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
- `trunk_id` (`string`, required): ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"gateway_id":"<gateway_id>","trunk_id":"<trunk_id>"}`

### `bird_voice_trunk_gateways_list`

List Voice SIP Trunk's Gateways · Read-only

Return the gateway addresses used to forward inbound calls to this trunk, ordered by priority.
Returns data, an array of items with id, trunk_id, sip_uri, priority, origination_format, destination_format, created_at, updated_at.
Use this to browse or filter. Use bird_voice_trunk_gateway_get when you already have the ID.
Needs trunk_id from bird_voice_trunks_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `trunk_id` (`string`, required): ID of the SIP trunk whose gateways to list or create. Example: spt_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"trunk_id":"<trunk_id>"}`

### `bird_voice_trunk_get`

Get Voice SIP Trunk · Read-only

Return a single SIP trunk, including its Bird-assigned `domain`, its IP access control lists, and its allowed API keys.
Returns an object with id, workspace_id, name, domain, outbound_enabled, inbound_enabled, media_bypass, ip_acls, allowed_api_key_ids, ineligible_api_key_ids, digest_algorithms, session_credentials_enabled and more.
Use this when you have the ID. Use bird_voice_trunks_list to find one.
Needs trunk_id from bird_voice_trunks_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `trunk_id` (`string`, required): ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"trunk_id":"<trunk_id>"}`

### `bird_voice_trunks_list`

List Voice SIP Trunks · Read-only

Return the workspace's SIP trunks as a paginated list, each with its assigned `domain` and access control lists.
Returns data, an array of items with id, workspace_id, name, domain, outbound_enabled, inbound_enabled, media_bypass, ip_acls, allowed_api_key_ids, ineligible_api_key_ids, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_voice_trunk_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_voice_verified_number_get`

Get Voice Verified Number · Read-only

Return the verified number with the given ID, including its verification status.
Returns an object with id, workspace_id, phone_number, name, status, outbound_enabled, verified_at, created_at, updated_at.
Use this when you have the ID. Use bird_voice_verified_numbers_list to find one.
Needs verified_number_id from bird_voice_verified_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `verified_number_id` (`string`, required): ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"verified_number_id":"<verified_number_id>"}`

### `bird_voice_verified_numbers_list`

List Voice Verified Numbers · Read-only

Return a paginated list of the workspace's verified numbers and their verification status.
Returns data, an array of items with id, workspace_id, phone_number, name, status, outbound_enabled, verified_at, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_voice_verified_number_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_webhook_attempts_list`

List Delivery Attempts · Read-only

Return the endpoint's recent delivery attempts, newest first.
Returns data, an array of items with id, event_id, event_type, status, url, failure_reason, response_status_code, response_body, response_duration_ms, attempted_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs webhook_id from bird_webhooks_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `after` (`string`, optional): Only return attempts strictly after this timestamp. Example: 2026-01-15T09:30:00Z
- `before` (`string`, optional): Only return attempts strictly before this timestamp. Example: 2026-01-15T09:30:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of attempts to return. Defaults to 50, capped at 100. Example: 50
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_webhook_callback_attempts_list`

List Callback Delivery Attempts · Read-only

Return the workspace's recent delivery attempts to SMS callback URLs, newest first.
Returns data, an array of items with id, event_id, event_type, status, url, failure_reason, response_status_code, response_body, response_duration_ms, attempted_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): Only return attempts strictly after this timestamp. Example: 2026-01-15T09:30:00Z
- `before` (`string`, optional): Only return attempts strictly before this timestamp. Example: 2026-01-15T09:30:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of attempts to return. Defaults to 50, capped at 100. Example: 50
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_webhook_get`

Get Webhook Endpoint · Read-only

Return one webhook endpoint's configuration and current delivery `status`, including its URL and subscribed event types.
Returns an object with id, url, description, filter, events, status, destination, next, created_at, updated_at.
Use this when you have the ID. Use bird_webhooks_list to find one.
Needs webhook_id from bird_webhooks_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_webhooks_list`

List Webhook Endpoints · Read-only

Return the workspace's webhook endpoints as a cursor-paginated list, newest first by default.
Returns data, an array of items with id, url, description, filter, events, status, destination, next, created_at, updated_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_webhook_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort webhook endpoints by: `created_at` (the default; newest first with the default `order`) or the endpoint URL. Example: created_at. One of: `created_at`, `url`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `url` (`string`, optional): Only endpoints delivering to exactly this URL. Several endpoints can share a URL, so this finds matches for a setup to reuse; it does not prevent a duplicate. Example: https://hooks.zapier.com/hooks/catch/123/abc/

Example input: `{}`

### `bird_whatsapp_agent_notification_get`

Get WhatsApp Notification Sent to an Agent · Read-only

Return one notification you sent the agent, with what came of it: `accepted` while WhatsApp is still working on it, then `success`, `skipped` with WhatsApp's reason, or `failed` with what went wrong.
Returns an object with id, from, to, name, description, payload, status, skipped_reason, error, created_at.
Use this when you have the ID. Use bird_whatsapp_agent_notifications_list to find one.
Needs notification_id from bird_whatsapp_agent_notifications_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `notification_id` (`string`, required): ID of the notification (`waan_` prefix), as returned when it was sent. Example: waan_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"notification_id":"<notification_id>"}`

### `bird_whatsapp_agent_notifications_list`

List WhatsApp Notifications Sent to Your Agents · Read-only

Return the notifications you have sent your agents, newest first, each with what came of it.
Returns data, an array of items with id, from, to, name, description, payload, status, skipped_reason, error, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_agent_notification_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Return only notifications sent to the agent on this business number, in E.164 format. A phone number is normalized before matching, so spacing does not matter. Example: +13124495648
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`string`, optional): Return only notifications in this state. Example: success. One of: `accepted`, `success`, `skipped`, `failed`.
- `to` (`string`, optional): Return only notifications about this contact, a phone number in E.164 format or a business-scoped user ID. A phone number is normalized before matching, so spacing does not matter. Example: +14155551234

Example input: `{}`

### `bird_whatsapp_business_account_get`

Get WhatsApp Business Account · Read-only

Return one WhatsApp Business Account your workspace has connected, addressed by either the `id` the account list reports (`waa_` prefix) or the `waba` value WhatsApp reports for it.
Returns an object with id, waba, name, status, account_review_status, business_verification_status, marketing_messages_onboarding_status, portfolio, ban, next, meta_health_status, meta_synced_at and more.
Use this when you have the ID. Use bird_whatsapp_business_accounts_list to find one.
Needs business_account_ref from bird_whatsapp_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_ref` (`string`, required): WhatsApp Business Account ID (`waa_` prefix) or the WhatsApp Business Account ID Meta reports in `waba`. A value that parses as a valid ID resolves by ID; any other value resolves as Meta's ID. Example: 102290129340001

Example input: `{"business_account_ref":"<business_account_ref>"}`

### `bird_whatsapp_business_account_reach_estimate_get`

Estimate WhatsApp Marketing Reach for a Maximum Price · Read-only

Return Meta's estimate of how many marketing deliveries, and at what cost, each candidate maximum price would have won over `window`.
Returns an object with currency_code, estimates.
Needs business_account_ref from bird_whatsapp_business_accounts_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `business_account_ref` (`string`, required): WhatsApp Business Account ID (`waa_` prefix) or the WhatsApp Business Account ID Meta reports in `waba`. A value that parses as a valid ID resolves by ID; any other value resolves as Meta's ID. Example: 102290129340001
- `countries` (`array`, required): The recipients' country, as an ISO 3166-1 alpha-2 code. Exactly one, because Meta refuses an estimate for more than one country. Example: ["BR"]
- `window` (`string`, optional): The days of recent auctions the estimate is based on, ending now. Omit it to use the last 7 days. Example: 7d. One of: `1d`, `7d`, `14d`, `28d`.

Example input: `{"business_account_ref":"<business_account_ref>","countries":["BR"]}`

### `bird_whatsapp_business_accounts_list`

List WhatsApp Business Accounts · Read-only

Return a paginated list of the WhatsApp Business Accounts your workspace has connected, so you can choose which one a template belongs to.
Returns data, an array of items with id, waba, name, status, account_review_status, business_verification_status, marketing_messages_onboarding_status, portfolio, ban, next, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_business_account_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_whatsapp_conversation_events_list`

List WhatsApp Conversation Events · Read-only

Return the conversation's activity history, newest first: - A move of control between the Meta Business Agent and your application. - An assignment, reassignment or unassignment. - A notification sent to the agent about this contact.
Returns data, an array of items with id, type, summary, metadata, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs conversation_id from bird_whatsapp_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `type` (`string`, optional): Keep only events of this exact type (for example `whatsapp_conversation.control_changed`). Omit for every type.

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_whatsapp_conversation_get`

Get WhatsApp Conversation · Read-only

Return one conversation's current state: who answers it right now, when its customer-service window closes, how many messages are unread, its labels, and its most recent message.
Returns an object with id, business_phone_number, recipient, inbox_status, control, assigned_to, service_window, last_message, unread_count, labels, created_at, updated_at.
Use this when you have the ID. Use bird_whatsapp_conversations_list to find one.
Needs conversation_id from bird_whatsapp_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_whatsapp_conversation_message_get`

Get Message in a WhatsApp Conversation · Read-only

Return one message in a conversation. It is the same object get a WhatsApp message returns, but read from the conversation's own store, so a message is readable here as soon as the conversation records it.
Returns an object with id, direction, from, to, template, text, image, video, audio, sticker, document, location and more.
Use this when you have the ID. Use bird_whatsapp_conversation_messages_list to find one.
Needs conversation_id from bird_whatsapp_conversations_list; message_id from bird_whatsapp_conversation_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
- `message_id` (`string`, required): Message identifier. Starts with `wam_`. Example: wam_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"conversation_id":"<conversation_id>","message_id":"<message_id>"}`

### `bird_whatsapp_conversation_messages_list`

List Messages in a WhatsApp Conversation · Read-only

Return the messages in one conversation, newest first, as a cursor-paginated list.
Returns data, an array of items with id, direction, from, to, template, text, image, video, audio, sticker, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_conversation_message_get when you already have the ID.
Needs conversation_id from bird_whatsapp_conversations_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
- `direction` (`string`, optional): Return only messages the contact sent (`inbound`) or only messages sent to them (`outbound`). Omit for both. Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_whatsapp_conversations_list`

List WhatsApp Conversations · Read-only

Return the workspace's WhatsApp conversations as a cursor-paginated list, most recently active first.
Returns data, an array of items with id, business_phone_number, recipient, inbox_status, control, assigned_to, service_window, last_message, unread_count, labels, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_conversation_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `assigned_to` (`string`, optional): Return conversations assigned to this workspace member. Pass `me` for the signed-in user or `unassigned` for conversations without an assignee. An API key cannot use `me` and receives a `422` response. Example: unassigned
- `business_phone_number` (`string`, optional): Return only conversations on this WhatsApp business phone number, in E.164 format. Omit to cover every number in the workspace. Example: +15550001234
- `control` (`string`, optional): Return only conversations the agent holds (`meta_business_agent`) or that your workspace holds (`bird`). Example: bird
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `inbox_status` (`string`, optional): Filter by workspace inbox status. Omit to include open and resolved conversations. Example: open. One of: `open`, `resolved`.
- `label` (`array`, optional): Return conversations carrying this label, matched in any casing. Repeat the parameter to require every supplied label. A name the workspace doesn't have matches nothing. Example: ["billing"]
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): Return only conversations whose contact phone number, BSUID, username, display name, group name or one of its labels contains this text, ignoring case. A phone number matches with or without its `+`, spaces, dashes, dots or parentheses. A group matches the name it had when its conversation started, and only for callers with `whatsapp_management` read access. The text cannot contain control characters such as tabs or line breaks. Example: jamie
- `service_window_status` (`string`, optional): Return only conversations whose customer-service window is `open` or `closed`. Example: open. One of: `open`, `closed`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_whatsapp_group_get`

Get WhatsApp Group · Read-only

Return one group as it currently stands, including who is in it.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Use this when you have the ID. Use bird_whatsapp_groups_list to find one.
Needs group_id from bird_whatsapp_groups_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `group_id` (`string`, required): ID of the group, as returned when it was created. Example: wag_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"group_id":"<group_id>"}`

### `bird_whatsapp_group_join_requests_list`

List WhatsApp Group's Join Requests · Read-only

Return the join requests still waiting for a decision, oldest first.
Returns data, an array of items with id, bsuid, phone_number, username, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs group_id from bird_whatsapp_groups_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `group_id` (`string`, required): ID of the group whose join requests are being listed. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: asc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"group_id":"<group_id>"}`

### `bird_whatsapp_groups_list`

List WhatsApp Groups · Read-only

Return the WhatsApp groups your workspace created as a cursor-paginated list, newest first.
Returns data, an array of items with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_group_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `number` (`string`, optional): Filter by the business number that administers the group, as either the number in E.164 format or the number's `id` (`wan_` prefix). A value that parses as a valid ID resolves by ID; any other value must be an E.164 number, and anything else is a `422`. The E.164 form is matched against the group's stored record of the number it was created on. Example: +13124495648
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `q` (`string`, optional): Case-insensitive substring match against the group's subject or description. Example: support
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Filter by status. Repeat the parameter to match any of several statuses. Example: ["active"]
- `waba` (`string`, optional): Filter by the WABA identifier returned on the group. Groups with `waba: null` do not match this filter. Example: 102290129340398

Example input: `{}`

### `bird_whatsapp_inbound_stats_by_phone_number_get`

Get Inbound WhatsApp Statistics by Phone Number · Read-only

Return how many WhatsApp messages each of your business phone numbers received.
Returns data, an array of items with phone_number, received, plus period, total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): Inclusive start of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Must not be after `to`. Max window 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-06-14
- `limit` (`integer`, optional): Maximum number of phone-number rows to return, ranked by received-message volume descending. Example: 50
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Max window 365 days. Defaults to today in that timezone when omitted. Example: 2026-07-13

Example input: `{}`

### `bird_whatsapp_inbound_stats_summary_get`

Get Aggregate Inbound WhatsApp Statistics · Read-only

Return the total number of WhatsApp messages your business numbers received over the period, using the time each message reached your number.
Returns an object with period, received, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `compare` (`string`, optional): Set to `previous_period` to include the received-message count for the immediately preceding window of equal length. The response also includes the change between the two, so you can show "+X% vs last period" without a second request. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window, either a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The form you use selects the grain the total is resolved at. Interpreted in `timezone`, or in UTC when `timezone` is omitted. Must use the same form as `to`. A numeric UTC offset (for example `+05:45`) is rejected when `timezone` is set; pass a calendar day or a `Z` instant instead. Defaults to 30 days before `to` for day windows, or 168 hours before `to` for hour windows. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, in the same form as `from`. Defaults to today, or the current hour for an hour window. A day window may not exceed 365 days and an hour window 720 hours. Example: 2026-05-25

Example input: `{}`

### `bird_whatsapp_inbound_stats_timeseries_get`

Get Inbound WhatsApp Statistics Time Series · Read-only

Get inbound WhatsApp statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, received, plus period.
Use this for trends over time. Use bird_whatsapp_inbound_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to today in that timezone when omitted. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_whatsapp_keyword_rule_get`

Get WhatsApp Keyword Rule · Read-only

Return one keyword rule, either one of Bird's own or one you created, with its `effective_keywords` and the reply it sends.
Returns an object with id, scope, operation, country, waba, keywords, effective_keywords, reply, created_at, updated_at.
Use this when you have the ID. Use bird_whatsapp_keyword_rules_list to find one.
Needs id from bird_whatsapp_keyword_rules_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the keyword rule, as returned by the list operation. Bird's own rules and yours share one ID space. Example: wkr_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"id":"<id>"}`

### `bird_whatsapp_keyword_rules_list`

List WhatsApp Keyword Rules · Read-only

Return the keyword rules that apply to inbound messages, most specific first.
Returns data, an array of items with id, scope, operation, country, waba, keywords, effective_keywords, reply, created_at, updated_at.
Use this to browse or filter. Use bird_whatsapp_keyword_rule_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Keep only rules that apply to someone messaging from this country, as an ISO 3166-1 alpha-2 code. Omit for every rule, whichever country it covers. Example: US
- `operation` (`string`, optional): Keep only rules for this operation. Omit for all of them. Open on the same terms as the response, so an operation Bird gains later can be filtered for without a client update; one Bird does not answer matches nothing rather than failing. Example: opt_out
- `scope` (`string`, optional): Keep only Bird's own rules (`system`) or only the rules you created (`workspace`). Omit for both. Example: workspace. One of: `system`, `workspace`.
- `waba` (`string`, optional): Keep only the rules that apply to this WhatsApp Business Account of yours, identified by its WhatsApp-issued account ID or by the `waa_` ID Bird gives it. Either form finds the same rules. Example: 102290129340398

Example input: `{}`

### `bird_whatsapp_message_events_list`

List Events for a WhatsApp Message · Read-only

Return a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (`whatsapp.accepted`, `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`).
Returns data, an array of items with id, type, occurred_at, recipient, error.
Needs message_id from bird_whatsapp_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message, as returned in the send response's `id` field. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `type` (`string`, optional): Keep only events of this exact type (for example `whatsapp.delivered` or `whatsapp.failed`). Omit for the full timeline.

Example input: `{"message_id":"<message_id>"}`

### `bird_whatsapp_message_get`

Get WhatsApp Message · Read-only

Return a single WhatsApp message: its current delivery status, per-stage timestamps (`sent_at`, `delivered_at`, `read_at`), and failure detail when it failed.
Returns an object with id, direction, from, to, template, text, image, video, audio, sticker, document, location and more.
Use this when you have the ID. Use bird_whatsapp_messages_list to find one.
Needs message_id from bird_whatsapp_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message, as returned in the send response's `id` field. Example: wam_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"message_id":"<message_id>"}`

### `bird_whatsapp_message_reaction_events_list`

List Reaction Events for a WhatsApp Message · Read-only

Return the changes made to this message's reactions as a cursor-paginated list, newest first: each emoji placed, each one replaced by a different emoji, and each one taken back.
Returns data, an array of items with id, emoji, status, from, error, occurred_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs message_id from bird_whatsapp_messages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message whose reactions to read, as returned in the `id` field of the message. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"message_id":"<message_id>"}`

### `bird_whatsapp_messages_list`

List WhatsApp Messages · Read-only

Return the workspace's WhatsApp messages as a cursor-paginated list, newest first, outbound and inbound alike.
Returns data, an array of items with id, direction, from, to, template, text, image, video, audio, sticker, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_message_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bsuid` (`string`, optional): Filter by business-scoped user ID (Meta identifier), matching the contact in either direction. `to` and `from` also accept one, but each matches a single end of the message. Example: US.13491208655302741918
- `category` (`string`, optional): Filter by category. Example: transactional
- `created_after` (`string`, optional): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-05-01T00:00:00Z
- `created_before` (`string`, optional): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset. Example: 2026-06-01T00:00:00Z
- `direction` (`string`, optional): Filter by whether the business sent the message (`outbound`) or received it from the contact (`inbound`). Example: outbound. One of: `outbound`, `inbound`.
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `from` (`string`, optional): Filter by sender, exact match. The sender is your business number on an outbound message and the contact on an inbound one, matching the `from` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `from=` matches inbound messages only. Example: +13124495648
- `group_id` (`string`, optional): Filter by the WhatsApp group the message belongs to, in either direction: the group an outbound message was addressed to, or the group an inbound message arrived through. Matches the `group_id` on each message's `to`. It names one group, so there is no way to ask for the messages that belong to no group: omit it to list group and one-to-one messages together. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `phone_number` (`string`, optional): Deprecated: use `to` or `from` instead, which also match a business-scoped user ID. Filters by contact phone number (E.164 exact match), in either direction. Example: +15551234567
- `reference` (`string`, optional): Keep only messages whose `reference` is exactly this value. The match is case-sensitive, and several messages can share a reference. Example: INV-1234
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Filter by status. Repeat the parameter to match any of several statuses. Example: ["scheduled"]
- `tag` (`array`, optional): Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.
- `to` (`string`, optional): Filter by recipient, exact match. The recipient is the contact on an outbound message and your business number on an inbound one, matching the `to` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `to=` matches outbound messages only. Example: +15551234567

Example input: `{}`

### `bird_whatsapp_number_events_list`

List WhatsApp Number Events · Read-only

Return the number's activity history, newest first by default: - The number being added, and every change of its status. - A messaging-limit change reported by WhatsApp. - A display-name review decision. - A quality-rating change, observed when Bird next reads the number.
Returns data, an array of items with id, type, summary, metadata, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Needs number_id from bird_whatsapp_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): ID of the WhatsApp number whose events to list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `sort` (`string`, optional): Field to sort by. Defaults to `created_at`. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"number_id":"<number_id>"}`

### `bird_whatsapp_number_get`

Get WhatsApp Number · Read-only

Return a WhatsApp number connected to the workspace and its state as of `meta_synced_at`.
Returns an object with id, waba, phone_number, number_id, meta_preverified_id, verified_until, name, scope, data_localization_region, status, next, error and more.
Use this when you have the ID. Use bird_whatsapp_numbers_list to find one.
Needs number_id from bird_whatsapp_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): ID of the WhatsApp number (`wan_` prefix), as returned by the number list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"number_id":"<number_id>"}`

### `bird_whatsapp_number_profile_get`

Get WhatsApp Number's Business Profile · Read-only

Return the business profile WhatsApp shows to people this number messages, read from WhatsApp on each request rather than from a stored copy.
Returns an object with display_name, display_name_status, new_display_name, new_display_name_status, username, username_status, about, address, description, email, vertical, websites and more.
Needs number_id from bird_whatsapp_numbers_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): ID of the WhatsApp number (`wan_` prefix), as returned by the number list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"number_id":"<number_id>"}`

### `bird_whatsapp_numbers_list`

List WhatsApp Numbers · Read-only

Return a paginated list of the WhatsApp numbers your workspace can send from.
Returns data, an array of items with id, waba, phone_number, number_id, meta_preverified_id, verified_until, name, scope, data_localization_region, status, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_number_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `include_total` (`boolean`, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `order` (`string`, optional): Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: desc. One of: `asc`, `desc`.
- `phone_number` (`string`, optional): Filter to a single number. The value is read as an international number and normalized before matching, so `+31612340001`, `+31 6 1234 0001`, `0031612340001` and `31612340001` are the same filter. A value that cannot be normalized is matched exactly as given. A number this workspace cannot send from returns an empty page, rather than being rejected. Example: +31612340001
- `scope` (`string`, optional): Filter by ownership tier: `system` for platform-managed numbers and `workspace` for numbers your workspace connected. Omit to return both. A `system` number belongs to no WhatsApp Business Account, so pairing this with `waba` always returns an empty page. Example: workspace. One of: `system`, `workspace`.
- `sort` (`string`, optional): Field to sort by. Example: created_at. One of: `created_at`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Filter by the number's WhatsApp state: the `status` a number in this list carries. Every value matches that status exactly, so repeat the parameter for each state you want. `pending` covers both a number WhatsApp reports as not registered and one it has reported no state for at all, while the two states before that keep their own values: a number we are still verifying carries `preparing`, and one waiting for someone to finish signup carries `awaiting_signup`. Asking for all three reaches every connection that has not finished, plus any finished one WhatsApp has not reported on yet. `failed` matches a connection refused permanently. A value this vocabulary does not recognize matches nothing, rather than being rejected. Omit to return numbers in every state. Example: ["connected"]
- `waba` (`string`, optional): Filter to a single WhatsApp Business Account by its Meta-assigned ID. Use the `waba` of a connected WhatsApp Business Account, or the `waba` on a number this list returns. A platform-managed number belongs to no WhatsApp Business Account and is never returned when this is set, so pairing it with `scope=system` always returns an empty page. An account this workspace does not hold returns an empty page. Example: 102290129340398

Example input: `{}`

### `bird_whatsapp_stats_breakdown_get`

Get Outbound WhatsApp Statistics Breakdown · Read-only

Get outbound WhatsApp statistics for a period grouped by one dimension (dimension): error codes, templates, template categories, tags, phone numbers, countries. Rows are ranked and capped by limit.
Returns data, one row per group with its delivery and latency metrics (the first field names the group and changes with dimension), plus the period.
Use this to compare senders, countries or other groups. Use bird_whatsapp_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dimension` (`string`, required): What to group the statistics by. Each value maps to its own Bird endpoint under /v1/whatsapp/stats/. Example: error-codes. One of: `error-codes`, `templates`, `template-categories`, `tags`, `phone-numbers`, `countries`.
- `from` (`string`, optional): Inclusive start of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Must not be after `to`. Max window 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-06-14
- `limit` (`integer`, optional): Maximum number of error-code rows to return, ranked by failure count descending. Example: 50
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Max window 365 days. Defaults to today in that timezone when omitted. Example: 2026-07-13

Example input: `{"dimension":"error-codes"}`

### `bird_whatsapp_stats_summary_get`

Get Aggregate Outbound WhatsApp Statistics · Read-only

Return one aggregate row for the requested period.
Returns an object with period, delivery, engagement, latency, comparison.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Restrict the statistics to a single message category; `service` selects free-form messages. Mutually exclusive with the other dimension filters (`template`, `phone_number`, `tag`); only one may be set per request. Matches the `category` key on a row of the per-category breakdown. Example: transactional
- `compare` (`string`, optional): Set to `previous_period` to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request. The comparison window carries any dimension filter set on the request, so a filtered comparison compares like with like. Example: previous_period. One of: `previous_period`.
- `from` (`string`, optional): Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset such as `+05:45` is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `to`. When omitted, it defaults to 30 days before `to` for day windows or 168 hours (7 days) before `to` for hour windows. Example: 2026-05-01
- `phone_number` (`string`, optional): Restrict the statistics to a single business sender phone number, in E.164 form. Mutually exclusive with the other dimension filters (`template`, `category`, `tag`); only one may be set per request. Matches the `phone_number` key on a row of the per-phone-number breakdown. Example: +13124495569
- `tag` (`string`, optional): Restrict the statistics to a single tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). Mutually exclusive with the other dimension filters (`template`, `category`, `phone_number`); only one may be set per request. A row of the per-tag breakdown carries the same pair in its single `tag` key. Example: campaign:spring_launch
- `template` (`string`, optional): Restricts the statistics to one template, identified by its ID (`wat_…`) or slug. Mutually exclusive with the other dimension filters (`category`, `phone_number`, `tag`); only one may be set per request. An ID matches the `template_id` key on a row of the per-template breakdown; a slug is accepted for callers that predate that key and resolves to the same messages. Example: wat_01krdgeqcxet5s7t44vh8rt9mg
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant rounded down to the hour. The `timezone` parameter makes a calendar day local and rounds an instant down to the local hour. Omit `timezone` to use UTC. When `timezone` is set, a numeric UTC offset is rejected; use a calendar day or a `Z` (UTC) instant. This value must use the same form as `from`. When omitted, it defaults to today for day windows or the current hour for hour windows in that timezone. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days). Example: 2026-05-25

Example input: `{}`

### `bird_whatsapp_stats_timeseries_get`

Get Outbound WhatsApp Statistics Time Series · Read-only

Get outbound WhatsApp statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.
Returns data, an array of items with bucket, delivery, engagement, latency, plus period.
Use this for trends over time. Use bird_whatsapp_stats_summary_get for one period total.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `granularity` (`string`, required): Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: daily. One of: `daily`, `hourly`.
- `category` (`string`, optional): Restrict the statistics to a single message category; `service` selects free-form messages. Mutually exclusive with the other dimension filters (`template`, `phone_number`, `tag`); only one may be set per request. Matches the `category` key on a row of the per-category breakdown. Example: transactional
- `from` (`string`, optional): Start date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to 30 days before `to` when omitted. Example: 2026-05-01
- `phone_number` (`string`, optional): Restrict the statistics to a single business sender phone number, in E.164 form. Mutually exclusive with the other dimension filters (`template`, `category`, `tag`); only one may be set per request. Matches the `phone_number` key on a row of the per-phone-number breakdown. Example: +13124495569
- `tag` (`string`, optional): Restrict the statistics to a single tag. Use `name` to match any value of a tag, or `name:value` for a specific pair (for example `campaign:spring_launch`). Mutually exclusive with the other dimension filters (`template`, `category`, `phone_number`); only one may be set per request. A row of the per-tag breakdown carries the same pair in its single `tag` key. Example: campaign:spring_launch
- `template` (`string`, optional): Restricts the statistics to one template, identified by its ID (`wat_…`) or slug. Mutually exclusive with the other dimension filters (`category`, `phone_number`, `tag`); only one may be set per request. An ID matches the `template_id` key on a row of the per-template breakdown; a slug is accepted for callers that predate that key and resolves to the same messages. Example: wat_01krdgeqcxet5s7t44vh8rt9mg
- `timezone` (`string`, optional): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets. Example: Asia/Kathmandu
- `to` (`string`, optional): End date (inclusive), YYYY-MM-DD. Interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). The window may not exceed 365 days. Defaults to today in that timezone when omitted. Example: 2026-05-25

Example input: `{"granularity":"daily"}`

### `bird_whatsapp_suppression_get`

Get WhatsApp Suppression · Read-only

Return the suppression record for the given ID, including one that has already ended.
Returns an object with id, address, waba, reason, origin, applies_to, source_whatsapp_id, ended_at, ended_reason, created_at.
Use this when you have the ID. Use bird_whatsapp_suppressions_list to find one.
Needs suppression_id from bird_whatsapp_suppressions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the WhatsApp suppression record to retrieve or end. Example: was_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_whatsapp_suppressions_list`

List WhatsApp Suppressions · Read-only

Return a paginated list of the WhatsApp addresses the workspace is currently suppressing.
Returns data, an array of items with id, address, waba, reason, origin, applies_to, source_whatsapp_id, ended_at, ended_reason, created_at, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_suppression_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address` (`string`, optional): Address prefix filter (case-insensitive). A complete address returns only that address; a partial value returns all matches. Example: +5511977670804
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `reason` (`string`, optional): Return only suppressions with this reason: - `manual`: Added through the API or dashboard. Example: manual. One of: `manual`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{}`

### `bird_whatsapp_template_get`

Get WhatsApp Message Template · Read-only

Return one template by its ID or slug: its lifecycle, the languages a send can currently resolve, a summary of where every language stands at Meta, and a pointer to the version that is live.
Returns an object with id, slug, slug_editable, name, description, scope, waba, category, status, default_language, on_missing_language, language_source_required and more.
Use this when you have the ID. Use bird_whatsapp_templates_list to find one.
Needs template_ref from bird_whatsapp_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp

Example input: `{"template_ref":"<template_ref>"}`

### `bird_whatsapp_template_version_get`

Get WhatsApp Template Version · Read-only

Return one version: the content of every language it holds and what its submission did with each.
Returns an object with id, template_id, version_number, submitted_at, variables, languages, created_at.
Use this when you have the ID. Use bird_whatsapp_template_versions_list to find one.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_version_language_get`

Get WhatsApp Version's Language · Read-only

Return one language of one version: its content blocks, what this version's submission did with it, and everything Meta holds about it: review outcome and category.
Returns an object with parameter_bindings, optimization_spec, message_send_ttl_seconds, language, components, status, revision, content_hash, category, previous_category, quality, pause and more.
Use this when you have the ID. Use bird_whatsapp_template_version_languages_list to find one.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list; language from bird_whatsapp_template_version_languages_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language, as a BCP-47 tag. Case and separator variance is accepted and normalised, and the canonical form is returned. Example: nl-BE
- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_version_languages_list`

List WhatsApp Version's Languages · Read-only

Return every language a version holds, without content: each language's tag, what this version's submission did with it, its write counter, and a hash over its content.
Returns data, an array of items with language, status, revision, content_hash, next.
Use this to browse or filter. Use bird_whatsapp_template_version_language_get when you already have the ID.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_versions_list`

List WhatsApp Template's Versions · Read-only

Return the template's versions, newest first. Each names the languages it holds and what became of them; content is not here, since a page of versions would carry a copy of every language in every one of them.
Returns data, an array of items with id, template_id, version_number, submitted_at, variables, languages, created_at, next, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_template_version_get when you already have the ID.
Needs template_ref from bird_whatsapp_templates_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd

Example input: `{"template_ref":"<template_ref>"}`

### `bird_whatsapp_templates_list`

List WhatsApp Available Message Templates · Read-only

Return the WhatsApp message templates available to your workspace: both the workspace's own templates (`scope: workspace`) and our built-in, Meta-approved templates (`scope: system`); filter to one tier with `scope`.
Returns data, an array of items with id, slug, slug_editable, name, description, scope, waba, category, status, default_language, plus next_cursor (pass it as starting_after for the next page; null on the last page).
Use this to browse or filter. Use bird_whatsapp_template_get when you already have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, optional): Filter by template category. Example: transactional
- `ending_before` (`string`, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `limit` (`integer`, optional): Maximum number of items to return per page. Example: 25
- `q` (`string`, optional): A case-insensitive substring search across the template's slug, name, and description. Example: jane
- `scope` (`string`, optional): Filter by ownership tier: `system` for the built-in, Meta-approved template catalog, or `workspace` for the workspace's own templates. Omit to return both. Example: system. One of: `system`, `workspace`.
- `starting_after` (`string`, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
- `status` (`array`, optional): Filter by lifecycle status. Repeat the parameter to match any of several. Our built-in templates are always `active`. Example: ["active"]
- `waba` (`string`, optional): Filter to a single WhatsApp Business Account by its Meta WABA ID: the same value each template reports in its own `waba` field. Our built-in templates belong to no account and are never returned when this is set, and an account your workspace does not hold returns an empty page. Example: 102290129340398

Example input: `{}`

### `bird_workspace_get`

Get Current Workspace · Read-only

Return the workspace the current credentials are scoped to: its ID, name, the ID of the organization that owns it, and its notification and logo settings.
Returns an object with id, organization_id, name, notification_emails, logo_url, suspended_at, created_at, updated_at.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_workspace_quotas_list`

List Workspace Quotas · Read-only

Return each resource and value quota as it applies to the current workspace: the organization limit shared by all workspaces, the workspace's own limit when one is set, and this workspace's current usage.
Returns data, an array of items with key, name, description, unit, label, type, kind, enforcement, maximum_value, organization_limit, plus configuration.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_workspace_rate_limits_list`

List Workspace Rate Limits · Read-only

Only relevant to organizations with several workspaces, or one left with a workspace limit or enabled allocation after a deletion.
Returns data, an array of items with key, name, description, unit, window_seconds, organization_limit, workspace_limit, limit, limit_source, automatic_limit.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `bird_amb_attachment_create`

Upload Apple Messages Attachment · Write

Upload a file to Apple for the business account identified by `from` and returns an attachment you can send by `attachment_id`.
Returns an object with id, business_account_id, origin, message_id, name, mime_type, size, expires_at, created_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Apple business identifier of the business account that sends the attachment. Read it from the business account's apple_business_id. Only this business account can send the attachment. Example: b52d6267-2b62-4f8a-8842-0533d0f1dc07
- `idempotency_key` (`string`, required): Required client-supplied deduplication key for this write. Reuse it for retries of the same intent. Successful results replay within the configured idempotency window (three hours by default); selected connected-app writes also replay uncertain-write conflicts. Use a new key only after confirming the prior result and beginning a different action. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `source_url` (`string`, required): HTTPS URL of the file, at most 99,999,999 bytes. Bird downloads it and uploads it to Apple. A non-HTTPS URL is refused with a `422` `AMBEndpointNotHTTPS`. Example: https://media.example.com/receipt.pdf
- `mime_type` (`string`, optional): Media type of the file. Defaults to the type Bird detects from the contents. Example: application/pdf
- `name` (`string`, optional): Display filename. Defaults to the last segment of the source_url path. Example: receipt.pdf

Example input: `{"from":"<from>","idempotency_key":"<idempotency_key>","source_url":"<source_url>"}`

### `bird_amb_business_account_create`

Create Apple Messages for Business Record · Write

Create an Apple Messages for Business record in your workspace.
Returns an object with id, apple_business_id, name, status, status_reason, invitations_enabled, created_at, updated_at, next, account_review_status, finish_setup_url.
Use this to add a new one. Use bird_amb_business_account_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The brand name shown for this business record inside Bird. Example: Acme Retail
- `apple_business_id` (`string`, optional): The Business ID Apple issued for this brand, if you already have it. Supplying it identifies the draft. Submit the completed evidence requirements explicitly when the business is ready for review. Example: b52d6267-2b62-4f8a-8842-0533d0f1dc07
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>"}`

### `bird_amb_business_account_reconnect`

Reconnect Apple Business Account · Write

Restore the local connection. The retained approval and suspension state still determines whether the account can send.
Returns an object with id, apple_business_id, name, status, status_reason, invitations_enabled, created_at, updated_at, next, account_review_status, finish_setup_url.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record to reconnect, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_business_account_submission_create`

Submit Apple Messages for Business Business for Review · Write

Submit an account for review and queues an automated review of its three evidence attachments.
Returns an object with id, business_account_id, apple_business_id, name, readiness_attachment, use_cases_attachment, video_attachment, status, status_reason, decided_by, created_at, next and more.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `readiness_attachment_id` (`string`, required): Uploaded PDF attachment containing the business readiness assessment. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
- `use_cases_attachment_id` (`string`, required): Uploaded PDF attachment describing the proposed customer use cases. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
- `video_attachment_id` (`string`, required): Uploaded MP4 attachment demonstrating the customer experience. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"business_account_id":"<business_account_id>","readiness_attachment_id":"<readiness_attachment_id>","use_cases_attachment_id":"<use_cases_attachment_id>","video_attachment_id":"<video_attachment_id>"}`

### `bird_amb_business_account_update`

Update Apple Messages for Business Record · Write

Change your workspace's Apple Messages for Business record.
Returns an object with id, apple_business_id, name, status, status_reason, invitations_enabled, created_at, updated_at, next, account_review_status, finish_setup_url.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `apple_business_id` (`string`, optional): The Business ID Apple issued for this brand. Accepted only while the account is a draft and connected, including after Bird staff return it to draft. Updating it does not submit the business. Example: b52d6267-2b62-4f8a-8842-0533d0f1dc07
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): The brand name shown for this business record inside Bird. Example: Acme Retail

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_channel_settings_update`

Update Apple Messages for Business Channel Settings · Write

Change the channel settings for your workspace's Apple Messages for Business record.
Returns an object with entry_points, default_locale, brand_name, logo_asset_id.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs business_account_id from bird_amb_business_accounts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `brand_name` (`string`, optional): The brand name shown on the Bird-hosted landing page customers use to connect this business. Example: Acme Retail
- `default_locale` (`string`, optional): The locale used for this business when a conversation reports none of its own, in BCP-47 form. Omit this field to keep the current default, or send null to clear it. Bird converts a configured default to Apple's locale form when sending a message without a conversation locale. Example: en-US
- `entry_points` (`array`, optional): The entry points customers can use to open a conversation with this business. Sending this replaces the entire set; there is no way to add or remove a single entry point without resending the rest. Example: [{"id": "website-footer", "group": "support", "intent": "general-inquiry", "body": "Hi, I have a question about my order."}]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `logo_asset_id` (`string`, optional): The business's logo, as an asset in your media library. Send null to clear it. Example: ast_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_conversation_typing_send`

Send Apple Messages Typing Indicator · Write

Send a typing indicator to the customer's device on this conversation.
Returns an empty response on success (HTTP 204).
Needs conversation_id from bird_amb_conversations_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
- `event` (`string`, required): The typing signal to send. `typing_start` tells the customer's device that an operator is composing a reply. `typing_end` tells it composition stopped without a message following. Apple expects at most one `typing_start` before the reply it precedes; sending it again before that reply is not meaningful and may be dropped. `typing_end`'s behavior against a live conversation is unproven: the legacy platform's implementation was disabled after it caused issues, so treat it as best-effort. Example: typing_start. One of: `typing_start`, `typing_end`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"conversation_id":"<conversation_id>","event":"typing_start"}`

### `bird_amb_conversation_update`

Update Apple Messages Conversation · Write

Update assignment, labels, inbox status, queue, or shared workspace read state, or settles a pending `routing_change`.
Returns an object with inbox_status, recipient, routing, routing_change, last_message, id, business_account_id, status, origin, device_capabilities, supported_content_kinds, locale and more.
Only the fields you pass change; omitted fields keep their current values.
Needs conversation_id from bird_amb_conversations_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
- `assigned_to` (`string`, optional): User to assign this conversation to. Pass a workspace member's user ID, `me` for the signed-in user, or null to unassign it. An API key cannot use `me` and receives a `422` response. Example: me
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbox_status` (`string`, optional): Whether the conversation needs attention in the workspace inbox. Set it to `resolved` when the work is finished. A new inbound message reopens the same conversation. Changing inbox status preserves message history and does not change the channel's permission to send messages or mark messages read. Example: open. One of: `open`, `resolved`.
- `labels` (`array`, optional): Labels from your workspace's label list. On update, this replaces the full set; pass an empty array to clear every label. Labels do not change read state or inbox status. A name matches the workspace's labels in any casing: adding "Urgent" where the workspace has "urgent" applies "urgent", and responses return the workspace's spelling. A name the workspace doesn't have yet becomes a new label. It must contain 1 to 64 characters, with no commas, control characters, or leading or trailing whitespace, and can't take the workspace past its limit of 100 labels. A new label can't use a reserved name: `all`, `archive`, `archived`, `assigned`, `blocked`, `closed`, `deleted`, `draft`, `drafts`, `flagged`, `important`, `inbox`, `junk`, `muted`, `none`, `open`, `outbox`, `pinned`, `read`, `scheduled`, `sent`, `snoozed`, `spam`, `starred`, `trash` or `unread`, in any casing. Example: ["billing", "vip"]
- `queue` (`string`, optional): Queue to move the conversation to, or null to leave it unrouted. Routing rules do not run, and the conversation keeps its group and intent. Moving the queue clears any pending `routing_change`, and cannot be combined with an `apply` decision. Example: billing
- `read` (`string`, optional): Mark received inbound messages with created_at at or before this timestamp as read in the shared workspace inbox. Messages sharing the timestamp are included together. Later arrivals remain unread until another read update. This does not send a read receipt to the customer or change inbox status. Omit to leave read state unchanged. Example: 2026-01-15T09:30:00Z
- `routing_change` (`object`, optional): Settles the conversation's pending `routing_change`. `message_id` names the change you reviewed: the request fails with `409` when the pending change has a different message ID, because a newer customer message replaced it or a teammate already settled it. Either action clears `routing_change`. Example: {"action": "dismiss", "message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg"}

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_amb_message_send`

Send Apple Messages Message · Write

Send an Apple Messages for Business message into a conversation with an Apple customer.
Returns the accepted message with id, status, conversation and content details.
Use this to reply to Apple Messages customers. Use bird_amb_conversations_list to find the conversation and bird_amb_message_get to follow delivery.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Apple business identifier of the brand sending the message. Read it from the business’s apple_business_id. The customer must have opened the conversation with this business. Example: b52d6267-2b62-4f8a-8842-0533d0f1dc07
- `to` (`string`, required): Apple’s opaque customer identifier for this business, available as the conversation’s recipient.opaque_user_id. The conversation must exist and its native status must be open. Example: the-opaque-user-id-from-the-conversation
- `category` (`string`, optional): Free-form reporting label; it does not change sending or suppression policy, for example `order_update`. Omit it to send with the default empty category. Rejected alongside `template`, where the category is derived from the template. Example: order_update
- `group` (`string`, optional): Department identifier for this message. Example: example
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `intent` (`string`, optional): Purpose of this conversation. Example: example
- `interactive` (`object`, optional): Something for the customer to tap, such as quick replies, a list picker, a time picker, a form or a custom iMessage app. Example: {"received_message": {"title": "Pick a delivery slot"}, "list_picker": {"sections": [{"title": "Tomorrow", "items": [{"identifier": "am", "title": "Morning"}]}]}}
- `locale` (`string`, optional): Apple locale identifier, for example en_US. Defaults to the conversation locale.
- `metadata` (`object`, optional): Arbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with `__bird` are reserved. Returned in the send response, message reads and customer message webhooks. Example: {"key": "value"}
- `reference` (`string`, optional): An identifier you want to find this message by, such as an order or ticket number, matched exactly by the message list's `reference` filter. Set it only when you need to search on it, and put any other data in `metadata`. Stored on the message, returned on reads and echoed in webhook payloads. Several messages can share one. Example: INV-1234
- `rich_link` (`object`, optional): A link with a preview card. Example: {"rich_link_data": {"url": "https://example.com/hooks/bird", "title": "example", "assets": {"image": {"source_url": "https://example.com/hooks/bird"}}}}
- `skip_typing` (`boolean`, optional): Send the first part without the typing indicator and one-second pause Bird otherwise shows before it. Set it only after you sent `typing_start` with the conversation typing operation, so the customer already sees typing. A first part that Apple accepts clears that indicator when it arrives. If Bird accepts the message but it fails before then, such as a failed send or a rejection during processing, Bird sends `typing_end` instead. If the request itself returns an error, nothing is sent, so send `typing_end` yourself. When Bird splits the message into several parts, such as text around a link, the parts after the first keep their typing indicator. Example: false
- `source` (`string`, optional): Who this message is sent as. A signed-in session may send as `operator` or `automation`; an API key may send as `api` or `automation`. Omit it to take the default for your credential. Naming a source your credential cannot use is refused with a `422` `AMBMessageSourceNotPermitted`. Example: operator. One of: `operator`, `automation`, `api`.
- `tags` (`array`, optional): Structured `{name, value}` labels for filtering. Maximum 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): Send using a stored template instead of `text`, `rich_link` or `interactive`. The category is derived from the template, so `category` is rejected alongside it. Example: {"id": "amt_01krdgeqcxet5s7t44vh8rt9mg"}
- `text` (`object`, optional): A text message. Alongside `interactive`, it is sent first as its own text bubble, in the same message. Alongside `rich_link`, the card takes the place of the first copy of its URL in `body`, splitting the text around it, or follows the text when `body` does not contain that URL. Later copies of that URL are removed. Example: {"body": "Your order shipped and will arrive tomorrow."}

Example input: `{"from":"<from>","to":"<to>"}`

### `bird_amb_routing_rule_create`

Create Apple Messages for Business Routing Rule · Write

Create a routing rule for one of your Apple Messages for Business brands.
Returns an object with created_at, updated_at, id, business_account_id, match_kind, match_intent_id, match_group_id, queue, precedence, is_default.
Use this to add a new one. Use bird_amb_routing_rule_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `business_account_id` (`string`, required): The Apple Messages for Business brand this rule belongs to. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `match_kind` (`string`, required): What a routing rule matches against the entry point that started the conversation. - `intent` matches on the entry point's intent alone: `match_intent_id` is set and `match_group_id` is null. - `group` matches on the entry point's group alone: `match_group_id` is set and `match_intent_id` is null. - `both` matches only when the entry point carries the given intent and the given group together, so `match_intent_id` and `match_group_id` are both set. There are two match fields rather than one because `both` needs to carry an intent and a group at once. Example: both. One of: `intent`, `group`, `both`.
- `queue` (`string`, required): The queue a matching conversation is filed into. Your console lists whichever values your rules use. Example: billing
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `is_default` (`boolean`, optional): Set to make this the rule that catches a conversation matching nothing else. A business can have only one; creating a second while one exists returns a `409`. Example: false
- `match_group_id` (`string`, optional): The entry point group to match, as sent in Apple's `groupID`. Required when `match_kind` is `group` or `both`, and rejected when it is `intent`. Example: support
- `match_intent_id` (`string`, optional): The entry point intent to match, as sent in Apple's `intentID`. Required when `match_kind` is `intent` or `both`, and rejected when it is `group`. Example: order_status
- `precedence` (`integer`, optional): Evaluation order among this business's rules. The highest-precedence rule a conversation matches wins. Omit it to default to 0. Example: 10

Example input: `{"business_account_id":"<business_account_id>","match_kind":"intent","queue":"<queue>"}`

### `bird_amb_routing_rule_update`

Update Apple Messages for Business Routing Rule · Write

Change a routing rule's business, match, queue, precedence, or default status.
Returns an object with created_at, updated_at, id, business_account_id, match_kind, match_intent_id, match_group_id, queue, precedence, is_default.
Only the fields you pass change; omitted fields keep their current values.
Needs routing_rule_id from bird_amb_routing_rules_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `routing_rule_id` (`string`, required): ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg
- `business_account_id` (`string`, optional): Move this rule to another Apple Messages for Business brand in the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `is_default` (`boolean`, optional): Set to true to make this the rule that catches a conversation matching nothing else, or to false to stop it from being the default. Example: false
- `match_group_id` (`string`, optional): The entry point group to match, as sent in Apple's `groupID`. Requires `match_kind`: required when it is `group` or `both`, and rejected when it is `intent`. Example: support
- `match_intent_id` (`string`, optional): The entry point intent to match, as sent in Apple's `intentID`. Requires `match_kind`: required when it is `intent` or `both`, and rejected when it is `group`. Example: order_status
- `match_kind` (`string`, optional): Replace what this rule matches. Send it with the ids the new kind requires, validated as on create. A stored id the new kind does not use is cleared. Example: both. One of: `intent`, `group`, `both`.
- `precedence` (`integer`, optional): Change this rule's evaluation order among the business's other rules. Example: 20
- `queue` (`string`, optional): Change the queue this rule files a matching conversation into. Example: billing

Example input: `{"routing_rule_id":"<routing_rule_id>"}`

### `bird_amb_suppression_create`

Create Apple Messages for Business Suppression · Write

Manually opens a suppression episode for a address, blocking every outbound path to it: operator and automated replies, API sends, typing indicators, and invitations.
Returns an object with id, business_account_id, address, address_type, reason, origin, applies_to, source_message_id, source_event_id, source_end_message_id, effective_at, created_at and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `address` (`string`, required): The phone number or opaque identifier to suppress. For a phone number, supply canonical E.164 with a leading plus sign. Example: +15551234567
- `address_type` (`string`, required): What kind of value `address` holds. - `phone_number` means `address` is the customer's phone number. Apple's CloseSession event carries a phone number rather than an opaque identifier, so a suppression opened by a close on a conversation identified by phone number takes this kind. - `opaque_user_id` means `address` is the opaque identifier Apple assigns to the customer's conversation with the business, stable across a close and a later re-initiation. Example: phone_number. One of: `phone_number`, `opaque_user_id`.
- `business_account_id` (`string`, optional): Limit this manual block to one account. Omit to cover the same address across the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"address":"<address>","address_type":"phone_number"}`

### `bird_asset_folder_create`

Create Folder in the Media Library · Write

Create a folder in the workspace's media library.
Returns an object with created_at, updated_at, id, name, parent_id, path.
Use this to add a new one. Use bird_asset_folder_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The folder's display name. Must be unique among folders sharing the same parent, compared without regard to case. Cannot contain `/`. Example: sk-test-sample
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `parent_id` (`string`, optional): The folder to create this one in. Omit it, or send null, to create the folder at the top level of the library. Example: asf_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"name":"<name>"}`

### `bird_asset_folder_update`

Rename or Move a Media-library Folder · Write

Rename or move a media-library folder. Renames a folder, moves it, or both. Send `parent_id` to move the folder into another folder, or `null` to move it to the top level.
Returns an object with created_at, updated_at, id, name, parent_id, path.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs folder_id from bird_asset_folders_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `folder_id` (`string`, required): ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): The folder's display name. Must be unique among folders sharing the same parent, compared without regard to case. Cannot contain `/`. Example: sk-test-sample
- `parent_id` (`string`, optional): The folder to move this one into. Send null to move it to the top level of the library. A folder cannot be moved into itself or into one of its own subfolders. Example: asf_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"folder_id":"<folder_id>"}`

### `bird_asset_update`

Update Asset Metadata or Folder Placement · Write

Update asset metadata or folder placement. Renames an asset, sets its default alternative text, or moves it to a folder.
Returns an object with created_at, updated_at, id, url, thumbnail_url, name, content_type, kind, size_bytes, width, height, alt_text and more.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs asset_id from bird_assets_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `asset_id` (`string`, required): ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
- `alt_text` (`string`, optional): Default alternative text describing the image. Send null to clear it. Example: Hello from Bird
- `folder_id` (`string`, optional): The folder to file the asset in. Send null to move it to the top level of the library. Moving an asset never changes its URL. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): The asset's display name. Example: sk-test-sample

Example input: `{"asset_id":"<asset_id>"}`

### `bird_asset_upload_session_browser_open`

Open Browser Fallback for a Media Upload · Write

Offer an existing upload session to a signed-in person with asset write access in its workspace.
Returns an object with session, browser_url, next.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `upload_id` (`string`, required): ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"upload_id":"<upload_id>"}`

### `bird_asset_upload_session_cancel`

Cancel Media-library Upload · Write

Cancel an unfinished upload. The temporary file is reclaimed after issued upload instructions expire.
Returns an object with id, state, expires_at, name, alt_text, folder_id, file, result, last_error, next, asset.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `upload_id` (`string`, required): ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"upload_id":"<upload_id>"}`

### `bird_asset_upload_session_complete`

Complete Media-library Upload · Write

Verify the uploaded file and publishes a media-library asset at a permanent public URL.
Returns an object with id, state, expires_at, name, alt_text, folder_id, file, result, last_error, next, asset.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `upload_id` (`string`, required): ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"upload_id":"<upload_id>"}`

### `bird_asset_upload_session_create`

Create Media-library Upload Session · Write

Create or recovers a session. An upload instruction is omitted when the session is no longer pending or another instruction was issued within the last 30 seconds; follow the returned state and next steps.
Returns an object with id, state, expires_at, name, alt_text, folder_id, file, result, last_error, next, upload.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `client_reference` (`string`, required): Caller-generated UUID for this upload intent. Retries with identical input recover the same session while its receipt is retained. Example: 4ca4145c-782a-4d03-bc80-a27e3e431780
- `file` (`object`, required): Exact properties of the active source file. Calculate size and SHA-256 from its bytes before creating a session or preparing a browser-selected source. Images allow up to 5,242,880 bytes; other supported media allow up to 25,000,000 bytes. Example: {"filename": "invoice.pdf", "content_type": "application/pdf", "size_bytes": 1024, "sha256": "4e2090a479f7ce6b17ad31f991988f12571bcafbd4a441cc4063644fc1400ae0"}
- `alt_text` (`string`, optional): Default alternative text for the asset. Example: Hello from Bird
- `folder_id` (`string`, optional): Destination folder in this workspace. Omit it to use the library root. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): Display name. Omitted or blank names default to the sanitized filename. Example: sk-test-sample

Example input: `{"client_reference":"<client_reference>","file":{"filename":"invoice.pdf","content_type":"application/pdf","size_bytes":1024,"sha256":"4e2090a479f7ce6b17ad31f991988f12571bcafbd4a441cc4063644fc1400ae0"}}`

### `bird_asset_upload_session_prepare`

Refresh Media-library Upload Instruction · Write

Refresh the temporary upload instruction for a pending session.
Returns an object with id, state, expires_at, name, alt_text, folder_id, file, result, last_error, next, upload.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `upload_id` (`string`, required): ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"upload_id":"<upload_id>"}`

### `bird_audience_contacts_add`

Assign Contacts to an Audience · Write

Add up to 1,000 contacts to an audience. Adding is idempotent: contacts that are already members are left in place and keep their original join time.
Returns an empty response on success (HTTP 204).
Needs audience_id from bird_audiences_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `audience_id` (`string`, required): ID of the audience to add contacts to. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `contact_ids` (`array`, required): Contacts to add to the audience. Adding a contact that is already a member has no effect and keeps its original join time. Duplicate IDs in the list are collapsed. If any ID does not exist in the workspace, the whole request fails with a validation error and no contacts are added. Example: ["con_01krdgeqcxet5s7t44vh8rt9mg"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"audience_id":"<audience_id>","contact_ids":["con_01krdgeqcxet5s7t44vh8rt9mg"]}`

### `bird_audience_contacts_remove`

Unassign Contacts from an Audience · Write

Remove up to 1,000 contacts from an audience. Contacts that are not members are skipped.
Returns an empty response on success (HTTP 204).
Needs audience_id from bird_audiences_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `audience_id` (`string`, required): ID of the audience to remove contacts from. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `contact_ids` (`array`, required): Contacts to remove from the audience. Removing a contact that is not a member has no effect. Duplicate IDs in the list are collapsed. If any ID does not exist in the workspace, the whole request fails with a validation error and no memberships are removed. Example: ["con_01krdgeqcxet5s7t44vh8rt9mg"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"audience_id":"<audience_id>","contact_ids":["con_01krdgeqcxet5s7t44vh8rt9mg"]}`

### `bird_audience_create`

Create Audience · Write

Create an audience in the workspace. New audiences start empty: add members with Add contacts to an audience or through Create or update contacts in bulk.
Returns an object with id, name, description, type, created_at, updated_at.
Use this to add a new one. Use bird_audience_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Display name for the audience. Example: sk-test-sample
- `description` (`string`, optional): Longer description of who this audience is. Example: Created by the Scalekit connector
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `type` (`string`, optional): How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts. Example: static. One of: `static`.

Example input: `{"name":"<name>"}`

### `bird_audience_update`

Update Audience · Write

Update an audience's name or description. Omitted fields are left unchanged; set `description` to `null` to clear it.
Returns an object with id, name, description, type, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs audience_id from bird_audiences_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `audience_id` (`string`, required): ID of the audience to update. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `description` (`string`, optional): Longer description of who this audience is. Set to null to clear. Example: Created by the Scalekit connector
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): New display name for the audience. Omit to keep the current name. The name cannot be cleared, and a whitespace-only value returns a validation error. Example: sk-test-sample

Example input: `{"audience_id":"<audience_id>"}`

### `bird_compliance_identity_create`

Create Identity · Write

Create an identity. Stores a party you register on behalf of, so its business details can prefill the countries you register in next.
Returns an object with id, name, answers, created_at, updated_at.
Use this to add a new one. Use bird_compliance_identity_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): What you call this party. Yours to choose; it is never sent to a carrier. Example: Goldcrest Communications SAS
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>"}`

### `bird_compliance_identity_update`

Update Identity Name · Write

Update an identity name. Renames the party. Only the name is yours to set. The business details are filled in from your registrations: each single-value answer you file about the party is written back onto it, whatever the verdict.
Returns an object with id, name, answers, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs identity_id from bird_compliance_identities_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `identity_id` (`string`, required): Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
- `name` (`string`, required): What you call this party. Yours to choose; it is never sent to a carrier. Example: Goldcrest Communications SAS
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"identity_id":"<identity_id>","name":"<name>"}`

### `bird_compliance_submission_create`

Create Registration Submission · Write

Submit every answer at once. Because submissions have no multi-call draft, send a complete set; anything missing or malformed comes back named field by field.
Returns an object with next, id, subject_kind, subject_id, program, country_code, identity_id, satisfied, items, created_at, updated_at, closed_at and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `answers` (`array`, required): Every answer at once. Because submissions have no multi-call draft, send a complete set. Anything missing or malformed comes back named. A requirement the named party already answers may be left out; one you send anyway wins over what the party holds. Example: [{"key": "business_registration_number", "value": "90012768"}]
- `country_code` (`string`, required): ISO 3166-1 alpha-2 country code. Example: US
- `program` (`string`, required): The registration program a country runs. Available programs depend on the registered resource. An SMS sender registers under an authority regime (`alpha` or `numeric`). A phone number proves ownership under its number type (`mobile`, `local`, `national`, `short_code`, `short_code_fteu`, or `toll_free`), matching the values of `NumberType`. An identity registers your business itself under `business`, internationally: its coordinate's country is always `ZZ`. A value is therefore only meaningful alongside the subject it describes. More are added as coverage grows, so treat this as an open set rather than a fixed list. Example: example
- `subject_id` (`string`, required): What is being registered. For `sms_sender` this is the `scr_` id returned when you register a sender for a country. For `number` it is the `nda_` id of a dedicated number you hold, as returned by `GET /v1/numbers`. For `number_emergency`, it is the `nes_` ID of the emergency service being registered. A shared short code (`nal_`) is not accepted: it is shared, so its ownership paperwork is not yours to file. For `identity` it is the `cid_` id of the party being registered, picked from the parties your workspace holds, as returned by `GET /v1/compliance/identities`. Example: scr_01krdgeqcxet5s7t44vh8rt9mg
- `subject_kind` (`string`, required): What is being registered. - `sms_sender`: a sender registered to send to one country. - `number`: a phone number you hold that needs ownership paperwork before it can carry traffic. - `number_emergency`: emergency calling on a dedicated number you hold. The subject is created by turning emergency calling on for the number. - `identity`: a business you operate as, registered once and reused by later registrations that name it. Example: sms_sender. One of: `sms_sender`, `number`, `number_emergency`, `identity`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `identity` (`object`, optional): Registers this on behalf of a party you have not stored yet, creating it as part of the submission so you do not need a separate call. Exclusive with `identity_id`. Each time you send this you get a new party. Single-value identity answers filed for one are reused by registrations naming the same party. Documents and lists are supplied separately for each registration. Send this once and use the `identity_id` from the response for the countries that follow. Example: {"name": "Goldcrest Communications SAS"}
- `identity_id` (`string`, optional): An existing party this registration is for. It fills in the business details you left out from what that party already holds, and each single-value answer you file about the party is written back onto it for next time, whatever the verdict. Documents and multi-value answers are asked fresh each time. Send this or `identity`, never both. An id belonging to another organization is rejected; nothing is created here. When `subject_kind` is `identity`, send neither: `subject_id` already names the party. Example: cid_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"answers":[{"key":"business_registration_number","value":"90012768"}],"country_code":"<country_code>","program":"<program>","subject_id":"<subject_id>","subject_kind":"sms_sender"}`

### `bird_compliance_submission_resupply`

Update Compliance Answers · Write

Replace rejected, expired, or missing answers on an existing submission.
Returns an object with next, id, subject_kind, subject_id, program, country_code, identity_id, satisfied, items, created_at, updated_at, closed_at and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `answers` (`array`, required): Every answer for the submission at once, one object per requirement key, as listed by bird_compliance_requirements_get. Each answer carries exactly one of value, values, attachment_id or attachment_ids. Example: [{"key": "business_registration_number", "value": "90012768"}]
- `submission_id` (`string`, required): Submission ID. Example: csb_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"answers":[{"key":"business_registration_number","value":"90012768"}],"submission_id":"<submission_id>"}`

### `bird_contact_create`

Create Contact · Write

Create a contact in the workspace, identified by an email address, a phone number, or both; at least one is required.
Returns an object with id, email, phone_number, first_name, last_name, external_id, data, audiences, created_at, updated_at.
Use this to add a new one. Use bird_contact_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `data` (`object`, optional): Custom property values for this contact. Each key must be a registered contact property, including an archived one. Each value must match the property's declared type: string, number, boolean, or RFC 3339 datetime. Strings can contain up to `500` characters, and a `null` value is ignored. An unregistered key returns a validation error. The serialized data is limited to 2 KB. Example: {"key": "value"}
- `email` (`string`, optional): The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace. Supply an email address, a phone number, or both. Example: jane@example.com
- `external_id` (`string`, optional): Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `first_name` (`string`, optional): The contact's first name. Example: Jane
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `last_name` (`string`, optional): The contact's last name. Example: Doe
- `phone_number` (`string`, optional): The contact's phone number in E.164 format, including the leading `+` and country code. Spaces and punctuation are accepted and stripped; the number is stored in its canonical form, which may differ from what you send, and is unique within the workspace. An empty string is treated as if the field were omitted. Supply an email address, a phone number, or both. Example: +31612345678

Example input: `{}`

### `bird_contact_property_archive`

Archive Contact Property · Write

Archiving is how you remove a contact property. Bird keeps its values so you can restore it with Unarchive.
Returns an object with id, key, type, fallback_value, archived, created_at, updated_at.
Needs property_id from bird_contact_properties_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `property_id` (`string`, required): ID of the contact property to archive. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"property_id":"<property_id>"}`

### `bird_contact_property_create`

Create Contact Property · Write

Create a contact property. Defines a custom property that contacts in the workspace can carry.
Returns an object with id, key, type, fallback_value, archived, created_at, updated_at.
Use this to add a new one. Use bird_contact_property_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `key` (`string`, required): The property key, used as the key in contact data and as the attribute in the `bird.contact.` broadcast template variable. Lowercase letters, digits, and underscores, starting with a letter. Cannot be changed after creation. Example: sk_test_key
- `type` (`string`, required): The value type every contact must use for a property. Cannot be changed after creation. `datetime` values are RFC 3339 timestamps with an explicit offset. Examples include `2024-01-15T09:30:00Z` and `2024-01-15T11:30:00+02:00`. A bare date or a time with no offset is rejected. The value is normalized to UTC with second precision on write, so `2024-01-15T11:30:00+02:00` is stored and returned as `2024-01-15T09:30:00Z`, and any fractional seconds are dropped. One of: `string`, `number`, `boolean`, `datetime`.
- `fallback_value` (`string`, optional): Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, boolean, or RFC 3339 datetime string matching the declared type (strings up to `500` characters); a value of another type returns a validation error. Omit or set to `null` for no fallback. Example: sk-test-value
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"key":"<key>","type":"string"}`

### `bird_contact_property_unarchive`

Unarchive Contact Property · Write

Restore an archived contact property with its stored values.
Returns an object with id, key, type, fallback_value, archived, created_at, updated_at.
Needs property_id from bird_contact_properties_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `property_id` (`string`, required): ID of the contact property to unarchive. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"property_id":"<property_id>"}`

### `bird_contact_property_update`

Update Contact Property · Write

Update a contact property's fallback value, the only mutable field.
Returns an object with id, key, type, fallback_value, archived, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs property_id from bird_contact_properties_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `property_id` (`string`, required): ID of the contact property to update. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
- `fallback_value` (`string`, optional): Default used when a contact has no value for this property and the template does not supply an inline fallback. A string, number, boolean, or RFC 3339 datetime string matching the declared type (strings up to `500` characters); a value of another type returns a validation error. Set to `null` to remove the fallback; omit to leave it unchanged. Example: sk-test-value
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"property_id":"<property_id>"}`

### `bird_contact_update`

Update Contact · Write

Update a contact. Supplied fields are changed and omitted fields are left unchanged; set `first_name`, `last_name`, or `external_id` to `null` to clear them.
Returns an object with id, email, phone_number, first_name, last_name, external_id, data, audiences, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs contact_id from bird_contacts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contact_id` (`string`, required): ID of the contact to update. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `data` (`object`, optional): Custom property values to merge into the contact's existing data. Supplied keys are set, keys with a `null` value are removed, and omitted keys remain unchanged. Each key must be a registered contact property, including an archived one. Each value must match the property's declared type: string, number, boolean, or RFC 3339 datetime. Strings can contain up to `500` characters. An unregistered key returns a validation error. The serialized result is limited to 2 KB. Example: {"key": "value"}
- `email` (`string`, optional): New email address for the contact. Trimmed and lowercased before it is stored and checked for uniqueness. Must not be in use by another contact in the workspace. Omit to keep the current address; set to `null` to remove it, as long as the contact keeps at least one identifier. Example: jane@example.com
- `external_id` (`string`, optional): Your own identifier for this contact. Unique within the workspace when set. Set to `null` to clear. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `first_name` (`string`, optional): The contact's first name. Set to `null` to clear. Example: Jane
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `last_name` (`string`, optional): The contact's last name. Set to `null` to clear. Example: Doe
- `phone_number` (`string`, optional): New phone number for the contact, in E.164 format with the leading `+` and country code. Spaces and punctuation are accepted and stripped. Stored in its canonical form, which may differ from what you send, and unique within the workspace. Omit to keep the current number; set to `null` to remove it, as long as the contact keeps at least one identifier. An empty string behaves as `null`. Example: +14155550123

Example input: `{"contact_id":"<contact_id>"}`

### `bird_contacts_batch_create`

Create or Update Contacts in Bulk · Write

Create or updates up to 1,000 contacts in one request.
Returns data, an array of items with entry, matched_on, status, contact_id, error.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contacts` (`array`, required): Contacts to create or update, matched automatically against every identifier an entry supplies. Existing contacts are updated with the fields each entry supplies; omitted fields keep their stored values, so an entry can set fields but never clear them. Unmatched entries create contacts. Example: [{"email": "jane@example.com", "phone_number": "+14155550123"}]
- `audience_ids` (`array`, optional): Audiences every contact in this request is added to. Contacts that are already members are left in place. Every listed audience must exist, or the whole request fails with a validation error and nothing is written. Example: ["adn_01krdgeqcxet5s7t44vh8rt9mg"]
- `data_mode` (`string`, optional): How a supplied `data` object is applied to an existing contact. The default `merge` mode adds the supplied keys to the contact's stored custom values. A key with a `null` value deletes that key. The `replace` mode overwrites the whole stored `data` map with the supplied map. In both modes a contact that omits `data` keeps its stored values unchanged, so an import that touches one attribute never wipes the others. Example: merge. One of: `merge`, `replace`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `match_on` (`string`, optional): Optional field used to match every entry to an existing contact. Every entry must include this field when set. When omitted, each entry is matched against all identifiers it supplies. No match creates a contact, one match updates it, and identifiers that match multiple contacts return an error naming each contact. Example: email. One of: `email`, `phone_number`, `external_id`.

Example input: `{"contacts":[{"email":"jane@example.com","phone_number":"+14155550123"}]}`

### `bird_email_broadcast_cancel`

Cancel Email Broadcast · Write

Cancel a broadcast that is scheduled, accepted, sending, waiting for funds, or paused.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_create`

Create Email Broadcast · Write

Create a broadcast for a stored audience. The default is an editable draft.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Use this to add a new one. Use bird_email_broadcast_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `audience_id` (`string`, optional): The audience this broadcast sends to. We take the audience's contacts as they stand when the send starts and drop any suppressed addresses, and what is left is who gets the email. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): What kind of email this is. A broadcast sets this itself rather than taking it from its template, and it decides two things: which suppressions apply, and whether we add an unsubscribe header. `marketing`, the default, is held back from every suppressed address and has the one-click unsubscribe headers. `transactional` still goes to addresses suppressed for a complaint or an unsubscribe, and has no unsubscribe header. Only use `transactional` for genuine operational mail such as a terms-of-service update or a service outage notice. Marketing content sent this way still reaches people who have already unsubscribed from you. Example: marketing. One of: `marketing`, `transactional`.
- `from` (`object`, optional): The address the broadcast sends from. Give it as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. The domain has to be one this workspace has verified. Example: Jane Doe <jane@acme.com>
- `headers` (`object`, optional): Custom email headers to set on the broadcast, as name and value pairs. Up to 25 of them, each value up to 998 characters. Two names are ours and cannot be set here: `List-Unsubscribe` and `List-Unsubscribe-Post` are dropped if you send them, whatever the category. We add the one-click unsubscribe pair to a marketing broadcast ourselves, and a transactional broadcast has neither header. Example: {"X-Campaign": "spring-launch"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ip_pool_id` (`string`, optional): The IP pool to send this broadcast from. Pass a pool ID, or `ipp_shared` to send through the shared pool on purpose. Leave it out and the broadcast uses your organization's default pool. A pool we do not recognize, or one with no IPs available to send from, is refused with a `422`. Example: ipp_01jbx7k3m9p2q5r8s4t6v0w1yz
- `metadata` (`object`, optional): Any JSON you want to keep on the broadcast. We store it, hand it back when you read the broadcast, and include it in webhook payloads, and you can break stats down by a path inside it such as `metadata.order_id`. It can be up to 2 KB once serialized. Example: {"key": "value"}
- `reply_to` (`array`, optional): Where replies to this broadcast should go. Give each address as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. You can list more than one. Example: ["Jane Doe <jane@acme.com>"]
- `scheduled_at` (`string`, optional): When to send the broadcast. It has to be at least 30 seconds and at most 365 days from now. It requires `send` to be true, so a `scheduled_at` on its own is refused rather than saved on the draft. Example: 2026-01-15T09:30:00Z
- `send` (`boolean`, optional): Whether to send the broadcast as soon as it is created. Set it to true and the broadcast goes out immediately, or at `scheduled_at` if you set one. Leave it false, which is the default, and you get a draft you can update and send later. Example: false
- `tags` (`array`, optional): Labels on this broadcast, each one a `name` and a `value`, up to 20 of them. You can filter the broadcast list by a tag, break your stats down by one, and read them back off webhook payloads. Use tags for anything you want to find broadcasts by later, and `metadata` for data you only want handed back to you. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): The template the broadcast sends, and the language to send it in. You can leave it out on a draft, but a broadcast cannot send without one. The template's published version is fixed when the broadcast is prepared for sending, and each recipient's contact properties are filled into the content as the email goes out. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg"}
- `track_clicks` (`boolean`, optional): Whether to track link clicks for this broadcast. Example: true
- `track_opens` (`boolean`, optional): Whether to track opens for this broadcast. Example: true

Example input: `{}`

### `bird_email_broadcast_resume`

Resume Email Broadcast · Write

Resume a broadcast. Continues a `paused` broadcast using its saved template references and recipient list, skipping recipients already sent to and applying current consent and suppression checks for its saved category.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `confirm` (`boolean`, optional): Acknowledgment that the message reaches the remaining recipients later than intended. It is required to resume a broadcast that started sending at least 24 hours ago. Before setting it, read the broadcast's `started_at` and have a reviewer with `email_management:read` check its pinned template version using `template.id` and `template.version_id`. Workspace versions retain the original content. Built-in template lookups (`scope: system`) show current catalogue content. Broadcasts with frozen content keep it, but older broadcasts can read the catalogue again when resumed. Neither a current lookup nor an earlier message alone proves what remaining recipients will receive. Leave the broadcast paused unless you can verify that content. Ask an authorized teammate if you lack that permission. It does not skip the funds or concurrent-broadcast checks. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_send`

Send Email Broadcast · Write

Send a draft or scheduled broadcast, either immediately or at `scheduled_at`.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `scheduled_at` (`string`, optional): When to send the broadcast. It has to be at least 30 seconds and at most 365 days from now. Leave it out to send straight away. Example: 2026-01-15T09:30:00Z

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_broadcast_test_send`

Send Email Rendered Broadcast Test · Write

Supply the same changes, contact and fingerprint as a new preview to send the exact rendered content to an authorized current organization member with workspace access.
Returns an object with id, from, to, cc, bcc, subject, subject_recipient_id, category, reply_to, status, accepted_count, processed_count and more.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, required): Required key for one logical broadcast test send, scoped to the workspace, the authenticated caller and this operation. Reuse the same key and the exact same request when retrying. - A confirmed `202` response replays unchanged for the same key and request within the configured window, 3 hours by default. Authorization is checked again on every retry; on an email test, so is the destination's member access. - `409 request_in_progress` (E01004) or `503 IdempotencyUnavailable` (E01033): retry with backoff using the same key. Switching keys can send another test. - `409 idempotency_key_reuse` (E01005): the key was used for a different request or broadcast. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `preview_fingerprint` (`string`, required): The `preview_fingerprint` returned by the preview whose content you are sending. Example: fingerprint_from_matching_preview
- `to` (`string`, required): The email address of a current organization member with access to this workspace. Example: member@example.com
- `contact_id` (`string`, optional): The workspace contact whose values fill `bird.contact.` inputs. Required when the template or envelope reads contact data. Present values are used as they are, and a property's fallback applies only when the contact has no value for it. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `from` (`object`, optional): Replaces the sender for this request. Give it as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. Example: Jane Doe <jane@acme.com>
- `headers` (`object`, optional): Replaces the custom headers for this request rather than adding to them. Up to 25 of them, each value up to 998 characters. The header rules for updating a broadcast apply. Example: {"X-Campaign": "spring-launch"}
- `reply_to` (`array`, optional): Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
- `template` (`object`, optional): Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}

Example input: `{"broadcast_id":"<broadcast_id>","idempotency_key":"<idempotency_key>","preview_fingerprint":"<preview_fingerprint>","to":"<to>"}`

### `bird_email_broadcast_update`

Update Email Broadcast · Write

Update a draft or scheduled broadcast. A field you supply in the request is changed.
Returns an object with id, display_label, from, audience_id, template, html_bytes, text_bytes, category, ip_pool_id, reply_to, headers, status and more.
Only the fields you pass change; omitted fields keep their current values.
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `audience_id` (`string`, optional): The audience this broadcast sends to. We take the audience's contacts as they stand when the send starts and drop any suppressed addresses, and what is left is who gets the email. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): What kind of email this is. It decides two things: which suppressions apply, and whether we add an unsubscribe header. `marketing` is held back from every suppressed address and has the one-click unsubscribe headers. `transactional` still goes to addresses suppressed for a complaint or an unsubscribe, and has no unsubscribe header. Only use `transactional` for genuine operational mail such as a terms-of-service update or a service outage notice. Marketing content sent this way reaches people who have already unsubscribed from you. Example: marketing. One of: `marketing`, `transactional`.
- `from` (`object`, optional): The address the broadcast sends from. Give it as a plain address, as `Jane ` to include a display name, or as an object with an address and a name. The domain has to be one this workspace has verified. Example: Jane Doe <jane@acme.com>
- `headers` (`object`, optional): Custom email headers to set on the broadcast, as name and value pairs. What you send replaces the headers the draft already had rather than adding to them. Up to 25 of them, each value up to 998 characters. Two names are ours and cannot be set here: `List-Unsubscribe` and `List-Unsubscribe-Post` are dropped if you send them, whatever the category. We add the one-click unsubscribe pair to a marketing broadcast ourselves, and a transactional broadcast has neither header. Example: {"X-Campaign": "spring-launch"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ip_pool_id` (`string`, optional): The IP pool to send this broadcast from. Pass a pool ID, or `ipp_shared` to send through the shared pool on purpose. Set it to null to fall back to your organization's default pool. Example: ipp_01jbx7k3m9p2q5r8s4t6v0w1yz
- `metadata` (`object`, optional): Any JSON you want to keep on the broadcast, up to 2 KB once serialized. What you send replaces the metadata the draft already had rather than merging into it. Example: {"key": "value"}
- `reply_to` (`array`, optional): Where replies to this broadcast should go. Set this to null to remove the addresses already set. Example: ["Jane Doe <jane@acme.com>"]
- `tags` (`array`, optional): Labels on this broadcast, each one a `name` and a `value`, that you can filter and search broadcasts by. What you send replaces the tags the draft already had rather than adding to them. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): The template the broadcast sends, and the language to send it in, each changeable on its own. Set this to null to take the template and its language off a draft, or leave it out to keep the template, language and fixed version already set. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}
- `track_clicks` (`boolean`, optional): Whether to track link clicks for this broadcast. Example: false
- `track_opens` (`boolean`, optional): Whether to track opens for this broadcast. Example: false

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_competitive_watchlist_brand_add`

Add Email Competitor Brand to the Watchlist · Write

Add a brand to the workspace's watchlist so its figures appear next to your own.
Returns an object with created_at, updated_at, id, brand_id, name, industry, sending_domains.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `brand_id` (`string`, required): Identifier of the brand in the panel's catalog, used to add it to the watchlist. It is a string for the same reason a campaign id is: the values are wide enough that a client storing every number as a floating point value would round them, and a rounded identifier matches no brand at all. Example: 81531
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"brand_id":"<brand_id>"}`

### `bird_email_domain_create`

Create Sending Domain · Write

Create a sending domain. Registers a new sending domain and returns the DNS records to publish for it.
Returns an object with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, receiving, dns_records and more.
Use this to add a new one. Use bird_email_domain_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain` (`string`, required): The domain you send from: the domain of your `from` addresses. Use a dedicated subdomain (for example, `mail.acme.com`) rather than your registered domain so sending reputation stays separate from other services on the domain. Example: mail.acme.com
- `dkim` (`object`, optional): DKIM signing configuration. Example: {"mode": "txt"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `return_path` (`object`, optional): Return-path (bounce) domain configuration. The return-path domain receives bounce and complaint notifications for mail sent from this domain and is what mailbox providers check for SPF. Provide only the name part; we add the sending domain automatically. Example: {"name": "bounce"}
- `settings` (`object`, optional): Per-domain behavior toggles. Changes apply immediately to new sends. Example: {"click_tracking": false, "open_tracking": false}
- `tracking` (`object`, optional): Tracking domain configuration for branded open and click tracking URLs. Provide only the name part; we add the sending domain automatically. A domain created with no tracking configuration defaults to `links`. Tracked links are served over HTTPS after the tracking record verifies. Example: {"name": "links"}

Example input: `{"domain":"<domain>"}`

### `bird_email_domain_dns_records_share`

Share Domain's DNS Records by Email · Write

Email the domain's current DNS records to up to three recipients, so a colleague who manages your DNS can publish them without an account.
Returns an empty response on success (HTTP 204).
Needs domain_id from bird_email_domains_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain_id` (`string`, required): ID of the domain whose DNS records to share. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `emails` (`array`, required): Email recipients for the domain's current DNS records. The first address is the direct recipient and the rest are copied on the same email; duplicates are ignored. Any invalid address fails the whole request with `422`. Example: ["alice@example.com"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"domain_id":"<domain_id>","emails":["alice@example.com"]}`

### `bird_email_domain_update`

Update Sending Domain · Write

Update settings and configuration on a sending domain.
Returns an object with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, receiving, dns_records and more.
Only the fields you pass change; omitted fields keep their current values.
Needs domain_id from bird_email_domains_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain_id` (`string`, required): ID of the domain to update. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `default_ip_pool_id` (`string`, optional): Default IP pool for this domain in this workspace. Used only when a send omits `ip_pool_id`; an explicit send option takes precedence. The pool must belong to the same organization. Set to `null` to use normal organization routing. Example: ipp_01krdgeqcxet5s7t44vh8rt9mg
- `dkim` (`object`, optional): Change how the DKIM key is published. The current key keeps signing until the new configuration verifies, so mail is never sent unsigned during the transition. Example: {"mode": "txt"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound` (`object`, optional): Enable or disable receiving on this domain. Enabling claims the domain for inbound and moves `capabilities.inbound.status` from `not_configured` to `pending`, then `verified` once the MX records resolve to us. The MX records to publish are always present under `dns_records` (`purpose: inbound_mx`) as a regional reference. Their presence does not mean receiving is enabled; enable the domain whenever `capabilities.inbound.status` is `not_configured`. Enabling requires the domain's DKIM to be verified first. A fresh enable on a domain whose DKIM is not verified returns `422` with `E05019` and claims nothing. A domain already receiving inbound for another organization returns `422` with `E05018`. Example: {"enabled": true}
- `return_path` (`object`, optional): Change the return-path name part. Cannot be removed: the return-path is required for sending. Example: {"name": "send"}
- `settings` (`object`, optional): Per-domain behavior toggles. Changes apply immediately to new sends. Example: {"click_tracking": false, "open_tracking": false}
- `tracking` (`object`, optional): Set or change the tracking name part, or remove tracking by passing `null`. Removal requires `click_tracking` and `open_tracking` to be disabled first, and returns `409` otherwise. After removal, links in previously sent email keep resolving while the tracking records are reported as `deprecated`. Example: {"name": "links"}

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_domain_verify`

Verify Domain · Write

Verify a domain. Runs a fresh DNS check across the domain's records (DKIM, return path, DMARC, tracking, inbound MX, and any staged changes) and returns the updated domain.
Returns an object with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, receiving, dns_records and more.
Needs domain_id from bird_email_domains_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `domain_id` (`string`, required): ID of the domain to verify. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_inbound_address_create`

Create Email Inbound Address · Write

Create a new inbound address. Forward a real mailbox to the returned `address`, and every message sent there arrives as a received email.
Returns an object with id, address, label, created_at, updated_at.
Use this to add a new one. Use bird_email_inbound_address_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `label` (`string`, optional): Your own label for this address, typically the source mailbox it maps to. Example: Support mailbox

Example input: `{}`

### `bird_email_inbound_address_update`

Update Email Inbound Address · Write

Update the label on an inbound address. The address itself is fixed and cannot be changed.
Returns an object with id, address, label, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs inbound_address_id from bird_email_inbound_addresses_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `inbound_address_id` (`string`, required): Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `label` (`string`, optional): Your own label for this address, typically the source mailbox it maps to. Send `null` to clear it. Omit the field to leave it unchanged. Example: Support mailbox

Example input: `{"inbound_address_id":"<inbound_address_id>"}`

### `bird_email_inbound_route_create`

Create Email Inbound Route · Write

Create a routing rule that delivers matching inbound mail on one of your domains to a mailbox, or drops it.
Returns an object with id, domain, match_type, match_value, action, target_mailbox_id, priority, enabled, created_at, updated_at.
Use this to add a new one. Use bird_email_inbound_route_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `action` (`string`, required): What happens to matching mail. `deliver_to_mailbox` delivers it to `target_mailbox_id` (required). `drop` discards it silently, with nothing stored and no webhook fired. Example: deliver_to_mailbox. One of: `deliver_to_mailbox`, `drop`.
- `domain` (`string`, required): The domain the route applies to. It has to be one of your inbound-enabled custom domains. Example: mail.acme.com
- `match_type` (`string`, required): How the route matches recipients. `address` matches one local part and requires `match_value`. `catch_all` matches every recipient on the domain that nothing else matched. Example: address. One of: `address`, `catch_all`.
- `enabled` (`boolean`, optional): Whether the route is evaluated. Example: true
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `match_value` (`string`, optional): The local part an `address` route matches. Required for `address` routes. Stored lowercase. Example: refunds
- `priority` (`integer`, optional): The order routes are tried in, lowest number first. Your own routes take a priority from 11 to 1000. The mailbox's own address always matches at priority 10, so a route can never pre-empt exact-address delivery. Example: 100
- `target_mailbox_id` (`string`, optional): The mailbox that receives matching mail. Required for `deliver_to_mailbox` routes. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"action":"deliver_to_mailbox","domain":"<domain>","match_type":"address"}`

### `bird_email_inbound_route_update`

Update Email Inbound Route · Write

Update an inbound route. Omitted fields are unchanged.
Returns an object with id, domain, match_type, match_value, action, target_mailbox_id, priority, enabled, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs route_id from bird_email_inbound_routes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `route_id` (`string`, required): Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg
- `action` (`string`, optional): What happens to matching mail. `deliver_to_mailbox` delivers it to `target_mailbox_id` (required). `drop` discards it silently, with nothing stored and no webhook fired. Example: deliver_to_mailbox. One of: `deliver_to_mailbox`, `drop`.
- `enabled` (`boolean`, optional): Whether the route is evaluated. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `match_type` (`string`, optional): How the route matches recipients. Example: address. One of: `address`, `catch_all`.
- `match_value` (`string`, optional): The local part an `address` route matches. `null` for `catch_all` routes. Example: sk-test-value
- `priority` (`integer`, optional): The order routes are tried in, lowest number first. Your own routes take a priority from 11 to 1000. The mailbox's own address always matches at priority 10. Example: 11
- `target_mailbox_id` (`string`, optional): The mailbox that receives matching mail. `null` for `drop` routes. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg

Example input: `{"route_id":"<route_id>"}`

### `bird_email_inbox_insights_domain_monitoring_set`

Switch Inbox Insights on for the Workspace's Main Sending Domain · Write

Switch Inbox Insights on for the workspace's main sending domain. Switches Inbox Insights on for the workspace's main sending domain, so a workspace opening the product for the first time has something to read without having to pick a domain first.
Returns an object with outcome, domain.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{}`

### `bird_email_inbox_insights_domain_update`

Switch Inbox Insights on or Off for a Sending Domain · Write

Change the workspace's monitoring preference for one of its verified sending domains.
Returns an object with domain, monitored.
Only the fields you pass change; omitted fields keep their current values.
Needs sending_domain from bird_email_inbox_insights_domains_get.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `monitored` (`boolean`, required): Whether the workspace wants this domain monitored. Enabling enrolls it with eDataSource; disabling removes only the workspace preference and preserves vendor enrollment and measurement history. Verified ownership governs report access. Example: true
- `sending_domain` (`string`, required): The sending domain to change, exactly as it appears in your sending domains. A domain that is not verified in this workspace answers not-found. Example: mail.acme.com
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"monitored":true,"sending_domain":"<sending_domain>"}`

### `bird_email_inbox_insights_seed_test_create`

Register Email Seed Test and Get Its Addresses · Write

Register a seed test and get its addresses. Registers a seed test for a sending domain and returns the seed addresses it measures.
Returns an object with registration_id, seed_addresses, seed_count, expires_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `engagement_profile` (`string`, required): Which engagement behaviour the seeds should simulate. Mixing both behaviours is what makes the engaged-against-dormant comparison measurable. Example: all
- `list_type` (`string`, required): Which seed pool to draw addresses from. Use a value the seed-test configuration reports as available for this account. Example: private
- `regions` (`array`, required): The regions to place seeds in, as the seed-test configuration names them. Example: ["North America - US", "Europe - UK"]
- `sending_domain` (`string`, required): The sending domain the test measures: one of the workspace's verified sending domains, exactly as it appears there. Example: mail.acme.com
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `label` (`string`, optional): A name attached to this registration. It is not returned in seed-test history. Example: Fall preview send

Example input: `{"engagement_profile":"<engagement_profile>","list_type":"<list_type>","regions":["North America - US","Europe - UK"],"sending_domain":"<sending_domain>"}`

### `bird_email_message_cancel`

Cancel Email Scheduled Message · Write

Cancel a message that was scheduled with `scheduled_at` before it sends.
Returns an empty response on success (HTTP 204).
Needs message_id from bird_email_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `message_id` (`string`, required): ID of the scheduled message to cancel, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"message_id":"<message_id>"}`

### `bird_email_message_send`

Create Email Message · Write

Send an email to explicit to, cc and bcc recipients, either inline (subject plus html or text) or from a published template with template parameters. Supports attachments, tags, metadata, custom headers, open/click tracking and scheduled_at for a later send.
Returns the accepted message with id, status, from, to, subject and per-recipient counters; delivery continues asynchronously.
Use this for one transactional or marketing email. Use bird_email_messages_batch_send for many independent emails in one request, bird_email_broadcast_create for a campaign to an audience, and bird_mailbox_message_send to send from an agent mailbox. Follow delivery with bird_email_message_get.
The from address must be on a verified sending domain (bird_email_domains_list); new workspaces can send from Bird's shared onboarding domain to their own address.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`object`, required): Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Must be from a verified domain in this workspace. Example: {"email": "onboarding@messagebird.dev", "name": "Bird"}
- `to` (`array`, required): Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: [{"email": "delivered@messagebird.dev"}]
- `attachments` (`array`, optional): Files to attach, up to 20 per message. A generated message is capped at 20 MB, and a send over it is refused. The cap counts the HTML and text bodies and every attachment and inline image after base64 encoding, which adds about a third, so 15 MB of raw files uses most of it. Each batch item has the same cap, and the whole request body is capped at 20 MB too. Example: [{"filename": "invoice.pdf", "content": "example"}]
- `bcc` (`array`, optional): BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: ["Jane Doe <jane@acme.com>"]
- `category` (`string`, optional): Content classification, which sets the suppression policy: - `marketing`: blocked by every suppression reason. A send with no template and no category defaults to it. - `transactional`: delivered through complaint and unsubscribe suppressions, for receipts, password resets and similar operational mail. A `template` send that omits it takes the template's classification. Set it to classify one send differently from its template; it always takes precedence. Example: marketing. One of: `marketing`, `transactional`.
- `cc` (`array`, optional): CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: ["Jane Doe <jane@acme.com>"]
- `headers` (`object`, optional): Custom email headers, such as `References`, `In-Reply-To`, and `X-*` headers. Reserved headers and values containing carriage returns or line feeds return `422`. Set addressing and subject through their dedicated fields. Transactional sends accept `List-Unsubscribe` and `List-Unsubscribe-Post`. Marketing sends use Bird-managed unsubscribe by default. Example: {"key": "value"}
- `html` (`string`, optional): HTML body. At least one of html or text must be provided. Example: My first Bird email.

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ip_pool_id` (`string`, optional): ID of the IP pool to send from (`ipp_` prefix), or `ipp_shared` to route through the shared pool explicitly. Omit to use the sending domain's default pool in this workspace, or the organization's default when the domain has none. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a `422`. Example: ipp_01jbx7k3m9p2q5r8s4t6v0w1yz
- `metadata` (`object`, optional): JSON object returned on reads and in webhook payloads, up to 2 KB serialized. Analytics can query its paths, such as `metadata.order_id`, but the dashboard cannot filter by it. Use it for per-send context such as order IDs and customer references, and `tags` for low-cardinality labels you filter by. Example: {"key": "value"}
- `parameters` (`object`, optional): Values for the Liquid tokens in inline content, shared by every recipient: `{{ animal }}` takes the `animal` value, and a missing value renders empty. Include the object, even as `{}`, to render Liquid, or omit it to leave tokens unchanged. Names are single words other than `bird`, and the object is capped at 16 KB serialized. A stored template takes `template.parameters` instead. Inline personalization covers validation and URL encoding. Example: {"key": "value"}
- `reference` (`string`, optional): An identifier you want to find this message by, such as an order or ticket number, matched exactly by the message list's `reference` filter. Set it only when you need to search on it, and put any other data in `metadata`. Stored on the message, returned on reads and echoed in webhook payloads. Several messages can share one. Example: INV-1234
- `reply_to` (`array`, optional): Reply-To addresses, each a plain email string, an RFC 5322 mailbox string, or an object with an optional display name. RFC 5322 allows multiple. Every recipient reply hits all listed addresses, so 1-2 is typical. The 25 cap exists to prevent header sizes that some receiving mail servers reject. Example: ["Jane Doe <jane@acme.com>"]
- `scheduled_at` (`string`, optional): Send at this future time instead of immediately, at least 30 seconds and at most 30 days ahead; outside that range returns `422`. The message returns `accepted` and reads as `scheduled` until it sends, and the message cancel endpoint cancels it before then. Scheduled sends count against your plan's monthly scheduled-email allowance, and a send over it returns `422`. A stored template's published version, language and parameter values are pinned at acceptance, so a later publication does not change what sends; deleting the template before the message is due rejects it with `generation_failure`. Sender eligibility and send-volume allowance are checked again when it is due. Batch items take this field too, so one batch can mix scheduled and immediate messages. Example: 2026-01-15T09:30:00Z
- `subject` (`string`, optional): Message subject line. Required for inline sends. Omit it when sending a `template` (the template supplies the subject). Example: Hello from Bird
- `tags` (`array`, optional): Structured `{name, value}` labels, up to 20 per send. You can filter the list endpoint by tag name, slice analytics by tag, and read them in webhook payloads. Use them for low-cardinality dimensions such as `category`, `experiment_variant` or `template_id`, and `metadata` for context you do not filter by. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): Send a stored template instead of inline content. When set, omit `subject`, `html` and `text`, because the template supplies them. Personalize with `template.parameters`. Add `scheduled_at` to send it later. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg"}
- `text` (`string`, optional): Plain-text body. At least one of html or text must be provided. Example: Hello from Bird
- `track_clicks` (`boolean`, optional): Whether to track click events for this message. Example: true
- `track_opens` (`boolean`, optional): Whether to track open events for this message. Example: true

Example input: `{"from":{"email":"onboarding@messagebird.dev","name":"Bird"},"to":[{"email":"delivered@messagebird.dev"}]}`

### `bird_email_messages_batch_send`

Create Batch of Email Messages · Write

Send a batch of independent email messages in one request, each with its own recipients and content or template.
Returns one result per message in request order with the accepted message id or a per-item error.
Use this to send many different emails at once. Use bird_email_message_send for a single email.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `messages` (`array`, required): Email message send requests, up to 100. All items are validated before any are queued. Attachments are allowed on individual messages. Each message must stay within the 20 MB estimated generated message-size cap. The serialized JSON request body for the batch has a hard 20 MB cap. Example: [{"from": {"email": "noreply@acme.com", "name": "Acme Support"}, "to": [{"email": "delivered@messagebird.dev", "name": "Jane Doe"}], "cc": ["manager@acme.com"], "reply_to": ["support@acme.com"], "subject": "Welcome aboard", "html": "<h1>Hi there 👋</h1>", "text": "Hi there", "headers": {"X-Campaign": "spring-2026"}, "tags": [{"name": "category", "value": "welcome"}], "metadata": {"user_id": "usr_12345"}, "category": "transactional", "track_clicks": false}]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"messages":[{"to":"+15551111111","from":"+15557654321","text":"Hi Alice!","category":"marketing"},{"to":"+15552222222","from":"+15557654321","text":"Hi Bob!","category":"marketing"}]}`

### `bird_email_smtp_config_update`

Update Email SMTP Config for an API Key · Write

Set the default send options applied to messages submitted over SMTP with this API key: - Which IP pool to send from. - The content category. - Tags. - Open and click tracking.
Returns an object with api_key_id, ip_pool_id, category, tags, track_opens, track_clicks, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs api_key_id from bird_email_smtp_configs_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `api_key_id` (`string`, required): ID of the API key the config applies to, the same key your SMTP client authenticates with. Example: key_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Content classification, independent of which endpoint messages are submitted through. Controls suppression policy: - `marketing`: Blocks on all suppression reasons. - `transactional`: Allows delivery through complaint and unsubscribe suppressions. Omit to leave unchanged. Example: marketing. One of: `marketing`, `transactional`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ip_pool_id` (`string`, optional): ID of the IP pool to send from (`ipp_` prefix), or `ipp_shared` to route through the shared pool explicitly. Send `null` to reset to your organization's default pool, or omit to leave unchanged. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a `422`. Example: ipp_01jbx7k3m9p2q5r8s4t6v0w1yz
- `tags` (`array`, optional): Structured `{name, value}` labels applied to every message submitted over SMTP with this key. Send an empty array to clear all tags, or omit to leave unchanged. Example: [{"name": "category", "value": "welcome"}]
- `track_clicks` (`boolean`, optional): Whether to track click events for messages submitted over SMTP with this key. Omit to leave unchanged. Example: false
- `track_opens` (`boolean`, optional): Whether to track open events for messages submitted over SMTP with this key. Omit to leave unchanged. Example: false

Example input: `{"api_key_id":"<api_key_id>"}`

### `bird_email_suppression_create`

Create Email Suppression · Write

Add an email address to the suppression list, stopping all email to it.
Returns an object with id, email, scope, reason, origin, applies_to, source_email_id, source_recipient_id, created_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `email` (`string`, required): The address to stop sending to. Normalized before storage and matching: lowercased and trimmed of surrounding whitespace. Example: jane@example.com
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"email":"<email>"}`

### `bird_email_template_create`

Create Email Template · Write

Create a template and its first editable draft. Send the template's `slug` (the name you send the template by), an optional display name that defaults to the slug, a category, the authoring format (`source`), and the draft's content in one or more languages.
Returns an object with editor_url, id, workspace_id, slug, name, description, scope, status, category, source, theme, draft_version_id and more.
Use this to add a new one. Use bird_email_template_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `category` (`string`, required): Whether the template is for `transactional` email or `marketing` email. Example: transactional. One of: `transactional`, `marketing`.
- `slug` (`string`, required): The template's workspace-unique handle, and a stable alternative to the template ID when sending by template. It can contain lowercase letters, numbers, hyphens, and underscores. It is fixed at creation, so pick it deliberately. Two prefixes are rejected: `bird_`, reserved for our built-in templates, and `emt_`, the template ID format, which a slug could never be distinguished from. Example: welcome-email
- `source` (`string`, required): The authoring format the template is written in, fixed at creation. `html` is finished markup you provide, optionally personalized with Liquid. Liquid supports variables, filters, and control flow such as `{% if %}` conditionals and `{% for %}` loops. A few constructs are rejected when you submit, and the error names exactly what to change: - Partial includes (`{% include %}`, `{% render %}`). - The `increment`, `decrement`, and `ifchanged` tags. - The `money`, `format_date`, `format_time`, `json`, `inspect`, and `type` filters. - Comparing against `empty`/`blank` (use `.size == 0` instead). - Blocks nested far deeper than real email markup needs. Broadcast template parameters accept scalar values; arrays and objects are unsupported. Broadcasts support `{% for %}` over a local collection created with `split`. Example: html. One of: `html`.
- `default_language` (`string`, optional): The language a send uses when it does not name one, and the last resort when a requested language is not available. It has to be one of the languages you supply. If you leave it out, we default to `en`, unless you supply exactly one language, in which case we use that one instead. So if you supply two or more languages and `en` is not among them, you have to set this yourself. Example: en
- `description` (`string`, optional): What the template is for, in your own words. Example: Sent to new customers after signup.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `language_source_required` (`boolean`, optional): Whether a send has to name a language. Set it to true to reject a send that names none instead of serving the default language. Pair it with `on_missing_language: fail` when every send must pick a language deliberately: on its own, `fail` is bypassed by naming no language at all. A broadcast must select a template language when this is set. Defaults to false. Example: false
- `languages` (`object`, optional): The initial draft's content, keyed by language tag in BCP-47 form such as `en` or `pt-BR`. A template holds up to 25 languages, and a send picks one of them. Omit this to create an empty draft and add content later. The example's `{{ first_name }}` is a parameter, filled from `template.parameters` at send time. A `{{ bird.contact. }}` placeholder reads a contact attribute. Broadcasts resolve each audience contact during preparation; previews use the selected contact or sample values. Missing attributes use their configured fallbacks, while explicit empty strings remain empty. Public API sends, including batch and scheduled sends, look up each To address in this workspace when the selected language reads contact attributes. A missing contact returns `422` (`E04099`), even if Liquid supplies a default. Each To receives its own personalized email, with Cc and Bcc copied on each. Example: {"en": {"subject": "Welcome, {{ first_name }}", "preview_text": "Your account is ready", "html": "<!DOCTYPE html>\n<html>\n<body>\nHi {{ first_name }}, thanks for signing up.
\n</body>\n</html>\n"}}
- `name` (`string`, optional): The template's display name, shown wherever the template is listed. You can change it any time. It defaults to the slug if you do not set one. Example: Welcome email
- `on_missing_language` (`string`, optional): What a send does when it asks for a language this template does not carry. Defaults to `fallback` on email. Example: fallback. One of: `fallback`, `fail`.

Example input: `{"category":"transactional","slug":"<slug>","source":"html"}`

### `bird_email_template_duplicate`

Duplicate Email Template · Write

Create a new template by copying an existing one: one of your workspace templates, or a built-in `system` template (by its `bird_` slug).
Returns an object with editor_url, id, workspace_id, slug, name, description, scope, status, category, source, theme, draft_version_id and more.
Needs template_ref from bird_email_templates_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): The source template to copy: a workspace template's id (`emt_…`) or slug, or a built-in `system` template's `bird_` slug. The copy is always a new workspace template. Example: welcome-email
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `slug` (`string`, optional): The copy's workspace-unique handle, and the stable alternative to the template ID when sending by template. It can contain lowercase letters, numbers, hyphens, and underscores. Omit it to derive one from the source (for example, `welcome-email-copy`), with a numeric suffix if that slug is already taken. Two prefixes are rejected: `bird_`, reserved for our built-in templates, and `emt_`, the template ID format, which a slug could never be distinguished from. If you supply a slug that is already in use in the workspace, the request returns a conflict. Example: welcome-email-copy

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_language_set`

Upsert Email One Language of a Draft · Write

Upsert one language of a draft. Saves one language's content on the template's draft, creating that language if the draft does not have it yet and replacing it in full if it does.
Returns an object with language, revision, draft_revision, content_hash, updated_at, template_ref, version_id, compatibility_severity, next, compatibility.
The body replaces this subresource in full.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list; language from bird_email_template_version_languages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Example: pt-BR
- `subject` (`string`, required): The email subject line. It may be empty in a draft but is required to publish. Example: Welcome to Acme, {{ bird.contact.first_name }}!
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
- `html` (`string`, optional): The HTML body for this language. Example: <h1>Hi {{ bird.contact.first_name }}</h1>
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `preview_text` (`string`, optional): The line an inbox shows after the subject in the message list. Leave it out and the inbox shows the opening words of the body instead. Example: {{ bird.contact.first_name }}, your order is on its way
- `revision` (`integer`, optional): The revision you last read for this language, to detect a concurrent edit. The save is rejected with a conflict if the language moved on since. Omit it to save unconditionally. Creating a language does not need one. Example: 10
- `text` (`string`, optional): The plain-text body for this language. Omit it and a plain-text alternative is derived from the HTML when you submit. Example: Hello from Bird

Example input: `{"language":"<language>","subject":"<subject>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_language_update`

Update Email One Language of a Draft · Write

Change part of one language's content on the template's draft: send only the fields you are changing and the rest keep their current values.
Returns an object with language, revision, draft_revision, content_hash, updated_at, template_ref, version_id, compatibility_severity, next, compatibility.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list; language from bird_email_template_version_languages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Example: pt-BR
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
- `html` (`string`, optional): A new HTML body for this language. Example: <h1>Hi {{ bird.contact.first_name }}</h1>
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `preview_text` (`string`, optional): A new line for the inbox to show after the subject in the message list. Send null to clear it, and the inbox shows the opening words of the body instead. Example: {{ bird.contact.first_name }}, your order is on its way
- `revision` (`integer`, optional): The revision you last read for this language, to detect a concurrent edit. The edit is rejected with a conflict if the language moved on since. Omit it to apply the edit unconditionally. Example: 10
- `subject` (`string`, optional): The email subject line. It may be empty in a draft but is required to publish. Example: Welcome to Acme, {{ bird.contact.first_name }}!
- `text` (`string`, optional): A new plain-text body for this language. Send null to clear it, and a plain-text alternative is derived from the HTML when you submit. Example: Hello from Bird

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_rollback`

Roll Back an Email Template · Write

Roll back an email template. Makes an earlier published version the live version used by sends, and replaces the draft with that version's content so editing continues from it.
Returns an object with editor_url, id, workspace_id, slug, name, description, scope, status, category, source, theme, draft_version_id and more.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `revision` (`integer`, required): The draft revision you last read (from the template's `revision` field). A stale value returns a conflict so you can reload and retry. Example: 3
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. Rollback resets a draft, and a built-in `system` template has no draft, so its `bird_` slug returns `404` `not_found_error` here. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The published version to restore. Example: emv_01krdgeqcxet5s7t44vh8rt9mh
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"revision":3,"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_update`

Update Email Template · Write

Update a template's metadata and draft settings, such as its name or default language.
Returns an object with editor_url, id, workspace_id, slug, name, description, scope, status, category, source, theme, draft_version_id and more.
Only the fields you pass change; omitted fields keep their current values.
Needs template_ref from bird_email_templates_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `revision` (`integer`, required): The draft revision you last read (from the template's `revision` field). A stale value returns a conflict so you can reload and retry. Example: 3
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Write operations (update, delete) accept a workspace template only, because a `system` template is immutable. Example: bird_welcome
- `default_language` (`string`, optional): New default language for the draft. Must be one of the languages the draft already has, so add the language first if it is not there yet. Example: pt-BR
- `description` (`string`, optional): What the template is for, in your own words. Send `null` to clear it. Example: Created by the Scalekit connector
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `language_source_required` (`boolean`, optional): Whether a send has to name a language. Turning it on rejects a send that names none instead of serving the default language. A broadcast must select a template language when this is set. Example: false
- `name` (`string`, optional): New display name, in free text. The slug stays fixed at creation, so renaming the template does not break whatever refers to it by slug or id. Example: sk-test-sample
- `on_missing_language` (`string`, optional): What a send does when it asks for a language this template does not carry. Example: fallback. One of: `fallback`, `fail`.

Example input: `{"revision":3,"template_ref":"<template_ref>"}`

### `bird_email_template_version_submit`

Submit Email Template Version · Write

Submit the template's draft as a new immutable, numbered version and makes it the live version used by sends.
Returns an object with valid, errors, version, template_ref, version_id, compatibility_severity, compatibility.
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. Submit freezes a draft, and a built-in `system` template has no draft, so its `bird_` slug returns `404` `not_found_error` here. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The draft version to validate or publish. Example: emv_01krdgeqcxet5s7t44vh8rt9mh
- `expected_revision` (`integer`, optional): The draft revision you last read (from the template's `revision` field). A stale value returns a conflict so you can reload and retry. Example: 3
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `languages` (`array`, optional): Languages to process when submitting an already-published version. Email templates accept submissions only for drafts, so setting this field for an email template is rejected. Example: ["pt-BR"]
- `validate_only` (`boolean`, optional): Check the draft without actually submitting it. Every language gets checked and every problem gets reported back to you, but nothing is frozen and no new version gets created. Give a validation run its own `Idempotency-Key`, separate from the real submit that follows it. You can also send no key. The validation request and real submit have different bodies, so using the same key for both is rejected as key reuse. Example: true

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_thread_message_reply`

Reply Email to a Thread Message · Write

Reply to a message in a mailbox email thread, keeping the reply in the same thread.
Returns the reply message with id, thread_id, status and addresses.
Use this to answer an inbound email. Use bird_mailbox_message_send to start a new thread.
Needs thread_id from bird_email_threads_list and message_id from bird_email_thread_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `attachments` (`array`, optional): File attachments to include with the reply. The send is rejected when the estimated generated message size exceeds 20 MB (bodies plus all attachments after base64 encoding). Keep total raw attachment content at or below 15 MB for reliable headroom. Attachment metadata stays on the message's `attachment_manifest`, and the bytes are downloadable for the mailbox's retention tier. Example: [{"filename": "invoice.pdf", "content": "example"}]
- `bcc` (`array`, optional): Blind-copy recipients. Addresses already on the derived To or merged Cc line are dropped (case-insensitive). Bcc addresses are omitted from conversation participants, visible recipient headers, and the 202 response. Bcc delivery outcomes are excluded from the message's `recipients` list. Example: ["jane@example.com"]
- `cancel_on_reply` (`boolean`, optional): When scheduled_at is set, cancel if an inbound message arrives in the conversation before dispatch is claimed. Defaults to false: the frozen parent, recipients and content are sent unchanged even if new mail arrives. Example: false
- `category` (`string`, optional): Content classification, which controls suppression policy: - `marketing`: Blocks on all suppression reasons. - `transactional`: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail. Example: transactional. One of: `marketing`, `transactional`.
- `cc` (`array`, optional): Additional Cc recipients, merged with recipients derived by `reply_all`. Addresses already on the derived To line are dropped (case-insensitive). The merged Cc set must contain at most 50 addresses; larger sets return 422. Example: ["jane@example.com"]
- `html` (`string`, optional): HTML body of the reply. At least one of html or text must be provided. Example: Hello from Bird

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized. Example: {"key": "value"}
- `reply_all` (`boolean`, optional): Also send the reply to the original To and Cc recipients, minus the mailbox's own address. Example: false
- `scheduled_at` (`string`, optional): Send between 30 seconds and 30 days ahead, sharing the scheduled-email allowance. The scheduled send is listed separately and enters the conversation only at dispatch. Sender, mailbox and send-volume eligibility are rechecked then; refusal fails the schedule record without adding a conversation message. Retention starts at dispatch. Attachments are not supported on scheduled messages; send now or schedule without attachments. Example: 2026-01-15T09:30:00Z
- `tags` (`array`, optional): Structured `{name, value}` labels for filtering and analytics on the sent-message log. Cap: 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
- `text` (`string`, optional): Plain-text body of the reply. At least one of html or text must be provided. Example: Hello from Bird

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_email_thread_message_update`

Update Email Message in a Thread · Write

Update a message in a thread. Applies read-state, label, and contact changes to a message in a conversation.
Returns an object with scheduled_message_id, scheduled_at, mailbox_id, notice, id, direction, channel, thread_id, from, from_name, to, cc and more.
Only the fields you pass change; omitted fields keep their current values.
Needs thread_id from bird_email_threads_list; message_id from bird_email_thread_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `contact_id` (`string`, optional): Contact to link this message to, or null to unlink the current contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `labels` (`object`, optional): Label changes to apply. Labels in `add` are applied and labels in `remove` are taken off; other labels are left untouched. Adding a label that is already present, or removing one that is not, has no effect. `set` instead replaces every custom label and leaves system labels as they are; send it on its own, since combining it with `add` or `remove` returns 422. On a message, adding or removing `unread` flips read state. Adding or removing `trash` moves it to or out of the trash. Placement labels cannot be applied to a message; use `folder` on Update a thread (`PATCH /v1/email/threads/{thread_id}`) to move its conversation. A sent message cannot use unread. Custom labels are 1-64 characters with no commas, control characters, or leading or trailing whitespace. Example: {"add": ["urgent"], "remove": ["pending"]}

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_email_thread_restore`

Restore Email Thread from Trash · Write

Restore the conversation's unexpired trashed messages and updates its message and unread counts.
Returns an object with id, mailbox_id, channel, contact_id, subject, participants, participant_names, message_count, unread_count, last_message_at, last_direction, folder and more.
Needs thread_id from bird_email_threads_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"thread_id":"<thread_id>"}`

### `bird_email_thread_update`

Update Email Thread · Write

Set the conversation's `read` state and `folder`, adds or removes custom `labels`, and links or unlinks a contact.
Returns an object with id, mailbox_id, channel, contact_id, subject, participants, participant_names, message_count, unread_count, last_message_at, last_direction, folder and more.
Only the fields you pass change; omitted fields keep their current values.
Needs thread_id from bird_email_threads_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `contact_id` (`string`, optional): Contact to link this conversation to, or null to unlink the current contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `folder` (`string`, optional): Move a non-trashed conversation to inbox, archive or spam. Use DELETE to trash it and POST restore to recover it. Blocked and sent folders are assigned automatically. Example: inbox. One of: `inbox`, `archive`, `spam`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `labels` (`object`, optional): Custom labels to add or remove, or the full set to replace them with. Send `set` on its own; combining it with `add` or `remove` returns 422. System names are refused; use read and folder for thread state. Reserved names are refused too, except a label the conversation already carries from before its name was reserved, which can still be removed, and kept in a `set` in any casing. The resulting custom-label set must contain at most 20 labels; larger sets return 422. A custom name added or set that the workspace does not have yet becomes a workspace label that stays after it is removed from every conversation; once the workspace has 100 labels, a write that would create one more is refused with `E17058`. Custom label names match the workspace's labels in any casing, so adding `Urgent` where the workspace has `urgent` applies `urgent`, and responses return the workspace's spelling. Example: {"add": ["urgent"], "remove": ["pending"]}
- `read` (`boolean`, optional): Mark all retained received messages read or unread. Includes trash, spam and blocked messages; unread_count continues to exclude them. Example: false

Example input: `{"thread_id":"<thread_id>"}`

### `bird_esim_assignment_create`

Assign eSIM to a Person · Write

Assign an existing, allocated eSIM to a subscriber in the same workspace.
Returns an object with id, subscriber_id, esim_id, created_at, updated_at.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `esim_id` (`string`, required): The esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `subscriber_id` (`string`, required): Subscriber in this workspace to assign to the eSIM. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>","subscriber_id":"<subscriber_id>"}`

### `bird_esim_credentials_deliver`

Send Install Credentials to the Traveler · Write

Send a hosted installation link by email or SMS. The eSIM must be installable.
Returns an object with id, channel, to, status, failure_code, created_at, settled_at, install_link.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `channel` (`string`, required): Channel the install credentials are delivered over. Example: sms. One of: `email`, `sms`.
- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `to` (`string`, required): Recipient address. An email address for the email channel, an E.164 phone number for the sms channel. Example: +31612345678
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `locale` (`string`, optional): Language for the message. Falls back to the closest available language, then English. Example: nl

Example input: `{"channel":"email","esim_id":"<esim_id>","to":"<to>"}`

### `bird_esim_install_link_create`

Create Hosted Install Link · Write

Create a link to a hosted installation page for one eSIM.
Returns an object with id, esim_id, url, expires_at, created_at.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_order_cancel`

Cancel Unfunded Order · Write

Cancel an order waiting for funds in `charging`. A canceled unfunded order returns `status: failed` with `failure_code: canceled`.
Returns an object with created_at, updated_at, id, status, mode, offer_id, offer_revision, zone_id, esim_id, subscriber_id, recurring_subscription_id, package_id and more.
Needs order_id from bird_esim_orders_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `order_id` (`string`, required): Order ID. Example: eor_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"order_id":"<order_id>"}`

### `bird_esim_order_create`

Order Data Package · Write

Order a data package. Purchases a data package at the quoted price. Omit `esim_id` to create an eSIM, or provide it to add a compatible package to an existing eSIM.
Returns an object with created_at, updated_at, id, status, mode, offer_id, offer_revision, zone_id, esim_id, subscriber_id, recurring_subscription_id, package_id and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `offer_id` (`string`, required): Offer to purchase. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
- `acknowledge_shortened_validity` (`boolean`, optional): Set to true to accept a validity cut short by the eSIM's service period. Without it, an order whose package would expire early is refused with a conflict that states the effective validity. Example: false
- `display_name` (`string`, optional): Free-text label for the new eSIM, for your own reference. Ignored when esim_id is set. Example: Amsterdam trip, order 8812
- `esim_id` (`string`, optional): Existing eSIM to add the package to. Omit to provision a new eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `expected_price` (`object`, optional): The price you displayed to the buyer. When set and the workspace's current resolved price differs, the order is refused with a conflict instead of charging a different amount. Catches billing-rate changes, which move independently of the offer revision. Example: {"amount": "0.00995", "currency_code": "USD"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Your own key-value data for the new eSIM, echoed on its lifecycle webhook events. Maximum 2 KB serialized. Ignored when esim_id is set. Example: {"key": "value"}
- `offer_revision` (`integer`, optional): The offer revision you are quoting from. When set and the offer has since moved to a newer revision, the order is refused with a conflict instead of charging a price you did not see. Omitted, the current revision is used. Example: 10
- `recurrence` (`object`, optional): Buy the first package and enable automatic renewal in one purchase. Requires subscriber_id, offer_revision and Idempotency-Key. Omit esim_id and expected_price. Example: {"recurrence_revision": 10, "accepted_price": {"amount": "0.00995", "currency_code": "USD"}}
- `subscriber_id` (`string`, optional): Person to assign the new eSIM to when delivery completes. Must be a subscriber in this workspace. Omit to leave it unassigned. Supplying it with esim_id returns 422; top-ups retain the existing assignment. An unknown subscriber or one outside this workspace returns 404 before charging. Identification guidance does not gate purchase. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
- `tags` (`array`, optional): Tags for the new eSIM, echoed on its lifecycle webhook events. Ignored when esim_id is set. Example: [{"name": "category", "value": "welcome"}]

Example input: `{"offer_id":"<offer_id>"}`

### `bird_esim_recurring_subscription_cancel`

Cancel Recurring eSIM Renewal · Write

Stop future package renewal at the current paid boundary.
Returns an object with delivery_mode, id, esim_id, initial_order_id, subscriber_id, offer_id, status, billing_status, current_period_start, current_period_end, cancel_at_period_end, latest_order_id and more.
Needs subscription_id from bird_esim_recurring_subscriptions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"subscription_id":"<subscription_id>"}`

### `bird_esim_recurring_subscription_create`

Create Recurring eSIM Subscription · Write

Start a recurring package on an assigned eSIM and purchases the first period.
Returns an object with delivery_mode, id, esim_id, initial_order_id, subscriber_id, offer_id, status, billing_status, current_period_start, current_period_end, cancel_at_period_end, latest_order_id and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `accepted_price` (`object`, required): The price you accept for the subscription, as returned by the offer's checkout options: a decimal amount string in major units and an ISO 4217 currency code. A changed price is refused so you never pay more than you saw. Example: {"amount": "0.00995", "currency_code": "USD"}
- `esim_id` (`string`, required): Assigned eSIM receiving the recurring package. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, required): Required client-supplied deduplication key for this write. Reuse it for retries of the same intent. Successful results replay within the configured idempotency window (three hours by default); selected connected-app writes also replay uncertain-write conflicts. Use a new key only after confirming the prior result and beginning a different action. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `offer_id` (`string`, required): Offer whose recurring terms the buyer accepted. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
- `offer_revision` (`integer`, required): The accepted offer revision. Example: 1
- `recurrence_revision` (`integer`, required): The accepted recurring configuration revision. Example: 1

Example input: `{"accepted_price":{"amount":"0.00995","currency_code":"USD"},"esim_id":"<esim_id>","idempotency_key":"<idempotency_key>","offer_id":"<offer_id>","offer_revision":1,"recurrence_revision":1}`

### `bird_esim_resume`

Resume eSIM · Write

Resume a suspended eSIM so it can use data again.
Returns an object with subscriber_id, id, status, mode, iccid, phone_number, capabilities, order_id, display_name, installation, packages, zone_balances and more.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_settings_update`

Update eSIM Settings · Write

Update the eSIM settings. Applies partial changes to your workspace's eSIM settings and returns the effective result.
Returns an object with credential_delivery_enabled.
Only the fields you pass change; omitted fields keep their current values.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `credential_delivery_enabled` (`boolean`, optional): Whether Bird automatically sends an install link after a new eSIM purchase with a linked contact. Uses the contact's email address, or SMS when only a phone number is available. Omit this field to retain the current value; a workspace without saved settings starts with `false`. Manual install-link sends remain available regardless of this setting. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{}`

### `bird_esim_subscriber_create`

Create eSIM Subscriber · Write

Create or returns the subscriber associated with a contact in this workspace.
Returns an object with id, contact_id, created_at, updated_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contact_id` (`string`, required): Existing contact in this workspace; requires Contacts read permission. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"contact_id":"<contact_id>"}`

### `bird_esim_suspend`

Suspend eSIM · Write

Suspend the eSIM's data service, for example during a payment dispute or a suspected-fraud hold.
Returns an object with subscriber_id, id, status, mode, iccid, phone_number, capabilities, order_id, display_name, installation, packages, zone_balances and more.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>"}`

### `bird_esim_update`

Update eSIM · Write

Update the eSIM's display name, tags, or metadata.
Returns an object with subscriber_id, id, status, mode, iccid, phone_number, capabilities, order_id, display_name, installation, packages, zone_balances and more.
Only the fields you pass change; omitted fields keep their current values.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `display_name` (`string`, optional): Free-text label for your own reference. Null clears it. Example: Jane Doe
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Replaces the eSIM's metadata. Maximum 2 KB serialized. Example: {"key": "value"}
- `tags` (`array`, optional): Replaces the eSIM's tags. Example: [{"name": "category", "value": "welcome"}]

Example input: `{"esim_id":"<esim_id>"}`

### `bird_lookup_email_batch_create`

Create Batch of Email Address Lookups · Write

Create a batch of email address lookups. Assesses up to 1,000 email addresses synchronously and returns one result per input in submission order.
Returns data, an array of items with email, valid, result, delivery_confidence, flags, reason, did_you_mean.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `emails` (`array`, required): Addresses to assess in submission order. Surrounding whitespace is trimmed and case is preserved. Malformed addresses receive individual assessments. Duplicates are assessed and billed at each position. The request must also fit within the 128 KiB request-body limit. Example: ["jane@example.com"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"emails":["jane@example.com"]}`

### `bird_lookup_email_create`

Create Email Address Lookup · Write

Return a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available.
Returns an object with email, valid, result, delivery_confidence, flags, reason, did_you_mean.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `email` (`string`, required): The email address to look up. Send it exactly as you hold it. The part before the `@` is case-sensitive, so the API does not lowercase it. A display-name form such as `Aisha ` is rejected rather than unwrapped. Example: jane@example.com
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"email":"<email>"}`

### `bird_lookup_email_get`

Get Email Address Lookup by URL · Write

Look up an email address given in the URL for deliverability. Every call performs and is charged for a new lookup.
Returns result, delivery_confidence, address characteristics, reason and a suggested correction when available.
Prefer bird_lookup_email_create, which keeps the address out of URLs and supports an idempotency key so retries are not charged twice.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address` (`string`, required): The email address to look up. Percent-encode it, because a local part may legally contain characters a URL path reads as structure. The `@` itself is safe either way. Example: example

Example input: `{"address":"<address>"}`

### `bird_lookup_phone_number_create`

Create Phone Number Lookup · Write

Return the number's serving and issuing networks, porting state, country, and line type.
Returns an object with phone_number, country_code, network_info, original_network_info, flags, line_type, classification, presence, roaming, sim_swap, porting, score.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `phone_number` (`string`, required): The phone number to look up, in international format: the country calling code, then the national number. The leading `+` is optional, and `00` works in its place, so `+31612345678`, `31612345678` and `0031612345678` are all the same number. A number written for dialling inside one country, with no country code, is rejected rather than guessed at. Example: +14155550123
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `type` (`array`, optional): Properties to add to the base lookup. Omit this field or send an empty array to request only the base lookup. Each delivered property is billed in addition to the base lookup. A property that could not be answered is returned with its status and is not billed. Example: ["classification"]

Example input: `{"phone_number":"<phone_number>"}`

### `bird_lookup_phone_number_get`

Get Phone Number Lookup by URL · Write

Look up a phone number given in the URL: serving and issuing network, porting state, country and line type, plus optional extra blocks. Every call performs and is charged for a new lookup.
Returns the lookup result with the baseline fields and each requested block with its own status.
Prefer bird_lookup_phone_number_create, which keeps the number out of URLs and supports an idempotency key so retries are not charged twice.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `number` (`string`, required): The number to look up, in international format. The leading `+` is optional, and `00` works in its place, so `31612345678` and `+31612345678` are the same number, with nothing to percent-encode. If you do send the `+`, percent-encode it as `%2B` when your client does not do that for you. Example: +14155550123
- `type` (`array`, optional): An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is `ok`. Example: ["classification"]

Example input: `{"number":"<number>"}`

### `bird_mailbox_create`

Create Mailbox · Write

Create a mailbox. The address is `local_part@domain`.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Use this to add a new one. Use bird_mailbox_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `default_reply_to` (`string`, optional): Default `Reply-To` address stamped on mail sent from this mailbox. Example: jane@example.com
- `display_name` (`string`, optional): Name shown to your team in the dashboard and tools. Defaults to `name` when omitted. Example: Acme Concierge
- `domain` (`string`, optional): The domain the address lives under. Defaults to `inbox.ai`, our shared mailbox domain. Creating a mailbox claims the shared address for your organization on a first-come, first-served basis. The address remains reserved to your organization after the mailbox is deleted. You can instead use one of your own domains. On a domain enabled for receiving, mail arrives directly. On a domain this workspace has verified (its `status` is `verified`) that is not set up for receiving, the mailbox gets a `forwarding_address`: forward mail for the address there from your current email provider, with no MX change. If another workspace receives the domain's mail, creation fails with `E17009`. Example: mail.acme.com
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `local_part` (`string`, optional): The local part of the mailbox address (the part before `@`). Letters, digits, dots, underscores, and hyphens. Stored lowercase. On the shared `inbox.ai` domain, separators must sit between letters or digits. Leading, trailing, and repeated separators are not allowed. Reserved names such as `postmaster` and `abuse` are unavailable. Choosing your own local part uses one of your plan's custom-handle allowance slots; generated addresses remain available. Omit this field to generate a random local part. Example: concierge
- `metadata` (`object`, optional): Your own key/value data to attach to the mailbox. Up to 2 KB. Keys starting with `__bird` are reserved. Example: {"key": "value"}
- `name` (`string`, optional): Optional sender name recipients see in the From header of outgoing mail. We recommend setting it so recipients can recognize the sender. Must contain a non-whitespace character and cannot contain carriage returns or line feeds. Example: My Agent
- `receive_policy` (`string`, optional): Which inbound mail the mailbox accepts: - `open`: Accepts everything not blocked by a rule. - `replies_only`: Accepts only replies to messages this mailbox has sent. A reply must match a message the mailbox sent. Landing in an existing thread by itself does not count. - `allowlist`: Accepts only senders matching an allow rule. - `drop`: Stores nothing. Example: open. One of: `open`, `replies_only`, `allowlist`, `drop`.
- `retention_tier` (`string`, optional): How long message metadata, extracted text, and attachments are kept. Original bodies and inbound raw MIME are limited to 30 days on every tier. Longer tiers require a plan that includes them. Example: 30d. One of: `30d`, `90d`, `1y`.

Example input: `{}`

### `bird_mailbox_forwarding_address_create`

Create Mailbox Forwarding Address · Write

Create a mailbox forwarding address. Gives a mailbox on your own domain an address on our receiving domain.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_message_send`

Create Message from a Mailbox · Write

Send a new email from an agent mailbox, starting a new thread (or scheduling it for later).
Returns the sent or scheduled message with id, thread_id, status and addresses.
Use this to start a conversation from a mailbox. Use bird_email_thread_message_reply to answer inside an existing thread, and bird_email_message_send for transactional email from a sending domain.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `subject` (`string`, required): Message subject line. Example: Hello from Bird
- `to` (`array`, required): Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: ["Jane Doe <jane@acme.com>"]
- `attachments` (`array`, optional): File attachments. The send is rejected when the estimated generated message size exceeds 20 MB (bodies plus all attachments after base64 encoding). Keep total raw attachment content at or below 15 MB for reliable headroom. Attachment metadata stays on the message's `attachment_manifest`, and the bytes are downloadable for the mailbox's retention tier. Example: [{"filename": "invoice.pdf", "content": "example"}]
- `bcc` (`array`, optional): BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: ["Jane Doe <jane@acme.com>"]
- `cancel_on_reply` (`boolean`, optional): When scheduled_at is set, cancel if an inbound message arrives in the conversation before dispatch is claimed. Defaults to false: the frozen parent, recipients and content are sent unchanged even if new mail arrives. Example: false
- `category` (`string`, optional): Content classification, which controls suppression policy: - `marketing`: Blocks on all suppression reasons. - `transactional`: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail. Example: transactional. One of: `marketing`, `transactional`.
- `cc` (`array`, optional): CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane `), or an object with an optional display name. Example: ["Jane Doe <jane@acme.com>"]
- `html` (`string`, optional): HTML body. At least one of html or text must be provided. Example: Hello from Bird

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized. Example: {"key": "value"}
- `reply_to` (`array`, optional): Reply-To addresses. When omitted, the mailbox's `default_reply_to` applies (replies then come back to the mailbox itself). Example: ["Jane Doe <jane@acme.com>"]
- `scheduled_at` (`string`, optional): Send between 30 seconds and 30 days ahead, sharing the scheduled-email allowance. The scheduled send is listed separately and enters the conversation only at dispatch. Sender, mailbox and send-volume eligibility are rechecked then; refusal fails the schedule record without adding a conversation message. Retention starts at dispatch. Attachments are not supported on scheduled messages; send now or schedule without attachments. Example: 2026-01-15T09:30:00Z
- `tags` (`array`, optional): Structured `{name, value}` labels for filtering and analytics on the sent-message log. Cap: 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
- `text` (`string`, optional): Plain-text body. At least one of html or text must be provided. Example: Hello from Bird

Example input: `{"mailbox_id":"<mailbox_id>","subject":"<subject>","to":["Jane Doe <jane@acme.com>"]}`

### `bird_mailbox_receive_rule_create`

Create Email Receive Rule · Write

Add an allow or block rule to the mailbox. Rules match the message's envelope sender.
Returns an object with id, mailbox_id, action, entry, entry_type, note, created_at.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `action` (`string`, required): What the rule does when it matches. Block rules always win. To flip an entry's action, delete the existing rule and re-create it. Example: allow. One of: `allow`, `block`.
- `entry` (`string`, required): The sender address (`alice@example.com`) or domain (`example.com`) to match. Domains also match their subdomains. Stored lowercase.
- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `note` (`string`, optional): Your own note about why the rule exists. Example: example

Example input: `{"action":"allow","entry":"<entry>","mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_restore`

Restore Deleted Mailbox · Write

Restore receiving and access to unexpired messages.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_resume`

Resume Suspended Mailbox · Write

Resume a mailbox that was suspended because the organization dropped below the plan needed to keep it active.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_scheduled_message_cancel`

Cancel Scheduled Mailbox Send · Write

Cancel a scheduled send before the scheduler claims dispatch.
Returns an empty response on success (HTTP 204).
Needs mailbox_id from bird_mailboxes_list; scheduled_message_id from bird_mailbox_scheduled_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
- `scheduled_message_id` (`string`, required): Scheduled send identifier from scheduled_message_id in the acceptance response. Example: msm_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>","scheduled_message_id":"<scheduled_message_id>"}`

### `bird_mailbox_update`

Update Mailbox · Write

Update a mailbox. The address and domain are immutable.
Returns an object with id, address, forwarding_address, name, display_name, default_reply_to, receive_policy, state, channel, owner, inbound_address_id, retention_tier and more.
Only the fields you pass change; omitted fields keep their current values.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `confirm` (`boolean`, optional): Set to `true` when lowering `retention_tier` would make remembered messages older than the new cutoff eligible for deletion. The request is rejected without it in that case. Example: false
- `default_reply_to` (`string`, optional): Default `Reply-To` address stamped on mail sent from this mailbox. `null` clears it. Example: jane@example.com
- `display_name` (`string`, optional): Name shown to your team in the dashboard and tools. `null` clears the override and uses `name`. Example: Jane Doe
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Replaces the mailbox's key/value data. Up to 2 KB. Keys starting with `__bird` are reserved. Example: {"key": "value"}
- `name` (`string`, optional): Optional sender name recipients see in the From header of outgoing mail. We recommend setting it so recipients can recognize the sender. Must contain a non-whitespace character and cannot contain carriage returns or line feeds. `null` clears it. Example: sk-test-sample
- `receive_policy` (`string`, optional): Which inbound mail the mailbox accepts: - `open`: Accepts everything not blocked by a rule. - `replies_only`: Accepts only replies to messages this mailbox has sent. A reply must match a message the mailbox sent. Landing in an existing thread by itself does not count. - `allowlist`: Accepts only senders matching an allow rule. - `drop`: Stores nothing. Example: open. One of: `open`, `replies_only`, `allowlist`, `drop`.
- `retention_tier` (`string`, optional): How long message metadata, extracted text, and attachments are kept. Original bodies and inbound raw MIME are limited to 30 days on every tier. Longer tiers require a plan that includes them. Lowering the tier requires `confirm=true` when messages would be affected; accepted changes hide those messages immediately. Deletion waits at least ten minutes and until the retention update finishes. Example: 30d. One of: `30d`, `90d`, `1y`.

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_number_update`

Update Allocated Number · Write

Update the name and reference for a number allocated to your workspace.
Returns an object with name, reference, id, kind, number, country_code, number_type, capabilities, status, allocated_at, releases_at, released_at and more.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs number_id from bird_numbers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `number_id` (`string`, required): Identifier returned by the allocated-number list. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): A name for this number in your workspace, such as Support line. Send null to clear it, or omit it to keep the current name. Example: Support line
- `reference` (`string`, optional): Your own reference for this number, such as an identifier from your records. References need not be unique. Send null to clear it, or omit it to keep the current reference. Example: STORE-042

Example input: `{"number_id":"<number_id>"}`

### `bird_numbers_order_create`

Create Number Order · Write

Create a number order. Orders a number for your workspace and starts its recurring charge.
Returns an object with id, number, country_code, number_type, status, number_id, failure_reason, completed_at, created_at, updated_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `number` (`string`, required): The number to acquire, in E.164 format, as returned by `GET /v1/numbers/available`. Example: +18005550100
- `compliance` (`object`, optional): Ownership paperwork for a number being ordered, where its country requires any. Optional always: the order completes and the number is yours either way, and supplying this only decides whether it can carry traffic sooner. Read `GET /v1/compliance/requirements` for the number to learn what is asked for, or file it after the order with `POST /v1/compliance/submissions`. Filing this cannot fail your order: if it is refused, the number is still yours and you can file again. The answers are a legal representation filed under the name of the business they describe. Sending this block uses the order's existing `numbers` scope at write level. Example: {"answers": [{"key": "business_registration_number", "value": "90012768"}]}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `reference` (`string`, optional): Your own reference to set on the number when this purchase completes. Leading and trailing whitespace is removed. A pending order keeps the reference until the number is allocated. Example: STORE-042

Example input: `{"number":"<number>"}`

### `bird_preference_create`

Record Preference · Write

Record one statement, a grant or an opt-out, for a handle on one channel.
Returns an object with applied, transition_id, preference.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `channel` (`string`, required): The channel a preference statement applies to. A preference addresses one channel: the handle that identifies the person differs per channel, so opting out of one channel says nothing about the others. New channels can be added over time, so a value outside this list can be returned. Example: sms
- `handle` (`string`, required): Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business. Example: +15550001234
- `status` (`string`, required): What the statement says: `granted` records consent to receive messages, `revoked` records an opt-out. There is no third state: a person who never stated anything simply has no preference on record. Example: revoked. One of: `granted`, `revoked`.
- `consented_at` (`string`, optional): When the person consented, on a `granted` statement. Required evidence when granting over a stored opt-out: the grant applies only if this is later than the opt-out it reverses. May not be in the future. Example: 2026-01-15T09:30:00Z
- `coverage` (`string`, optional): How much traffic the statement covers. Defaults to `non_transactional`, which keeps transactional messages such as receipts and verification codes flowing. Apple Messages for Business phone invitations have no transactional exemption, so either value covers them. Example: non_transactional. One of: `all`, `non_transactional`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `sender_scope` (`string`, optional): Limit the statement to one sender instead of the whole channel. On SMS this is the originator; on WhatsApp it identifies the business account; on Apple Messages for Business it is the Apple business ID used for invitations. Not supported on email, where preferences are always channel-wide. Example: +15557654321
- `source` (`string`, optional): Free-form note on where the statement came from: a form name, an import batch, a campaign. Stored verbatim and returned on the preference. Example: signup-form-v2

Example input: `{"channel":"<channel>","handle":"<handle>","status":"granted"}`

### `bird_realtime_app_create`

Create Realtime App · Write

Create a Realtime app. Provisions a new Realtime app for the workspace and returns it with the initial key.
Returns an object with created_at, updated_at, client_events, connection_counting, connection_count_events, watchlist_events, authorized_connections, id, app_id, name, region, status and more.
Use this to add a new one. Use bird_realtime_app_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): A label for the app, shown wherever it is listed. Example: chat-production
- `region` (`string`, required): The region this app runs in. Unlike other products, a Realtime app can be placed in a region other than the workspace's home region. Immutable after creation. Example: us1. One of: `us1`, `eu1`.
- `authorized_connections` (`boolean`, optional): Require every connection to be authorized. Example: false
- `client_events` (`boolean`, optional): Allow clients to trigger events directly (client events). Example: false
- `connection_count_events` (`boolean`, optional): Broadcast connection-count events to public and private channel subscribers. Requires `connection_counting`. Presence channels do not emit these events; use a channel query to read their connection count. Example: false
- `connection_counting` (`boolean`, optional): Count the connections subscribed to each channel and expose the count on channel queries. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `watchlist_events` (`boolean`, optional): Tell a signed-in member when the members on their watchlist come online or go offline. The watchlist is part of the identity your backend signs at signin. Example: false

Example input: `{"name":"<name>","region":"us1"}`

### `bird_realtime_app_key_create`

Create Realtime App Key · Write

Add a new key to the app and returns it with its secret.
Returns an object with id, key, secret, revoked_at, created_at.
Needs realtime_app_id from bird_realtime_apps_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"realtime_app_id":"<realtime_app_id>"}`

### `bird_realtime_app_update`

Update Realtime App · Write

Update a Realtime app's name and configuration flags.
Returns an object with created_at, updated_at, client_events, connection_counting, connection_count_events, watchlist_events, authorized_connections, id, app_id, name, region, status.
Only the fields you pass change; omitted fields keep their current values.
Needs realtime_app_id from bird_realtime_apps_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
- `authorized_connections` (`boolean`, optional): Require every connection to be authorized. Example: false
- `client_events` (`boolean`, optional): Allow clients to trigger events directly (client events). Example: false
- `connection_count_events` (`boolean`, optional): Broadcast connection-count events to public and private channel subscribers. Requires `connection_counting`. Presence channels do not emit these events; use a channel query to read their connection count. Example: false
- `connection_counting` (`boolean`, optional): Count the connections subscribed to each channel and expose the count on channel queries. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): A label for the app, shown wherever it is listed. Example: chat-production
- `watchlist_events` (`boolean`, optional): Tell a signed-in member when the members on their watchlist come online or go offline. The watchlist is part of the identity your backend signs at signin. Example: false

Example input: `{"realtime_app_id":"<realtime_app_id>"}`

### `bird_sms_keyword_rule_create`

Create SMS Keyword Rule · Write

Create a workspace keyword rule. Use it to replace the default opt-out, opt-in, or help reply for one country, or to add a `custom` keyword.
Returns an object with id, scope, operation, country, language, number, keywords, effective_keywords, reply, reply_suffix, reply_disabled_at, mandatory and more.
Use this to add a new one. Use bird_sms_keyword_rule_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): What Bird does when an inbound message matches the rule. - `stop` unsubscribes the sender from further messages. - `start` resubscribes them. - `help` replies with your support information. - `info` replies with your program information. It behaves exactly as `help` does and is separate so a country whose INFO answer must differ from its HELP answer can carry both. Where Bird ships no `info` rule for a country, INFO is one of that country's `help` keywords and answers with the `help` reply. - `confirm` marks a double opt-in reply. It sends nothing today, so answer it from your own handler. - `custom` replies with the text you configured and has no other effect. Bird's built-in rules fix the operation for `stop`, `start` and `help`; you can change their reply but not what they do. The same holds for `info` in any country where Bird ships an `info` rule. This is an open enum. Example: stop
- `confirmed_self_managed` (`boolean`, optional): Set this with `reply: null` to confirm you send this reply from your own system, which switches Bird's auto-reply off for the rule. Required to send no reply, and rejected when a reply is given, so the two can never disagree. Example: true
- `country` (`string`, optional): The country this rule applies in, as an ISO 3166-1 alpha-2 code. It matches a message two ways: one received on any of your numbers in this country, and one sent by a subscriber whose own number is in it, wherever they text you. Rules for the country a message arrives in always outrank rules for the country its sender is in; within each, your rule wins over Bird's keywords for that country. To confine a rule to one of your numbers, set `number` instead. Required for `stop`, `start` and `help`, because those replace what Bird ships for one country and a worldwide rule would replace every country's. Omit it only for `custom`, which then applies everywhere you send. Derived from `number` when you supply an E.164 number and leave this out; a short code carries no country, so a rule for one must name it. Example: NL
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `keywords` (`array`, optional): Extra keywords to match, on top of the ones Bird already ships for this operation and country. Omit to keep Bird's keywords and change only the reply, including keywords Bird adds later. You cannot remove one of Bird's keywords, and a keyword Bird has bound to another operation cannot be reused here. Required for `custom`, which inherits none. Example: ["pizza", "menu"]
- `language` (`string`, optional): Which language this rule replaces, in countries where Bird ships keywords in more than one. Required there and rejected elsewhere. Listing the country's rules shows whether it applies and which languages are available. Example: fr
- `number` (`string`, optional): Narrows the rule to one number you hold, in E.164 format or as a short code. Omit to cover every number you hold in the country. The number must be one of yours and able to receive messages. Example: +18005551234
- `reply` (`string`, optional): The message to send back when a keyword matches, except on a `confirm` rule, which never sends one whatever this is set to. Set it to null together with `confirmed_self_managed` to send nothing at all. Example: You have been unsubscribed and will receive no further messages.

Example input: `{"operation":"<operation>"}`

### `bird_sms_keyword_rule_update`

Update SMS Keyword Rule · Write

Change the reply or the added keywords of a rule you created.
Returns an object with id, scope, operation, country, language, number, keywords, effective_keywords, reply, reply_suffix, reply_disabled_at, mandatory and more.
Only the fields you pass change; omitted fields keep their current values.
Needs id from bird_sms_keyword_rules_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg
- `confirmed_self_managed` (`boolean`, optional): Set this with `reply: null` to confirm you send this reply from your own system. Required to switch the auto-reply off, and rejected when a reply is given. Example: true
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `keywords` (`array`, optional): Replaces the extra keywords this rule matches, on top of the ones Bird ships. Send an empty array to keep Bird's keywords only. Omit to leave the current ones unchanged. Example: ["pizza", "menu"]
- `reply` (`string`, optional): Replaces the message sent back when a keyword matches, except on a `confirm` rule, which never sends one whatever this is set to. Set it to null together with `confirmed_self_managed` to switch the auto-reply off. Omit to leave it unchanged. Example: You have been unsubscribed and will receive no further messages.

Example input: `{"id":"<id>"}`

### `bird_sms_message_send`

Create SMS Message · Write

Send an SMS to one phone number, either free-form text from a sender your workspace can use or a template (including Bird's built-in templates, which pick their own sender).
Returns the accepted message with id, status, to, originator, segment details and cost (null until priced).
Use this for one SMS. Use bird_sms_messages_batch_send for many messages in one request. Poll bird_sms_message_get for delivery status.
The destination country must be enabled for the workspace in the Bird dashboard (SMS > Destinations); free-form text needs a sender from bird_sms_senders_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `to` (`string`, required): Recipient phone number in E.164 format (for example `+14155550100`), or in national format when you also pass `to_country_code`. One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a `422` `SMSInvalidRecipient`. Example: +31612345678
- `audience_id` (`string`, optional): Preview feature: audience-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `binary` (`object`, optional): Send an 8-bit binary payload instead of `text` or `template`. Requires `category` `transactional` and refuses `options.smart_encoding`. It is sent and charged as one segment. Example: {"udh": "0605041582158A", "data": "C0FFEE"}
- `broadcast_id` (`string`, optional): Preview feature: broadcast correlation. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `campaign_id` (`string`, optional): Preview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `category` (`string`, optional): Content classification: why you are sending. Required on a free-text send unless the messaging profile in `messaging_profile_id` sets a default category; omit it on a template send, where the category is derived from the template. Where the destination country requires the sender to be registered, a category outside what that registration covers returns a `422` `SenderCategoryNotPermitted`. Example: transactional. One of: `transactional`, `marketing`, `authentication`, `service`.
- `contact_id` (`string`, optional): Preview feature: contact-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `cost_center` (`string`, optional): Your accounting identifier for this message, such as a department code. Stored on the message and its usage record, returned on reads, and echoed in webhook payloads. Omit it to use the cost center of the messaging profile in `messaging_profile_id`. Accepting it does not change how the message is priced. Example: CC001234
- `from` (`string`, optional): Sender the workspace holds: a number it owns in E.164, such as `+15557654321`, a short code, such as `24680`, or an alphanumeric sender ID it has claimed, such as `MyBrand`. Any other sender returns `422` `SMSSenderNotConfigured`, and an alphanumeric sender must also be permitted, and where required registered, for the destination country. Required on a free-text send and a workspace-template send, unless the profile in `messaging_profile_id` selects a sender for the destination country or has a default sender; omitting it otherwise returns `422`. A built-in template selects its sender itself and rejects `from`. Example: Bird
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `media_urls` (`array`, optional): Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: ["https://example.com/hooks/bird"]
- `messaging_profile_id` (`string`, optional): The messaging profile that supplies this message's sender and defaults. Without `from`, Bird sends from the profile's sender for the destination country, or its default sender. An omitted `category` on a free-text send, `smart_encoding`, `cost_center`, `validity_period`, `options.callback_url` and `options.ignore_suppression` take the profile's settings, and values set on the message take precedence. A built-in template sends from Bird's system sender and ignores the profile's senders. A profile that does not exist in this workspace returns `422` `SMSMessagingProfileNotFound`, and a `from` bound to a different profile returns `422` `SMSMessagingProfileSenderBound`. Example: mpr_01jbx7k3m9p2q5r8s4t6v0w1yz
- `metadata` (`object`, optional): Arbitrary JSON object stored on the message, returned on API reads, and echoed in webhook payloads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use `tags` instead. Example: {"key": "value"}
- `options` (`object`, optional): What Bird does to this message on its way out, such as `smart_encoding`. The message being relayed stays at the top level: its recipient, sender, content, and the delivery instructions the carrier acts on. Example: {"smart_encoding": true}
- `personalization` (`object`, optional): Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: {"key": "value"}
- `reference` (`string`, optional): An identifier you want to find this message by, such as an order or ticket number, matched exactly by the message list's `reference` filter. Set it only when you need to search on it, and put any other data in `metadata`. Stored on the message, returned on reads and echoed in webhook payloads. Several messages can share one. Example: INV-1234
- `scheduled_at` (`string`, optional): Preview feature: send-later scheduling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: 2026-01-15T09:30:00Z
- `tags` (`array`, optional): Structured `{name, value}` labels, up to 20 per send. You can filter the list endpoint by tag name, slice analytics by tag, and read them in webhook payloads. Use them for low-cardinality dimensions such as `category` or `experiment_variant`, and `metadata` for context you do not filter by. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): Send using a stored template instead of free text. The category is derived from the template, so `category` and `media_urls` are rejected. A workspace template requires `from`; a built-in template selects its sender and rejects `from`. Example: {"id": "smt_01krdgeqcxet5s7t44vh8rt9mg"}
- `text` (`string`, optional): Free-text message body, required unless `template` is set; the two are mutually exclusive. From 1 character up to 12 segments, roughly 1836 GSM-7 or 804 UCS-2 characters, since the two encodings fit different numbers of characters in a segment. Bird does not truncate: a longer body returns `422`. Example: Your order shipped, track it here…
- `to_country_code` (`string`, optional): The ISO 3166-1 alpha-2 country whose national numbering plan `to` is written in, such as `NL` for `0612345678`. Bird converts `to` to E.164 before checking the destination, price and sender. An E.164 `to` is still accepted when its country calling code matches this country; a mismatch, or a national number that is not valid in this country, returns a `422` `SMSInvalidRecipient`. Omit it to send `to` in E.164. Example: NL
- `topic_id` (`string`, optional): Preview feature: topic-gated sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
- `validity_period` (`integer`, optional): How long, in seconds (60-172800), the message may wait for delivery after acceptance. Bird does not submit it to the carrier after that deadline, and passes the remaining time to the carrier where the route supports it. A message that misses the deadline before reaching the carrier ends `rejected` or `failed`; `expired` comes only from a carrier report. Omit it to use the validity period of the profile in `messaging_profile_id`, or the carrier's own rules when the profile sets none. Example: 60

Example input: `{"to":"<to>"}`

### `bird_sms_messages_batch_send`

Create Batch of SMS Messages · Write

Send a batch of independent SMS messages in one request, each with its own recipient and content or template.
Returns one result per message in request order with the accepted message or a per-item error.
Use this to send many SMS at once. Use bird_sms_message_send for a single message.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `messages` (`array`, required): SMS message send requests, up to 100. Each is an independent send; all are validated before any is queued. Example: [{"to": "+15551111111", "from": "+15557654321", "text": "Hi Alice!", "category": "marketing"}, {"to": "+15552222222", "from": "+15557654321", "text": "Hi Bob!", "category": "marketing"}]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"messages":[{"to":"+15551111111","from":"+15557654321","text":"Hi Alice!","category":"marketing"},{"to":"+15552222222","from":"+15557654321","text":"Hi Bob!","category":"marketing"}]}`

### `bird_sms_messaging_profile_create`

Create SMS Messaging Profile · Write

Create a messaging profile for one program in your workspace.
Returns an object with id, name, senders, inbound, default_category, validity_period, cost_center, options, callback_events, created_at, updated_at.
Use this to add a new one. Use bird_sms_messaging_profile_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): A label for the profile. Names are not unique, so two profiles can share one. Example: device-activation
- `callback_events` (`array`, optional): The events of this profile's outbound messages that go to a callback URL. The list is fixed when a message is accepted, and applies only while the message has a callback URL: an event outside it then reaches neither the URL nor a plain webhook endpoint. Without a callback URL the list has no effect, and every event goes to your webhook endpoints. A value other than `sms.accepted`, `sms.sent`, `sms.delivered`, `sms.undelivered`, `sms.failed`, `sms.rejected` or `sms.expired` returns `422`. `sms.received` is never filtered. Omit it to deliver every event. Example: ["sms.delivered", "sms.failed"]
- `cost_center` (`string`, optional): A label for assigning the cost of this profile's messages. A send that omits `cost_center` uses it. Example: CC001234
- `default_category` (`string`, optional): The category a free-text send that names this profile uses when it sets none: `transactional`, `marketing`, `authentication`, or `service`. A template send takes the template's category. Example: authentication. One of: `transactional`, `marketing`, `authentication`, `service`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound` (`object`, optional): How the profile receives replies. Omit it for a profile that only sends. Example: {"numbers": [{"number": "34001"}], "callback_url": "https://receipts.example.com/bird/sms/inbound"}
- `options` (`object`, optional): Sending options for messages that do not set their own. Booleans default to `false`. Example: {"smart_encoding": false, "ignore_suppression": false}
- `senders` (`array`, optional): The sender for each destination country, and optionally a default sender. Each country appears at most once, and at most one entry omits `country_code`. Example: [{"sender_id": "snd_01krdgeqcxet5s7t44vh8rt9mg"}]
- `validity_period` (`integer`, optional): How many seconds a message stays valid before it expires undelivered. A send that omits `validity_period` uses it. Example: 3600

Example input: `{"name":"<name>"}`

### `bird_sms_messaging_profile_update`

Update SMS Messaging Profile · Write

Change a messaging profile. Properties you omit keep their value, including those inside `inbound` and `options`, and `null` clears a property that accepts it.
Returns an object with id, name, senders, inbound, default_category, validity_period, cost_center, options, callback_events, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs profile_id from bird_sms_messaging_profiles_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `profile_id` (`string`, required): ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg
- `callback_events` (`array`, optional): The events of this profile's outbound messages that go to a callback URL. The list is fixed when a message is accepted, and applies only while the message has a callback URL: an event outside it then reaches neither the URL nor a plain webhook endpoint. Without a callback URL the list has no effect, and every event goes to your webhook endpoints. A value other than `sms.accepted`, `sms.sent`, `sms.delivered`, `sms.undelivered`, `sms.failed`, `sms.rejected` or `sms.expired` returns `422`. `sms.received` is never filtered. Send `null` to deliver every event. Example: ["sms.delivered", "sms.failed"]
- `cost_center` (`string`, optional): A label for assigning the cost of this profile's messages. Send `null` to clear it. A send that omits `cost_center` uses it. Example: CC001234
- `default_category` (`string`, optional): The category a free-text send that names this profile uses when it sets none: `transactional`, `marketing`, `authentication`, or `service`. A template send takes the template's category. Send `null` to clear it. Example: authentication. One of: `transactional`, `marketing`, `authentication`, `service`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound` (`object`, optional): Changes how the profile receives replies. Omitted properties keep their value. Example: {"numbers": [{"number": "34001"}], "callback_url": "https://receipts.example.com/bird/sms/inbound"}
- `name` (`string`, optional): A new label for the profile. Names are not unique, so two profiles can share one. Example: device-activation
- `options` (`object`, optional): Changes the sending options for messages that do not set their own. Omitted properties keep their value. Example: {"smart_encoding": false, "ignore_suppression": false}
- `senders` (`array`, optional): Replaces the profile's senders. Each country appears at most once, and at most one entry omits `country_code`. Send an empty array to remove them all. Example: [{"sender_id": "snd_01krdgeqcxet5s7t44vh8rt9mg"}]
- `validity_period` (`integer`, optional): How many seconds a message stays valid before it expires undelivered. Send `null` to clear it. A send that omits `validity_period` uses it. Example: 3600

Example input: `{"profile_id":"<profile_id>"}`

### `bird_sms_sender_create`

Create SMS Sender · Write

Create an SMS sender. Claims an alphanumeric sender string for your workspace.
Returns an object with id, sender, source_kind, sender_type, country_code, number_id, status, next, destinations, created_at, updated_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `sender` (`string`, required): The alphanumeric sender string to create, for example "BIRD". 3–11 letters, digits, spaces, dashes, underscores, or dots, at least one of them a letter, and no separator at either end. Example: BIRD
- `type` (`string`, required): The kind of sender to create. Only `alpha` (an alphanumeric sender string) is customer-creatable. Dedicated numbers become senders when you allocate them from inventory. This endpoint cannot create their senders. Example: alpha. One of: `alpha`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"sender":"<sender>","type":"alpha"}`

### `bird_sms_sender_registration_create`

Create SMS Sender Registration for a Country · Write

Create a sender registration for a country. Registers a sender for a destination country. If the country requires review, the sender can send there after approval.
Returns an object with id, country_code, registration_mode, sender_id_behavior, program, category, status, program_ref, rejection_reason, created_at, updated_at.
Needs sender_id from bird_sms_senders_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `country_code` (`string`, required): ISO 3166-1 alpha-2 country code. Example: US
- `sender_id` (`string`, required): ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg
- `category` (`string`, optional): Message category to register the sender for. Omit to register the sender for all categories. Example: transactional. One of: `transactional`, `marketing`, `authentication`, `service`.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"country_code":"<country_code>","sender_id":"<sender_id>"}`

### `bird_sms_suppression_create`

Create SMS Suppression · Write

Stop a sender's messages to a subscriber, with reason `manual`, blocking every category including transactional.
Returns an object with id, destination, originator, reason, origin, applies_to, blocking, source_sms_id, effective_at, ended_at, ended_reason, ended_effective_at and more.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `destination` (`string`, required): The subscriber to stop messaging, in E.164 format. Example: +15550001234
- `originator` (`string`, required): The sender to stop. Your other senders keep reaching this subscriber, so stopping every one of them means one call per sender. Example: +15557654321
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"destination":"<destination>","originator":"<originator>"}`

### `bird_verification_check`

Create Verification Passcode Check · Write

Check a one-time passcode a user entered against an active verification.
Returns the verification with its status (approved when the code matched) and remaining attempts.
Use this after bird_verification_send. A wrong code counts against the attempt limit.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `code` (`string`, required): The passcode the recipient received. Passcodes are numeric; submit the digits exactly as delivered. An incorrect value is a normal `200` outcome with `success: false`. It does not return an error. Example: 123456
- `to` (`object`, required): The recipient to verify. Provide an `email`, a `phone_number`, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone. Example: {"email": "user@example.com"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"code":"<code>","to":{"email":"user@example.com"}}`

### `bird_verification_next_channel_send`

Create Next Verification Channel Attempt · Write

Send a fresh passcode for an active verification on its next configured channel, for example voice after SMS.
Returns the verification with its new channel and status.
Use this when the user did not receive the first code. Use bird_verification_check to check the new code.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `to` (`object`, required): The recipient to verify. Provide an `email`, a `phone_number`, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone. Example: {"phone_number": "+15551234567"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"to":{"phone_number":"+15551234567"}}`

### `bird_verification_send`

Create Verification · Write

Start a verification: send a one-time passcode to a phone number or email address over SMS, WhatsApp, voice or email using Bird's shared senders.
Returns the verification with id, status, channel and expiry.
Use this to start an OTP flow. Use bird_verification_check to check the code the user enters and bird_verification_next_channel_send to resend on the next channel.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `to` (`object`, required): The recipient to verify. Provide an `email`, a `phone_number`, or both; at least one is required. The addresses also identify the verification: a check must supply exactly the set used on the create call, so a verification created with both addresses is not found by either one alone. Example: {"email": "user@example.com"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `metadata` (`object`, optional): Optional key/value pairs to attach to the verification, for example a correlation id. Returned on the verification.
- `options` (`object`, optional): Per-request overrides applied to this verification only. `language` picks one of Bird's built-in translations; a custom sender that carries its own template renders the language that template stocks instead. An email template pinned to a custom email sender falls back to its own default language rather than to English (Verify only accepts templates whose language settings fall back). A WhatsApp authentication template follows its own missing-language policy: it falls back to its default or, when set to fail, refuses the send for a language it does not stock. The requested tag stays fixed for the verification. Example: {"code_length": 8, "channels": ["example"]}

Example input: `{"to":{"email":"user@example.com"}}`

### `bird_voice_call_create`

Create Voice Call · Write

Place an outbound voice call from one of your numbers to a phone number or SIP endpoint, running a voice sequence or connecting the parties.
Returns the accepted call with id, initial_leg_id, direction, parties and live status.
Use this to start a call. Use bird_voice_legs_list or bird_voice_leg_get to follow it and bird_voice_call_transcript_get afterwards.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `from` (`string`, required): Calling number that this workspace is permitted to present. Example: +12025550100
- `sequence` (`object`, required): Supply exactly one of `id`, to run a saved sequence's active publication, or `definition`, to run a sequence once without saving it. Example: {"id": "vsq_01krdgeqcxet5s7t44vh8rt9mg", "entry_node_id": "start", "trigger_data": {}}
- `to` (`string`, required): Recipient number in canonical E.164 form. Example: +12025550101
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `ringing_timeout_seconds` (`integer`, optional): Maximum ringing time for the original dialing attempt, shared across routing candidates. Example: 30

Example input: `{"from":"<from>","sequence":{},"to":"<to>"}`

### `bird_voice_destinations_update`

Update Enabled Voice Destination Countries · Write

Update enabled Voice destination countries. Enables or disables specific destination countries for your workspace, and sets or removes their daily spend limits.
Returns data, an array of items with country_code, country_name, dial_code, region, super_region, enabled, status, high_risk_destination, daily_spend_limit, plus total.
Only the fields you pass change; omitted fields keep their current values.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `destinations` (`array`, required): The destination countries to change. Only the countries listed here change, and only the fields you send; anything else keeps its current setting. A country listed more than once takes its last `enabled`, but may set or remove `daily_spend_limit` only once. A limit can be set only on a country the Voice service supports; removing one accepts any country code. Otherwise the request is rejected and nothing changes. Example: [{"country_code": "NL", "enabled": true}, {"country_code": "GB", "enabled": false}]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"destinations":[{"country_code":"NL","enabled":true},{"country_code":"GB","enabled":false}]}`

### `bird_voice_number_update`

Update Voice Number · Write

Change what you have said about this number: the label you gave it, and what happens when a call arrives for it.
Returns an object with id, phone_number, country_code, name, provider, directions, inbound_configuration, created_at.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs number_id from bird_voice_numbers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `number_id` (`string`, required): ID of the voice number to retrieve or update, as returned by the voice number list. Example: vnu_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound_configuration` (`object`, optional): What should happen to calls arriving for this number. The route replaces whatever was set before, because a number has exactly one answer at a time. Type "reject" stops it answering, and a null route returns it to your workspace's default inbound route. Omit the field to leave the answer alone. Only a number that can receive calls carries a route, so it is refused on one whose directions do not include inbound. Example: {"route": {"type": "trunk", "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"}}
- `name` (`string`, optional): Your own label for this number. Send null to remove the one it has. Omit the field to leave it alone. Example: Support line

Example input: `{"number_id":"<number_id>"}`

### `bird_voice_ring_group_create`

Create Voice Ring Group · Write

Create a ring group with no members. Add members with `POST /v1/voice/ring-groups/{ring_group_id}/members`.
Returns an object with id, name, is_default, online_member_count, created_at, updated_at.
Use this to add a new one. Use bird_voice_ring_group_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The ring group's name. Example: Support
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>"}`

### `bird_voice_ring_group_member_create`

Add Voice Member to a Ring Group · Write

Add a workspace user to the ring group. The group rings the user only while they are online in the browser phone.
Returns an object with user_id, created_at.
Needs ring_group_id from bird_voice_ring_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `ring_group_id` (`string`, required): ID of the ring group whose members to list or add to. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
- `user_id` (`string`, required): The workspace user to add. `bird members list` and the `members_list` MCP tool list workspace members in pages, each with its `user.id`; follow `next_cursor` until the user appears. Both need the `members` scope at read level. Example: usr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"ring_group_id":"<ring_group_id>","user_id":"<user_id>"}`

### `bird_voice_ring_group_update`

Update Voice Ring Group · Write

Update a ring group. Renames the ring group. Renaming the default group returns `409 Conflict`.
Returns an object with id, name, is_default, online_member_count, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs ring_group_id from bird_voice_ring_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The ring group's new name. Example: Tier 2 support
- `ring_group_id` (`string`, required): ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>","ring_group_id":"<ring_group_id>"}`

### `bird_voice_session_credential_create`

Create Voice SIP Session Credential · Write

Issue a workspace-scoped SIP digest credential valid for five minutes.
Returns an object with username, password, realm, expires_at, handshake_token.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `idempotency_key` (`string`, optional): Does not deduplicate this operation. Every successful attempt creates a fresh credential. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{}`

### `bird_voice_settings_update`

Update Voice Settings · Write

Change your workspace's voice settings. Omit a field to leave it as it is.
Returns an object with inbound_configuration, daily_spend_limit.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `daily_spend_limit` (`object`, optional): The workspace's own daily voice spend limit. Set workspace_limit to an amount object (decimal amount string and currency code, in the organization's wallet currency) or to null to remove the override so the default applies. Example: {"workspace_limit": {"amount": "0.00995", "currency_code": "USD"}}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound_configuration` (`object`, optional): The route for calls arriving on any of your Bird numbers that has no inbound route of its own; verified caller IDs receive no calls. It takes effect on the next call to each of those numbers. Numbers with their own route keep it. Example: {"route": {"type": "trunk", "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"}}

Example input: `{}`

### `bird_voice_trunk_create`

Create Voice SIP Trunk · Write

Create a SIP trunk. Provisions a new SIP trunk for the workspace. Bird assigns a unique domain for the trunk; use this domain as the SIP registrar or proxy address in your PBX or SIP client.
Returns an object with id, workspace_id, name, domain, outbound_enabled, inbound_enabled, media_bypass, ip_acls, allowed_api_key_ids, ineligible_api_key_ids, digest_algorithms, session_credentials_enabled and more.
Use this to add a new one. Use bird_voice_trunk_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain. Example: Production PBX trunk
- `digest_algorithms` (`array`, optional): The Digest hash algorithms to offer, in the order they should be offered. Omit this to use the default of `["SHA-256", "MD5"]`, which suits most equipment. Send `["MD5"]` for a PBX that only implements MD5 and rejects or ignores a challenge offering SHA-256 first. This can be changed later without re-issuing credentials. Example: ["MD5"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound_enabled` (`boolean`, optional): Whether the new trunk may receive calls. Omit it to create a trunk that does neither direction yet. A trunk receives no calls until it also has at least one gateway and at least one number, both added after create. Example: true
- `media` (`object`, optional): How the new trunk carries call audio. An omitted member takes its default. Example: {"encryption": "preferred"}
- `media_bypass` (`boolean`, optional): Whether we take ourselves out of the audio path for calls we forward to this trunk. Omit it to create the trunk with this off, which is what suits equipment behind NAT and any account that wants call recording. It is an inbound setting, so `true` is accepted only alongside `inbound_enabled: true`; `false` is always accepted. It can be changed later. Example: true
- `outbound_enabled` (`boolean`, optional): Whether the new trunk may place calls. Omit it to create a trunk that does neither direction yet, and enable the ones you want once you know what the trunk is for. The settings below configure outbound, so send this as `true` alongside them. Example: true
- `session_credentials_enabled` (`boolean`, optional): Whether a session credential may be used to connect to this trunk from a web browser, the CLI or MCP. Omit it to create the trunk with this off, which is what a trunk reached only by a PBX wants. It can be changed later. Example: true

Example input: `{"name":"<name>"}`

### `bird_voice_trunk_gateway_create`

Create Voice Gateway on a SIP Trunk · Write

Add a gateway address for forwarding inbound calls to this trunk.
Returns an object with id, trunk_id, sip_uri, priority, origination_format, destination_format, created_at, updated_at.
Use this to add a new one. Use bird_voice_trunk_gateway_update to change an existing one.
Needs trunk_id from bird_voice_trunks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `priority` (`integer`, required): The gateway's place in the trunk's All gateways (automatic) hunt group, which tries the lowest priority first. Give two gateways the same priority to share calls between them evenly. Hunt groups you build in the trunk's inbound routing in the dashboard set their own order. Example: 0
- `sip_uri` (`string`, required): SIP URI an inbound call to this trunk should be forwarded to. Give the host only, with an optional port: which number is dialed there comes from `destination_format`, so a URI carrying a user part is rejected. Example: sip:pbx.example.com:5060
- `trunk_id` (`string`, required): ID of the SIP trunk whose gateways to list or create. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `destination_format` (`string`, optional): How this gateway formats the dialed number. In the template, `{number}` represents the number without its leading `+`. The result is placed before the `sip_uri` host. For example, `1234#{number}` formats `+31201234567` as `sip:1234#31201234567@pbx.example.com:5060`. Omit it for E.164, which is `+{number}`. A format with no `{number}` at all sends every number this trunk answers to one fixed number, so `777000447973` reaches `sip:777000447973@pbx.example.com:5060` whatever was dialed. The same rules as `origination_format` apply to what the template may contain.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `origination_format` (`string`, optional): How this gateway wants the calling number spelled. Write a template whose `{number}` stands for the number without its leading `+`; the result is stated in the `P-Asserted-Identity` header of the delivered call. Omit it for E.164, which is `+{number}`. The template may add digits, letters and the characters `-_.!~*'()&=+$,;?/%#` around `{number}`, which may appear at most once, and anything else in braces is rejected so a misspelled placeholder cannot reach a call. A format with no `{number}` at all states the same identity on every call, which is what a peer that only accepts one authorized number wants. The call then carries nothing about who really called. Example: +{number}

Example input: `{"priority":0,"sip_uri":"<sip_uri>","trunk_id":"<trunk_id>"}`

### `bird_voice_trunk_gateway_update`

Update Voice SIP Trunk Gateway · Write

Update the gateway's `sip_uri`, its `priority`, either number format, or any combination.
Returns an object with id, trunk_id, sip_uri, priority, origination_format, destination_format, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs trunk_id from bird_voice_trunks_list; gateway_id from bird_voice_trunk_gateways_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `gateway_id` (`string`, required): ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
- `trunk_id` (`string`, required): ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `destination_format` (`string`, optional): How this gateway formats the dialed number. In the template, `{number}` represents the number without its leading `+`. The result is placed before the `sip_uri` host. For example, `1234#{number}` formats `+31201234567` as `sip:1234#31201234567@pbx.example.com:5060`. Send an empty string to go back to E.164, which is `+{number}`. A format with no `{number}` at all sends every number this trunk answers to one fixed number, so `777000447973` reaches `sip:777000447973@pbx.example.com:5060` whatever was dialed. The same rules as `origination_format` apply to what the template may contain.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `origination_format` (`string`, optional): How this gateway wants the calling number spelled, as a template whose `{number}` stands for the number without its leading `+`. The result is stated in the `P-Asserted-Identity` header of the delivered call. Send an empty string to go back to E.164, which is `+{number}`. The template may add digits, letters and the characters `-_.!~*'()&=+$,;?/%#` around `{number}`, which may appear at most once, and anything else in braces is rejected so a misspelled placeholder cannot reach a call. A format with no `{number}` at all states the same identity on every call, which is what a peer that only accepts one authorized number wants. The call then carries nothing about who really called. Example: +{number}
- `priority` (`integer`, optional): The gateway's place in the trunk's All gateways (automatic) hunt group, which tries the lowest priority first. Give two gateways the same priority to share calls between them evenly. Hunt groups you build in the trunk's inbound routing in the dashboard set their own order. Example: 0
- `sip_uri` (`string`, optional): SIP URI an inbound call to this trunk should be forwarded to. Give the host only, with an optional port: which number is dialed there comes from `destination_format`, so a URI carrying a user part is rejected. Example: sip:pbx.example.com:5060

Example input: `{"gateway_id":"<gateway_id>","trunk_id":"<trunk_id>"}`

### `bird_voice_trunk_update`

Update Voice SIP Trunk · Write

Update a SIP trunk's `name`, access control (`ip_acls`, `allowed_api_key_ids`), and Digest algorithm offer (`digest_algorithms`).
Returns an object with id, workspace_id, name, domain, outbound_enabled, inbound_enabled, media_bypass, ip_acls, allowed_api_key_ids, ineligible_api_key_ids, digest_algorithms, session_credentials_enabled and more.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs trunk_id from bird_voice_trunks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `trunk_id` (`string`, required): ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `allowed_api_key_ids` (`array`, optional): Replaces the trunk's entire set of allowed API keys. When present, exactly these keys may authenticate the trunk over SIP Digest. Each key you ADD must belong to this workspace and hold `voice` at write level; a key that does not is refused and the whole update is rolled back. A key already on the list that has since lost the permission or expired does not block the update, so you can keep editing the trunk while you put its permission back. A non-empty list turns API-key authentication on; send an empty array to turn it off. Omit the field to leave the allowed keys unchanged. Example: ["key_01krdgeqcxet5s7t44vh8rt9mg"]
- `digest_algorithms` (`array`, optional): Replaces the Digest hash algorithms this trunk offers, in the order they should be offered. Send `["MD5"]` for a PBX that only implements MD5 and rejects or ignores a challenge offering SHA-256 first. Send an empty array to return to the default of `["SHA-256", "MD5"]`. The offer is never empty, because a trunk that offered nothing could not be authenticated at all. Narrowing the list also narrows what the trunk accepts: an answer using an algorithm no longer offered is rejected. Takes effect on the next call setup; no credential is re-issued. Omit the field to leave the offer unchanged. Example: ["MD5"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbound_enabled` (`boolean`, optional): Whether this trunk may receive calls. Turning it off resets number routes that use this trunk to reject incoming calls. Turning it back on does not restore those routes. Clear an attached emergency number in the dashboard before turning inbound off. The gateways remain configured. Omit the field to leave it unchanged. Example: true
- `ip_acls` (`array`, optional): Replaces the trunk's entire IP allow list. When present, the allow list is set to exactly these CIDR blocks: ranges not listed are removed and new ones are added. Send an empty array to clear the list, turning IP filtering off. Omit the field to leave the allow list unchanged. Example: [{"cidr": "203.0.113.0/24"}]
- `media` (`object`, optional): A change to how the trunk encrypts call audio. Example: {"encryption": "preferred"}
- `media_bypass` (`boolean`, optional): Whether we take ourselves out of the audio path for calls we forward to this trunk. Turning it on takes effect at the next call setup and leaves calls already up untouched. It is an inbound setting, so the trunk must have `inbound_enabled` on; one update can do both. While it is on we cannot record those calls, report their audio quality, or end one because its audio stopped, and your equipment must be reachable for audio from the public internet. Turning it off puts us back in the path at the next call setup. Omit the field to leave it unchanged. Example: true
- `name` (`string`, optional): A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain. Example: Production PBX trunk
- `outbound_enabled` (`boolean`, optional): Whether this trunk may place calls. Turning it off stops the trunk admitting call attempts at the next call setup and leaves its connection and authentication settings stored, so turning it back on restores a working trunk. Omit the field to leave it unchanged. Example: true
- `session_credentials_enabled` (`boolean`, optional): Whether a session credential may be used to connect to this trunk from a web browser, the CLI or MCP. Off by default; turning it on does not change what the allow lists admit, and turning it off stops those connections at the next call setup without re-issuing anything. Omit the field to leave it unchanged. Example: true

Example input: `{"trunk_id":"<trunk_id>"}`

### `bird_voice_verified_number_create`

Create Voice Verified Number · Write

Create a verified number. Registers a phone number as an outbound caller ID for the workspace and starts verification.
Returns an object with id, workspace_id, phone_number, name, status, outbound_enabled, verified_at, created_at, updated_at.
Use this to add a new one. Use bird_voice_verified_number_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `phone_number` (`string`, required): The phone number to register as an outbound caller ID, in E.164 format (a leading `+` followed by the country code and national number). Must be unique within the workspace. Creating the verified number starts verification: a verification call is placed to this number. Example: +14155551234
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `name` (`string`, optional): Your label for this verified number, to tell several registered numbers apart. Omit it to register the number without one and add it later. It is yours to choose and appears nowhere on a call, so it never affects what the person you are calling sees. Example: Support line

Example input: `{"phone_number":"<phone_number>"}`

### `bird_voice_verified_number_update`

Update Voice Verified Number · Write

Set the verified number's label. Send `name` as null to clear the label.
Returns an object with id, workspace_id, phone_number, name, status, outbound_enabled, verified_at, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values. Pass at least one field.
Needs verified_number_id from bird_voice_verified_numbers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Your new label for this verified number. Send `null` to clear it and go back to identifying the verified number by its number alone. It is yours to choose and appears nowhere on a call, so renaming never affects what the person you are calling sees, and it leaves the number and its verification untouched. Example: Support line
- `verified_number_id` (`string`, required): ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"name":"<name>","verified_number_id":"<verified_number_id>"}`

### `bird_voice_verified_number_verify`

Verify Voice Number Ownership · Write

Verify number ownership. Completes the number ownership verification challenge that registering the number started.
Returns an object with id, workspace_id, phone_number, name, status, outbound_enabled, verified_at, created_at, updated_at.
Needs verified_number_id from bird_voice_verified_numbers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `verified_number_id` (`string`, required): ID of the verified number registration whose ownership challenge to complete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
- `code` (`string`, optional): The 6-digit verification code read out by the verification call. Required until ownership is verified. Omit it when retrying activation of an already verified number. Example: 123456
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"verified_number_id":"<verified_number_id>"}`

### `bird_webhook_callback_replay`

Replay Failed Callback Deliveries · Write

Replay failed callback deliveries. Queues redelivery of SMS callbacks that failed. The window runs from `since` (default: the last 24 hours) to `until`, and events whose callback was already received successfully within that window are skipped.
Returns an empty response on success (HTTP 202).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `since` (`string`, optional): Replay events whose delivery attempt failed at or after this timestamp. The bound is inclusive and applies to attempt time, not to when the event occurred, so a retry that trailed its event by a day falls in the window by the hour it was attempted. Defaults to 24 hours before the request when omitted. Attempts are retained for three days, so that is the oldest history a replay reaches: an earlier `since` widens the window without recovering anything older. Example: 2026-05-07T00:00:00Z
- `until` (`string`, optional): Replay events whose delivery attempt failed at or before this timestamp, on the same attempt-time bound as `since`. Omitted, it resolves to the time of the request. Example: 2026-05-07T23:59:59Z

Example input: `{}`

### `bird_webhook_callback_signing_secret_rotate`

Rotate Callback Signing Secret · Write

Rotate callback signing secret. Generates a new signing secret for the workspace's SMS callback URLs and voice sequence webhook requests, and returns it exactly once: store it immediately, it cannot be retrieved after this response.
Returns an object with secret.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{}`

### `bird_webhook_create`

Create Webhook Endpoint · Write

Create a webhook endpoint. Registers an `active` webhook endpoint that receives the event types in `events` as signed HTTPS `POST` requests.
Returns an object with id, url, description, filter, events, status, destination, next, created_at, updated_at, secret.
Use this to add a new one. Use bird_webhook_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `events` (`array`, required): Event types to subscribe to; the endpoint receives only matching events. Types outside the event catalog return a `422`, and an endpoint holds at most 100 entries. Example: ["email.delivered", "email.bounced"]
- `description` (`string`, optional): Human-readable label for this endpoint, up to 256 characters. Example: Production webhook endpoint
- `destination` (`object`, optional): How each delivery is built. Omit to post the signed event to `url` unchanged, the same as `{"type": "webhook"}`. Example: {"type": "webhook"}
- `filter` (`object`, optional): Limit delivery to one mailbox and only email_mailbox events. Omit to include all resources. Example: {"mailbox_id": "mbx_01kr97a6rje4wbe5z40wxdfcy9"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `url` (`string`, optional): HTTPS URL to deliver events to, at most 2048 characters. The host must be publicly reachable: URLs on private, loopback, or link-local addresses are rejected with a `422`. Required unless `destination` is a connector, whose URL comes from the connector and its `config`; a URL given with one must equal it. Example: https://example.com/webhook

Example input: `{"events":["email.delivered","email.bounced"]}`

### `bird_webhook_replay`

Replay Failed Deliveries · Write

Replay failed deliveries. Queues redelivery of deliveries that failed. The window runs from `since` (default: the last 24 hours) to `until`, and events the endpoint already received successfully are skipped, so a replay never double-delivers.
Returns an empty response on success (HTTP 202).
Needs webhook_id from bird_webhooks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `since` (`string`, optional): Replay events whose delivery attempt failed at or after this timestamp. The bound is inclusive and applies to attempt time, not to when the event occurred, so a retry that trailed its event by a day falls in the window by the hour it was attempted. Defaults to 24 hours before the request when omitted. Attempts are retained for three days, so that is the oldest history a replay reaches: an earlier `since` widens the window without recovering anything older. Example: 2026-05-07T00:00:00Z
- `until` (`string`, optional): Replay events whose delivery attempt failed at or before this timestamp, on the same attempt-time bound as `since`. Omitted, it resolves to the time of the request. Example: 2026-05-07T23:59:59Z

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_webhook_secret_rotate`

Rotate Webhook Signing Secret · Write

Rotate webhook signing secret. Generates a new signing secret for the endpoint and returns it exactly once: store it immediately, it cannot be retrieved after this response.
Returns an object with secret.
Needs webhook_id from bird_webhooks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_webhook_test`

Test Webhook with a Sample Event · Write

Send a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency.
Returns an object with kind, status, response_status_code, response_body, response_duration_ms, event_payload, error, field, client_certificate.
Needs webhook_id from bird_webhooks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `event_type` (`string`, optional): Event type to simulate. Any type from the event catalog is accepted, whether or not the endpoint subscribes to it; an unknown type returns a `422`. When omitted, the endpoint's first subscribed event type is used. Example: email.delivered
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_webhook_update`

Update Webhook Endpoint · Write

Update the webhook endpoint. Only the fields you send change: `events` replaces the whole subscription set, and `status` pauses or re-enables delivery.
Returns an object with id, url, description, filter, events, status, destination, next, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs webhook_id from bird_webhooks_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `description` (`string`, optional): Human-readable label for this endpoint, up to 256 characters. Example: Updated webhook endpoint
- `destination` (`object`, optional): Changes to how deliveries are built, shaped as at creation. Only a `connector` destination takes `connector`; on any other endpoint it returns a `422`. Omit to keep the destination. Example: {"type": "webhook", "connector": {"connector_id": "claude_managed_agents", "action": "trigger_run"}}
- `events` (`array`, optional): Replaces all event subscriptions with this list. Omit to keep the current set. Types outside the event catalog return a `422`. Example: ["email.delivered", "email.bounced", "email.complained"]
- `filter` (`object`, optional): Replace the mailbox scope. Omit to keep it, or send null to include all resources. Scoped endpoints accept only email_mailbox events. Example: {"mailbox_id": "mbx_01kr97a6rje4wbe5z40wxdfcy9"}
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `status` (`string`, optional): `paused` stops all deliveries; `active` re-enables a paused endpoint. Omit to leave the status unchanged. Events that fire while paused are not delivered and a replay cannot recover them, because they were never attempted; after re-enabling, Replay failed deliveries reaches only the deliveries that failed before the pause. A `degraded` endpoint cannot be reset through this field: it returns to `active` automatically once deliveries succeed again. Example: active. One of: `active`, `paused`.
- `url` (`string`, optional): Replacement delivery URL. Same rules as at creation: HTTPS, at most 2048 characters, and the host must be publicly reachable (private, loopback, and link-local addresses return a `422`). Omit to keep the current URL. A connector endpoint's URL comes from its connector and cannot be replaced: any value returns a `422`. Example: https://example.com/webhook

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_whatsapp_agent_notification_create`

Send WhatsApp Agent a Notification · Write

Send an agent a notification. Tells the agent on the `from` business number that something happened in your systems for one contact, such as a payment landing, an order shipping or an identity check passing.
Returns an object with id, from, to, name, description, payload, status, skipped_reason, error, created_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `description` (`string`, required): What happened, in a sentence the agent can tell the contact. Example: Order 88213 left the warehouse and arrives on Thursday.
- `from` (`string`, required): The business phone number whose agent should act on the notification, in E.164 format (for example `+13124495648`), the same form a message's `from` takes. It must be a number this workspace has connected and that runs an agent. Example: +13124495648
- `name` (`string`, required): Your own name for what happened, such as `payment_received` or `order_shipped`. The agent reads it as the kind of thing that happened, so keep one name per kind. WhatsApp calls this the event type. Example: order_shipped
- `payload` (`string`, required): Details the agent may draw on when it writes to the contact, as one JSON string. WhatsApp passes it to the agent unchanged and does not read it itself. Example: {"order_id":"88213","carrier":"ACME Courier","eta":"2026-10-02"}
- `to` (`string`, required): The contact the notification is about: a phone number in E.164 format (for example `+14155551234`), or the contact's business-scoped user ID (for example `US.13491208655302741918`), the same forms a message's `to` accepts. A phone number is normalized before the call reaches WhatsApp, so spacing does not matter. WhatsApp documents a phone number for this call; a business-scoped user ID is passed through as given. Example: +14155551234
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"description":"<description>","from":"<from>","name":"<name>","payload":"<payload>","to":"<to>"}`

### `bird_whatsapp_conversation_update`

Update WhatsApp Conversation · Write

Update assignment, inbox status, labels, or shared workspace read state.
Returns an object with id, business_phone_number, recipient, inbox_status, control, assigned_to, service_window, last_message, unread_count, labels, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs conversation_id from bird_whatsapp_conversations_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `conversation_id` (`string`, required): Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
- `assigned_to` (`string`, optional): User to assign this conversation to. Pass a workspace member's user ID, `me` for the signed-in user, or null to unassign it. An API key cannot use `me` and receives a `422` response. Example: me
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `inbox_status` (`string`, optional): Whether the conversation needs attention in the workspace inbox. Set it to `resolved` when the work is finished. A new inbound message reopens the same conversation. Changing inbox status preserves message history and does not change the channel's permission to send messages or mark messages read. Example: open. One of: `open`, `resolved`.
- `labels` (`array`, optional): Labels from your workspace's label list. On update, this replaces the full set; pass an empty array to clear every label. Labels do not change read state or inbox status. A name matches the workspace's labels in any casing: adding "Urgent" where the workspace has "urgent" applies "urgent", and responses return the workspace's spelling. A name the workspace doesn't have yet becomes a new label. It must contain 1 to 64 characters, with no commas, control characters, or leading or trailing whitespace, and can't take the workspace past its limit of 100 labels. A new label can't use a reserved name: `all`, `archive`, `archived`, `assigned`, `blocked`, `closed`, `deleted`, `draft`, `drafts`, `flagged`, `important`, `inbox`, `junk`, `muted`, `none`, `open`, `outbox`, `pinned`, `read`, `scheduled`, `sent`, `snoozed`, `spam`, `starred`, `trash` or `unread`, in any casing. Example: ["billing"]
- `read` (`string`, optional): Mark received inbound messages with created_at at or before this timestamp as read in the shared workspace inbox. Messages sharing the timestamp are included together. Later arrivals remain unread until another read update. This does not send a read receipt to the customer or change inbox status. Omit to leave read state unchanged. Example: 2026-01-15T09:30:00Z

Example input: `{"conversation_id":"<conversation_id>"}`

### `bird_whatsapp_group_create`

Create WhatsApp Group · Write

Create a WhatsApp group administered by one of your business numbers.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Use this to add a new one. Use bird_whatsapp_group_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subject` (`string`, required): The group's name, shown to participants and to anyone who opens the invite link. Surrounding whitespace is trimmed. Example: New Purchase Inquiry
- `whatsapp_number_id` (`string`, required): The business number that will own and administer the group, as its id in `GET /v1/whatsapp/numbers`. It must be a number your workspace can send from, and WhatsApp must have granted it Official Business Account status; a number without that status returns a `412` `WhatsAppGroupsNotEligible`. The number cannot be changed afterwards, and every message to the group is sent from it. Example: wan_01krdgeqcxet5s7t44vh8rt9mg
- `description` (`string`, optional): The group's description, shown alongside the subject. Example: Jim would like to learn about new car purchase options for current year models.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `join_approval_mode` (`string`, optional): Whether opening the invite link joins the group outright, or raises a join request for you to approve. Defaults to `auto_approve`. It cannot be changed once the group exists. Example: auto_approve. One of: `auto_approve`, `approval_required`.

Example input: `{"subject":"<subject>","whatsapp_number_id":"<whatsapp_number_id>"}`

### `bird_whatsapp_group_invite_link_rotate`

Rotate WhatsApp Group's Invite Link · Write

Issue a new invite link for the group. Every link issued before stops working, so anyone still holding one cannot join.
Returns an object with invite_link.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `group_id` (`string`, required): ID of the group whose invite link is being replaced. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>"}`

### `bird_whatsapp_group_join_requests_approve`

Approve WhatsApp Group Join Requests · Write

Approve the named join requests, up to 50 in one call.
Returns an object with decided, failed.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `group_id` (`string`, required): ID of the group whose join requests are being decided. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `join_request_ids` (`array`, required): The join requests to act on, as returned by `GET /v1/whatsapp/groups/{group_id}/join-requests`. Each is decided on its own, so one can fail while the rest succeed. An ID that names no waiting request returns a `422` `WhatsAppGroupJoinRequestNotFound`. The 50 is Bird's own request bound, not a WhatsApp one: how many people the group can hold does not limit how many can queue at its link, so a rejection sweep is not held to the size of the group it is refusing entry to. Example: ["wgj_01krdgeqcxet5s7t44vh8rt9mg"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>","join_request_ids":["wgj_01krdgeqcxet5s7t44vh8rt9mg"]}`

### `bird_whatsapp_group_join_requests_reject`

Reject WhatsApp Group Join Requests · Write

Reject the named join requests, up to 50 in one call.
Returns an object with decided, failed.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `group_id` (`string`, required): ID of the group whose join requests are being decided. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `join_request_ids` (`array`, required): The join requests to act on, as returned by `GET /v1/whatsapp/groups/{group_id}/join-requests`. Each is decided on its own, so one can fail while the rest succeed. An ID that names no waiting request returns a `422` `WhatsAppGroupJoinRequestNotFound`. The 50 is Bird's own request bound, not a WhatsApp one: how many people the group can hold does not limit how many can queue at its link, so a rejection sweep is not held to the size of the group it is refusing entry to. Example: ["wgj_01krdgeqcxet5s7t44vh8rt9mg"]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>","join_request_ids":["wgj_01krdgeqcxet5s7t44vh8rt9mg"]}`

### `bird_whatsapp_group_pinned_message_create`

Pin Message in a WhatsApp Group · Write

Pin one of the group's messages at the top of its chat, where it stays for the number of days you give, from 1 to 30.
Returns an object with message_id, pinned_until.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `group_id` (`string`, required): ID of the group to pin a message in. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `message_id` (`string`, required): The message to pin. It has to be one this group carries: a message in another group, or a one-to-one message, returns a `422` `WhatsAppMessageNotInGroup`. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `duration_days` (`integer`, optional): How many days the message stays pinned before WhatsApp unpins it, from 1 to 30. Example: 7
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>","message_id":"<message_id>"}`

### `bird_whatsapp_group_update`

Update WhatsApp Group · Write

Change what participants see at the top of the group: its subject, its description, and its picture.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Only the fields you pass change; omitted fields keep their current values.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `group_id` (`string`, required): ID of the group to change. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `description` (`string`, optional): A new description for the group. Send `null` to clear it; an empty string is a `422` rather than a second way to clear. Example: Discuss the latest timepieces and share reviews.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `profile_picture_url` (`string`, optional): A new picture for the group, naming a file in your workspace's media library. WhatsApp takes a square JPEG of at least 192 by 192 pixels and up to 5 MB; anything else returns a `422`. Sending `null` clears the picture Bird stores, and an empty string is a `422` rather than a second way to clear it; WhatsApp has no operation for removing a group's photo, so the one participants see stays until another picture replaces it. Example: https://media.example.com/whatsapp/groups/square.jpg
- `subject` (`string`, optional): A new name for the group. Participants see the change in the group's chat. Example: Watch Enthusiasts

Example input: `{"group_id":"<group_id>"}`

### `bird_whatsapp_keyword_rule_create`

Create WhatsApp Keyword Rule · Write

Create a keyword rule. Use it to replace the reply Bird sends for `opt_out` or `opt_in`, or to add keywords your customers actually type.
Returns an object with id, scope, operation, country, waba, keywords, effective_keywords, reply, created_at, updated_at.
Use this to add a new one. Use bird_whatsapp_keyword_rule_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, required): What Bird does when an inbound message matches the rule. - `opt_out` records that the sender no longer consents to receive any messages from your WhatsApp Business Account, including transactional ones. Typing the word is the person's own statement, so it covers everything, unlike WhatsApp's built-in marketing opt-out control, which stops marketing alone. - `opt_in` records that they consent again. A rule's operation is fixed once created, and a keyword belongs to exactly one operation, so a keyword Bird ships for `opt_out` cannot be reused for `opt_in`. Closed on the write side: an operation Bird does not answer is rejected here rather than stored as a rule that never fires. The read side is open, because Bird can gain an operation without a new API version. Example: opt_out. One of: `opt_in`, `opt_out`.
- `country` (`string`, optional): The country this rule applies in, as an ISO 3166-1 alpha-2 code. It matches the country of the person who messaged you, worked out from their phone number. Omit it to cover everyone, which is what Bird's own rules do. Example: US
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `keywords` (`array`, optional): Extra keywords to match, on top of the ones Bird already ships for this operation. Omit to keep Bird's keywords and change only the reply, including keywords Bird adds later. You cannot remove one of Bird's keywords, and a keyword Bird has bound to the other operation cannot be reused here. Example: ["no more texts", "remove me"]
- `reply` (`string`, optional): The message to send back when a keyword matches. Omit it to send nothing. Example: You're off the list. ACME Courier won't message you again.
- `waba` (`string`, optional): Limit the rule to one WhatsApp Business Account, identified by its WhatsApp-issued account ID or by the `waa_` ID Bird gives it. Either form resolves to the same account, and the rule stores and returns the WhatsApp-issued one. Omit it to cover every account in your workspace. The account must be one of yours. Example: 102290129340398

Example input: `{"operation":"opt_in"}`

### `bird_whatsapp_keyword_rule_update`

Update WhatsApp Keyword Rule · Write

Change the reply or the added keywords of a rule you created.
Returns an object with id, scope, operation, country, waba, keywords, effective_keywords, reply, created_at, updated_at.
Only the fields you pass change; omitted fields keep their current values.
Needs id from bird_whatsapp_keyword_rules_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the keyword rule, as returned by the list operation. Bird's own rules and yours share one ID space. Example: wkr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `keywords` (`array`, optional): Replaces the extra keywords this rule matches, on top of the ones Bird ships. Send an empty array to keep Bird's keywords only. Omit to leave the current ones unchanged. Example: ["no more texts"]
- `reply` (`string`, optional): Replaces the message sent back when a keyword matches. Set it to null to send nothing. Omit to leave it unchanged. Example: You're off the list. ACME Courier won't message you again.

Example input: `{"id":"<id>"}`

### `bird_whatsapp_message_reaction_set`

React to a WhatsApp Message · Write

Place an emoji reaction on a message this workspace received, the same way tapping and holding a message in WhatsApp does.
Returns an object with id, emoji.
The body replaces this subresource in full.
Needs message_id from bird_whatsapp_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `emoji` (`string`, required): The emoji to place, as the character itself. Replaces your existing reaction on this message if you have one. To take a reaction back entirely, delete it rather than sending an empty value. WhatsApp takes exactly one emoji, so a value carrying more than one is refused with a `422` rather than sent. The length cap is generous because a single joined emoji is many code points: a couple-kissing one carrying two skin tones is ten, which is why the cap alone cannot express the limit. Example: 👍
- `message_id` (`string`, required): ID of the message to react to, as returned in the `id` field of the message. Must be a message this workspace received. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"emoji":"<emoji>","message_id":"<message_id>"}`

### `bird_whatsapp_message_read_receipt_send`

Mark WhatsApp Message as Read · Write

Mark an inbound WhatsApp message as read, showing the contact the blue ticks.
Returns an object with typing_indicator.
Needs message_id from bird_whatsapp_messages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `message_id` (`string`, required): ID of the inbound message to acknowledge. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `typing_indicator` (`boolean`, optional): Show a typing indicator to the contact as well as marking the message read. WhatsApp clears it when you send your next message, or after 25 seconds, whichever comes first. Only ask for one if you are about to reply. Example: true

Example input: `{"message_id":"<message_id>"}`

### `bird_whatsapp_message_send`

Send WhatsApp Message · Write

Send a WhatsApp message to a phone number: an approved template (required to start a conversation) or, inside the 24-hour customer service window, free-form text, media, location, contacts, interactive or reaction content.
Returns the accepted message with id, status, to, from and type; delivery status advances asynchronously.
Use this to message one WhatsApp user. Use bird_whatsapp_message_get to follow delivery and bird_whatsapp_conversation_messages_list to read a thread.
Templates come from bird_whatsapp_templates_list; sending numbers from bird_whatsapp_numbers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `to` (`string`, required): Recipient E.164 number, business-scoped user ID (BSUID, such as `US.13491208655302741918`), or group ID (such as `wag_01krdgeqcxet5s7t44vh8rt9mg`). OTP templates require a phone number. For replies, use the inbound sender identity and receiving business number. Example: +15551234567
- `audio` (`object`, optional): Free-form audio; requires an open customer service window. Example: {"url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true}
- `contact_cards` (`array`, optional): Up to five cards. Each name needs `formatted_name` and another name part. Requires an open customer service window. Example: [{"name": {"formatted_name": "Barbara J. Johnson", "first_name": "Barbara", "last_name": "Johnson"}, "phone_numbers": [{"phone_number": "+16505551234", "type": "Mobile"}]}]
- `document` (`object`, optional): Free-form document; requires an open customer service window. Example: {"url": "https://cdn.example.com/invoices/a1b2c3.pdf", "caption": "Your invoice for order A1B2C3", "filename": "invoice-a1b2c3.pdf"}
- `from` (`string`, optional): Connected E.164 number owned by this workspace; for authored templates, use the same WhatsApp Business Account. Omit for Bird-managed templates and groups; required otherwise. Example: +13124495648
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `image` (`object`, optional): Free-form image; requires an open customer service window. Example: {"url": "https://cdn.example.com/receipts/a1b2c3.png", "caption": "Your receipt for order A1B2C3"}
- `in_reply_to_message_id` (`string`, optional): Message to quote, from this conversation (`to` and `from`) within the last 15 days. Example: wam_01kya19eknftrs2s6p82asmvnh
- `interactive` (`object`, optional): Reply buttons, a list, a link button, media cards, or a location/contact request. Requires an open customer service window; unsupported for groups. Example: {"type": "button", "header": {"type": "image", "url": "https://cdn.example.com/banners/workshop.png"}, "body_text": "Your gardening workshop is scheduled for 9am tomorrow. Use the buttons if you need to reschedule.", "footer_text": "Lucky Shrub, your gateway to succulents", "buttons": [{"type": "quick_reply", "quick_reply": {"slug": "change-booking", "text": "Change"}}, {"type": "quick_reply", "quick_reply": {"slug": "cancel-booking", "text": "Cancel"}}]}
- `location` (`object`, optional): Free-form location; requires an open customer service window. Example: {"latitude": 37.7955, "longitude": -122.3937, "name": "Ferry Building", "address": "1 Ferry Building, San Francisco, CA 94111"}
- `metadata` (`object`, optional): Per-message JSON context, such as internal IDs, returned on reads. Maximum 2 KB serialized. Use `tags` for filterable labels. Example: {"key": "value"}
- `reference` (`string`, optional): Identifier matched exactly by the message list's `reference` filter; returned on reads and webhooks. May be shared by multiple messages. Put non-searchable context in `metadata`. Example: INV-1234
- `sticker` (`object`, optional): Free-form sticker; requires an open customer service window. Example: {"url": "https://cdn.example.com/stickers/thumbs-up.webp"}
- `tags` (`array`, optional): Up to 20 `{name, value}` labels, filterable by name. Use for low-cardinality dimensions such as category; put other context in `metadata`. Example: [{"name": "category", "value": "welcome"}]
- `template` (`object`, optional): Required outside the customer service window. Groups accept workspace-authored, non-authentication templates only. Example: {"slug": "bird_delivery_update", "parameters": {"ref": "A1B2C3D4", "date": "10 Jul 2026"}}
- `text` (`object`, optional): Free-form text; requires an open customer service window. Example: {"body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true}
- `video` (`object`, optional): Free-form video; requires an open customer service window. Example: {"url": "https://cdn.example.com/unboxing.mp4", "caption": "How to set it up"}

Example input: `{"to":"<to>"}`

### `bird_whatsapp_suppression_create`

Create WhatsApp Suppression · Write

Manually adds a WhatsApp address to the suppression list with reason `manual`.
Returns an object with id, address, waba, reason, origin, applies_to, source_whatsapp_id, ended_at, ended_reason, created_at.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `address` (`string`, required): WhatsApp address to suppress. For a phone number, supply canonical E.164 with a leading plus sign, such as `+5511977670804`. A value that is not a valid phone number returns a `422`. Example: +5511977670804
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `waba` (`string`, optional): Limit the suppression to messages sent from this WhatsApp Business Account, identified by its WhatsApp-issued account ID. Omit it to block the address for the whole workspace, whichever account sends. Example: 102290129340398

Example input: `{"address":"<address>"}`

### `bird_whatsapp_template_create`

Create WhatsApp Message Template · Write

Create a WhatsApp message template. Supply `languages` to seed its first draft in the same call, or omit it to create the template alone and add content through the version and language paths.
Returns an object with id, slug, slug_editable, name, description, scope, waba, category, status, default_language, on_missing_language, language_source_required and more.
Use this to add a new one. Use bird_whatsapp_template_update to change an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `category` (`string`, required): The category Meta reviews the template under. Required, because Meta demands one on every template it holds and it determines what a send costs. There is no default. Meta can recategorize a template after review; the per-language summary reports what it actually holds. Example: utility. One of: `authentication`, `utility`, `marketing`.
- `default_language` (`string`, required): The language a send uses when it names none, and the last resort when a requested language is unavailable. When `languages` is supplied it must be one of its keys. Example: en
- `slug` (`string`, required): The template's workspace-unique handle, and what a send references. Editable only before the first submission. The `bird_` prefix is reserved for our built-in templates and is rejected. Meta's own template name is derived from this handle, so the handle itself is validated against the charset Meta accepts. Example: order_update
- `waba` (`string`, required): The WhatsApp Business Account to author this template on. A template belongs to one account at Meta and is reviewed, approved and sent under it, so every create names the account explicitly. It must be an account connected to this workspace. Example: 102290129340398
- `description` (`string`, optional): What the template is for. Free text. Example: Sent when a customer's order ships.
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `language_source_required` (`boolean`, optional): Whether a send has to name a language. Set it to have a send that names none rejected, leaving the default language for sends that ask for it. Example: false
- `languages` (`object`, optional): Optional seed for the template's first draft, keyed by BCP-47 language tag. Supplying it opens the draft and writes every language in one transaction: any invalid entry fails the whole create, leaving no template behind. Tags are canonicalised, so `pt-br` lands as `pt-BR`, and two keys canonicalising to one tag are rejected. Omit it to create the template with no draft, and add content later through the version and language paths. Nothing here reaches Meta: content is submitted, never created. Example: {"en": {"components": [{"type": "body", "text": "Your order {{order_id}} has shipped.", "example_parameters": [{"type": "text", "name": "order_id", "text": "A-4192"}]}]}}
- `name` (`string`, optional): The template's display name, shown wherever the template is listed. Free text, changeable at any time. Defaults to the slug when omitted. Example: Order update
- `on_missing_language` (`string`, optional): How a send behaves when it asks for a language this template does not carry. Defaults to `fail`: a WhatsApp send that silently fell back would deliver approved copy the recipient did not expect, at a price the sender did not choose. Example: fallback. One of: `fallback`, `fail`.

Example input: `{"category":"authentication","default_language":"<default_language>","slug":"<slug>","waba":"<waba>"}`

### `bird_whatsapp_template_draft_create`

Create WhatsApp Template Draft · Write

Open the template's draft, seeded from the newest submitted version, or an empty draft if the template has none.
Returns an object with id, template_id, version_number, submitted_at, variables, languages, created_at.
Needs template_ref from bird_whatsapp_templates_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"template_ref":"<template_ref>"}`

### `bird_whatsapp_template_duplicate`

Duplicate WhatsApp Message Template · Write

Duplicate a message template. Copies a template into a new one holding the source's current content as an open draft.
Returns an object with id, slug, slug_editable, name, description, scope, waba, category, status, default_language, on_missing_language, language_source_required and more.
Needs template_ref from bird_whatsapp_templates_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `waba` (`string`, required): The WhatsApp Business Account the copy is created on. A template belongs to one account at Meta. Meta reviews, approves, and sends it under that account. The copy therefore names its account rather than taking the source's. A built-in template's account is not one you can submit against. It must be an account connected to this workspace. Example: 102290129340398
- `default_language` (`string`, optional): The copy's default language, which must be one of the languages the copy carries. Omitted, the copy keeps the source's default when `include_languages` still carries it. Otherwise it takes the first of the copy's languages sorted by canonical tag, which is the order the copy stores them in, not the order `include_languages` listed them. Example: pt-BR
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `include_languages` (`array`, optional): The languages the copy carries, when it should carry only some of them. Every entry must be a language the source holds. A copy narrows the set it inherits, it never adds to it. Omitted, the copy takes all of the source's languages. Example: ["pt-BR", "es-ES"]
- `name` (`string`, optional): The copy's display name. Inherited from the source when omitted. Example: sk-test-sample
- `slug` (`string`, optional): The copy's handle. The server assigns one when omitted. A `bird_` slug is rejected, and one already in use is a conflict. Example: acme_order_update

Example input: `{"template_ref":"<template_ref>","waba":"<waba>"}`

### `bird_whatsapp_template_language_edits_discard`

Discard WhatsApp Language's Draft Edits Back to Its Submitted Copy · Write

Restore one language of the template's draft to the copy the draft was branched from, discarding the edits made to it since.
Returns an object with language, revision, content_hash, updated_at.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list; language from bird_whatsapp_template_version_languages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `language` (`string`, required): The language, as a BCP-47 tag. Case and separator variance is accepted and normalised, and the canonical form is returned. Example: nl-BE
- `template_ref` (`string`, required): The template: its id (`wat_…`) or its slug. A value that parses as a `wat_` id is treated as one; anything else is a slug. Slugs on this channel can spell a typed id, so the two are told apart by parsing the value rather than by its character set. Example: bird_otp
- `version_id` (`string`, required): Version ID. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `revision` (`integer`, optional): The revision you last read for this language, making the discard a compare-and-set: a mismatch is refused with a conflict, leaving an edit you have not seen in place. Omit it for last-write-wins, which is what a single writer wants. Supplying it for a language the draft no longer holds is also refused with a conflict rather than recreating the language. Example: 4

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_language_set`

Upsert WhatsApp Language's Content · Write

Write one language of the template's draft, creating it when absent (`201`) and replacing it when present (`200`).
Returns an object with language, revision, content_hash, updated_at.
The body replaces this subresource in full.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list; language from bird_whatsapp_template_version_languages_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language, as a BCP-47 tag. Case and separator variance is accepted and normalised, and the canonical form is returned. Example: nl-BE
- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
- `components` (`array`, optional): The template's content blocks for this language. Header, footer and buttons are optional. Every variable needs an example value, which is what Meta reviews against. May be omitted or empty on a draft; a body block is required before the language can be submitted. Example: [{"type": "body", "text": "Hello"}]
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `message_send_ttl_seconds` (`integer`, optional): How long WhatsApp keeps trying to deliver a message from this language, in seconds. WhatsApp drops a message it cannot deliver in that time. Omit it to keep the current value. Send `null` to use WhatsApp's default: 10 minutes for authentication, 30 days for utility and marketing. A new language written without it uses WhatsApp's default. The range depends on the language's `category`: 30 to 900 for authentication, 30 to 43200 for utility, and 43200 to 1209600 for marketing. A value outside 30 to 1209600 fails request validation; one inside it but outside the category's range fails with `WhatsAppTemplateTTLOutOfRange`. On a marketing template, the value applies while the business account's `marketing_messages_onboarding_status` is `onboarded`. Changing only this value updates WhatsApp without a new review. Example: 86400
- `optimization_spec` (`object`, optional): This language's maximum price. Omit it to keep the current one. A new language written without it uses Meta's standard rate. Send `null` to return to the standard rate. Changing only the price updates Meta without a new review. A send at a maximum price needs the business account's `marketing_messages_onboarding_status` to be `onboarded`. Otherwise it fails with WhatsApp error 131061. Example: {"bid_amount": 5000, "bid_strategy": "lowest_cost_with_bid_cap"}
- `parameter_bindings` (`object`, optional): Liquid that computes this language's send values from the send's `template.parameters`. Omit it to keep the current bindings, and send `null` to remove them. Changing only the bindings never needs a new review. Example: {"full_name": "{{ first_name | append: ' ' | append: last_name }}", "header_url": "https://cdn.example.com/inv/{{ order_id }}.pdf"}
- `revision` (`integer`, optional): The revision you last read for this language, making the write a compare-and-set: a mismatch is refused with a conflict, leaving an edit you have not seen in place. Omit it for last-write-wins, which is what a single writer wants. Supplying it for a language that does not exist is also refused with a conflict rather than recreating the language. Inside a template's initial languages seed on create, a value here is refused, since no prior revision exists yet to compare against. Example: 4

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_update`

Update WhatsApp Message Template · Write

Update a template's metadata. The slug can change only before the first submission.
Returns an object with id, slug, slug_editable, name, description, scope, waba, category, status, default_language, on_missing_language, language_source_required and more.
Only the fields you pass change; omitted fields keep their current values.
Needs template_ref from bird_whatsapp_templates_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `default_language` (`string`, optional): The language a send falls back to, and the one language the template is required to carry. Repointing it at a language the draft does not hold is refused, the same way removing the current default is: add the language first. Example: en
- `description` (`string`, optional): What the template is for. Send `null` to clear it. Example: Created by the Scalekit connector
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `language_source_required` (`boolean`, optional): Whether a send has to name a language. Example: false
- `name` (`string`, optional): The template's display name. Editable at any time; it is not what a send references. Example: Order update
- `on_missing_language` (`string`, optional): How a send behaves when it asks for a language this template does not carry. Omitting it leaves the template's current setting alone. The `fail` default belongs to a create, and a partial update never reapplies it. Example: fallback. One of: `fallback`, `fail`.
- `slug` (`string`, optional): A new workspace-unique handle. Editable only before the first submission. After a change, the old slug no longer resolves; the template ID stays the same. Example: welcome-email

Example input: `{"template_ref":"<template_ref>"}`

### `bird_whatsapp_template_version_submit`

Submit WhatsApp Template Version for Review · Write

Submit a template version for review. Validates the template draft before freezing it. If validation fails, the API returns `200 OK` with every problem across all languages and creates no version.
Returns an object with valid, errors, version, next.
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `validate_only` (`boolean`, optional): Check the draft without submitting it. Every language is checked and every problem reported, but nothing is frozen and nothing is sent to WhatsApp. A clean result does not guarantee WhatsApp approval: WhatsApp offers no way to ask in advance, so it can still refuse a submission these checks passed. Use a different idempotency key for the validation and the submission. Reusing one key with different request bodies is rejected. Example: false

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_amb_business_account_delete`

Disconnect Apple Business Account · Destructive

Stop new and queued sends while retaining the account, Apple UUID, approval, credentials and history.
Returns an empty response on success (HTTP 204).
Needs business_account_id from bird_amb_business_accounts_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `business_account_id` (`string`, required): ID of the Apple Messages for Business record to disconnect, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"business_account_id":"<business_account_id>"}`

### `bird_amb_routing_rule_delete`

Delete Apple Messages for Business Routing Rule · Destructive

Delete a routing rule. A conversation already routed by it keeps its queue; only newly created or reopened conversations stop matching it.
Returns an empty response on success (HTTP 204).
Needs routing_rule_id from bird_amb_routing_rules_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `routing_rule_id` (`string`, required): ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"routing_rule_id":"<routing_rule_id>"}`

### `bird_amb_suppression_delete`

End Apple Messages for Business Suppression · Destructive

End an Apple Messages for Business suppression. Ends a manual suppression created by a user or API caller, retaining the episode and the time it ended.
Returns an empty response on success (HTTP 204).
Needs suppression_id from bird_amb_suppressions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression episode to retrieve or end. Example: asp_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_asset_delete`

Remove Asset from the Media Library · Destructive

Remove an asset from the library. The asset is excluded from default list results, but remains readable by ID or with the `deleted` list filter unless blocked by staff.
Returns an empty response on success (HTTP 204).
Needs asset_id from bird_assets_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"asset_id":"<asset_id>"}`

### `bird_asset_folder_delete`

Delete Folder and Move Its Contents Up · Destructive

Delete a folder. Its subfolders and its assets move up one level, to the folder it sat in, so nothing is removed from the library as a side effect and no URL changes.
Returns an empty response on success (HTTP 204).
Needs folder_id from bird_asset_folders_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `folder_id` (`string`, required): ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"folder_id":"<folder_id>"}`

### `bird_audience_contact_remove`

Unassign Contact from an Audience · Destructive

Remove a contact's membership in an audience. The contact itself is not deleted and remains a member of any other audiences.
Returns an empty response on success (HTTP 204).
Needs audience_id from bird_audiences_list; contact_id from bird_audience_contacts_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience to remove the contact from. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `contact_id` (`string`, required): ID of the contact to remove. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"audience_id":"<audience_id>","contact_id":"<contact_id>"}`

### `bird_audience_delete`

Delete Audience · Destructive

Delete an audience and its memberships. Contacts themselves are not deleted.
Returns an empty response on success (HTTP 204).
Needs audience_id from bird_audiences_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `audience_id` (`string`, required): ID of the audience to delete. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"audience_id":"<audience_id>"}`

### `bird_compliance_attachment_delete`

Delete Registration Attachment · Destructive

Delete an uploaded registration attachment. This succeeds only while the file is unused.
Returns an empty response on success (HTTP 204).
Needs attachment_id from bird_compliance_attachments_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `attachment_id` (`string`, required): Attachment ID. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"attachment_id":"<attachment_id>"}`

### `bird_compliance_identity_delete`

Delete Identity · Destructive

Delete an identity. Retires a party so it no longer appears in your list or prefills a registration.
Returns an empty response on success (HTTP 204).
Needs identity_id from bird_compliance_identities_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `identity_id` (`string`, required): Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"identity_id":"<identity_id>"}`

### `bird_contact_delete`

Delete Contact · Destructive

Delete a contact permanently and removes it from every audience it belongs to.
Returns an empty response on success (HTTP 204).
Needs contact_id from bird_contacts_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, required): ID of the contact to delete. Example: con_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"contact_id":"<contact_id>"}`

### `bird_email_broadcast_delete`

Delete Email Broadcast · Destructive

Delete a draft broadcast. Only a draft can be deleted.
Returns an empty response on success (HTTP 204).
Needs broadcast_id from bird_email_broadcasts_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `broadcast_id` (`string`, required): Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"broadcast_id":"<broadcast_id>"}`

### `bird_email_competitive_watchlist_brand_delete`

Remove Email Competitor Brand from the Watchlist · Destructive

Remove a competitor brand from the watchlist. Takes a brand off the workspace's watchlist and frees its place in the organization's allowance.
Returns an empty response on success (HTTP 204).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `watchlist_brand_id` (`string`, required): The watchlist entry to act on. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"watchlist_brand_id":"<watchlist_brand_id>"}`

### `bird_email_domain_delete`

Delete Sending Domain · Destructive

Remove the domain and revokes its sender authorization.
Returns an empty response on success (HTTP 204).
Needs domain_id from bird_email_domains_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `domain_id` (`string`, required): ID of the domain to delete. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_domain_tracking_release`

Release Link Tracking Configuration · Destructive

Remove the link tracking configuration from this domain and releases the claim on its tracking subdomain, so another organization can configure the same hostname.
Returns an object with default_ip_pool_id, id, workspace_id, domain, vendor, status, settings, next, dkim, capabilities, receiving, dns_records and more.
Needs domain_id from bird_email_domains_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `domain_id` (`string`, required): ID of the domain to release tracking for. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"domain_id":"<domain_id>"}`

### `bird_email_inbound_address_delete`

Delete Email Inbound Address · Destructive

Delete an inbound address. Mail forwarded to the address after deletion is no longer received.
Returns an empty response on success (HTTP 204).
Needs inbound_address_id from bird_email_inbound_addresses_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `inbound_address_id` (`string`, required): Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"inbound_address_id":"<inbound_address_id>"}`

### `bird_email_inbound_route_delete`

Delete Email Inbound Route · Destructive

Delete an inbound route. Mail the route matched falls through to the next route in priority order, or, when nothing matches, is received as a plain received email.
Returns an empty response on success (HTTP 204).
Needs route_id from bird_email_inbound_routes_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `route_id` (`string`, required): Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"route_id":"<route_id>"}`

### `bird_email_suppression_delete`

Delete Email Suppression · Destructive

Permanently deletes the selected suppression record.
Returns an empty response on success (HTTP 204).
Needs suppression_id from bird_email_suppressions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression record, as returned when the suppression was created or listed. Example: sup_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_email_template_delete`

Delete Email Template · Destructive

Delete the template from authoring and lists. The slug becomes available for reuse in the workspace, and the deletion cannot be undone.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_email_templates_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Write operations (update, delete) accept a workspace template only, because a `system` template is immutable. Example: bird_welcome
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"template_ref":"<template_ref>"}`

### `bird_email_template_language_delete`

Delete Email One Language from a Draft · Destructive

Remove one language from the template's draft, along with its content.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list; language from bird_email_template_version_languages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language as a BCP-47 tag. Example: pt-BR
- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_template_version_delete`

Delete Email Template Draft · Destructive

Discard the draft's unsaved work: its content resets to what is currently published (or to a single empty language when nothing has been published yet), so the draft matches what sends actually deliver again.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_email_templates_list; version_id from bird_email_template_versions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here, to its one permanently published version. Discarding a draft requires a workspace template, because a `system` template has no draft and returns `404` `not_found_error`. Example: emt_01krdgeqcxet5s7t44vh8rt9mg
- `version_id` (`string`, required): The version to read or reset. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_email_thread_delete`

Delete Email Thread · Destructive

Delete a thread. Moves the conversation and all of its messages to the trash.
Returns an empty response on success (HTTP 204).
Use bird_email_thread_restore to undo it while that is still possible.
Needs thread_id from bird_email_threads_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `permanent` (`boolean`, optional): Permanently delete the conversation and its messages immediately instead of moving them to the trash. Example: false

Example input: `{"thread_id":"<thread_id>"}`

### `bird_email_thread_message_delete`

Delete Email Message in a Thread · Destructive

Delete a message in a thread. Moves the message to the trash. Trashed messages are permanently deleted after 30 days, or sooner if the mailbox's retention period ends first.
Returns an empty response on success (HTTP 204).
Needs thread_id from bird_email_threads_list; message_id from bird_email_thread_messages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
- `thread_id` (`string`, required): Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
- `permanent` (`boolean`, optional): Permanently delete the message immediately instead of moving it to the trash. Example: false

Example input: `{"message_id":"<message_id>","thread_id":"<thread_id>"}`

### `bird_esim_install_link_delete`

Revoke Hosted Install Link · Destructive

Revoke a hosted install link. Revokes a hosted installation link so it no longer grants access to installation details.
Returns an empty response on success (HTTP 204).
Needs esim_id from bird_esims_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `install_link_id` (`string`, required): Hosted install link ID. Example: eil_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>","install_link_id":"<install_link_id>"}`

### `bird_esim_package_delete`

Remove Data Package · Destructive

Remove a data package and frees capacity under the eSIM's `package_limit`.
Returns an object with id, order_id, offer_id, zone_id, zone_name, countries, status, speed, balance, activated_at, expires_at, price and more.
Needs esim_id from bird_esims_list; package_id from bird_esim_packages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `package_id` (`string`, required): Data package ID. Example: epk_01krdgeqcxet5s7t44vh8rt9mg
- `acknowledge_balance_forfeit` (`boolean`, optional): Confirms you accept that the package's remaining balance is forfeited. Omitted or false while balance remains, the request fails with a conflict error. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>","package_id":"<package_id>"}`

### `bird_esim_release`

Release eSIM · Destructive

Permanently releases an eSIM. This is irreversible: the eSIM can never be installed or used again, any remaining package data balance is forfeited, and release never credits anything back.
Returns an object with subscriber_id, id, status, mode, iccid, phone_number, capabilities, order_id, display_name, installation, packages, zone_balances and more.
Needs esim_id from bird_esims_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `esim_id` (`string`, required): eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
- `acknowledge_balance_forfeit` (`boolean`, optional): Confirms you accept that remaining package balances are forfeited. Omitted or false while unexpired balance remains, the request fails with a conflict error. Example: false
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"esim_id":"<esim_id>"}`

### `bird_mailbox_delete`

Delete Mailbox · Destructive

Delete a mailbox. The address stops receiving mail immediately and enters quarantine.
Returns an empty response on success (HTTP 204).
Use bird_mailbox_restore to undo it while that is still possible.
Needs mailbox_id from bird_mailboxes_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>"}`

### `bird_mailbox_receive_rule_delete`

Delete Email Receive Rule · Destructive

Remove a receive rule from the mailbox. A rule's allow or block action cannot be changed after creation; delete it and create a replacement.
Returns an empty response on success (HTTP 204).
Needs mailbox_id from bird_mailboxes_list; rule_id from bird_mailbox_receive_rules_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `mailbox_id` (`string`, required): Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
- `rule_id` (`string`, required): Receive-rule identifier. Starts with `erl_`. Example: erl_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"mailbox_id":"<mailbox_id>","rule_id":"<rule_id>"}`

### `bird_number_cancel`

Cancel Dedicated Number · Destructive

Cancel one of your workspace's dedicated numbers at the end of its current billing period.
Returns an object with name, reference, id, kind, number, country_code, number_type, capabilities, status, allocated_at, releases_at, released_at and more.
Needs number_id from bird_numbers_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `number_id` (`string`, required): Identifier of the number to cancel, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"number_id":"<number_id>"}`

### `bird_number_release`

Release Dedicated Number · Destructive

Release one of your workspace's dedicated numbers now and stops its recurring charge.
Returns an empty response on success (HTTP 204).
Needs number_id from bird_numbers_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `number_id` (`string`, required): Identifier of the number to release, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"number_id":"<number_id>"}`

### `bird_preference_delete`

Delete Preference · Destructive

Delete a preference, returning its key to having no record, as if nothing had ever been stated.
Returns an object with applied, transition_id, preference.
Needs preference_id from bird_preferences_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `preference_id` (`string`, required): ID of the preference, as returned when it was recorded or listed. The ID stays stable while the key holds a record; deleting and re-recording the same key mints a new one. Example: prf_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"preference_id":"<preference_id>"}`

### `bird_realtime_app_delete`

Delete Realtime App · Destructive

Permanently deletes the app: disconnects all clients and removes its keys and configuration.
Returns an empty response on success (HTTP 204).
Needs realtime_app_id from bird_realtime_apps_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"realtime_app_id":"<realtime_app_id>"}`

### `bird_realtime_app_key_revoke`

Revoke Realtime App Key · Destructive

Revoke a Realtime app key. Revokes a key immediately and returns it with `revoked_at` set.
Returns an object with id, key, secret, revoked_at, created_at.
Needs realtime_app_id from bird_realtime_apps_list; realtime_app_key_id from bird_realtime_app_keys_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `realtime_app_id` (`string`, required): ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
- `realtime_app_key_id` (`string`, required): ID of the Realtime app key (`rak_` prefix), as returned when the key was created. Example: rak_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"realtime_app_id":"<realtime_app_id>","realtime_app_key_id":"<realtime_app_key_id>"}`

### `bird_sms_keyword_rule_delete`

Delete SMS Keyword Rule · Destructive

Delete a rule you created. Bird's default for that operation and country applies again straight away, so deleting an opt-out rule restores Bird's reply rather than switching opt-out off.
Returns an empty response on success (HTTP 204).
Needs id from bird_sms_keyword_rules_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `bird_sms_messaging_profile_delete`

Delete SMS Messaging Profile · Destructive

Delete a messaging profile and releases its reply numbers and keyword, so another profile can use them and a new profile can reuse the name.
Returns an empty response on success (HTTP 204).
Needs profile_id from bird_sms_messaging_profiles_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `profile_id` (`string`, required): ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"profile_id":"<profile_id>"}`

### `bird_sms_suppression_delete`

Delete SMS Suppression · Destructive

Delete an SMS suppression. Ends a suppression, so the sender reaches the subscriber again.
Returns an empty response on success (HTTP 204).
Needs suppression_id from bird_sms_suppressions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the suppression, as returned when it was created or listed. Example: ssu_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_voice_ring_group_delete`

Delete Voice Ring Group · Destructive

Delete the ring group and its member list. Calls already ringing its members are not affected.
Returns an empty response on success (HTTP 204).
Needs ring_group_id from bird_voice_ring_groups_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ring_group_id` (`string`, required): ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"ring_group_id":"<ring_group_id>"}`

### `bird_voice_ring_group_member_delete`

Remove Voice Member from a Ring Group · Destructive

Remove the user from the ring group. A call already ringing the user is not affected.
Returns an empty response on success (HTTP 204).
Needs ring_group_id from bird_voice_ring_groups_list; user_id from bird_voice_ring_group_members_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ring_group_id` (`string`, required): ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
- `user_id` (`string`, required): ID of the member to remove. Example: usr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"ring_group_id":"<ring_group_id>","user_id":"<user_id>"}`

### `bird_voice_trunk_delete`

Delete Voice SIP Trunk · Destructive

Remove the SIP trunk. Calls already in progress on this trunk are not affected.
Returns an empty response on success (HTTP 204).
Needs trunk_id from bird_voice_trunks_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `trunk_id` (`string`, required): ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"trunk_id":"<trunk_id>"}`

### `bird_voice_trunk_gateway_delete`

Delete Voice SIP Trunk Gateway · Destructive

Remove the gateway. Calls already ringing this address are not affected.
Returns an empty response on success (HTTP 204).
Needs trunk_id from bird_voice_trunks_list; gateway_id from bird_voice_trunk_gateways_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `gateway_id` (`string`, required): ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
- `trunk_id` (`string`, required): ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"gateway_id":"<gateway_id>","trunk_id":"<trunk_id>"}`

### `bird_voice_verified_number_delete`

Delete Voice Verified Number · Destructive

Remove the verified number. After deletion the number can no longer be presented as the outbound caller ID; register and verify it again to reuse it.
Returns an empty response on success (HTTP 204).
Needs verified_number_id from bird_voice_verified_numbers_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `verified_number_id` (`string`, required): ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"verified_number_id":"<verified_number_id>"}`

### `bird_webhook_delete`

Delete Webhook Endpoint · Destructive

Permanently removes the webhook endpoint and stops all deliveries to it, including retries of earlier failed deliveries.
Returns an empty response on success (HTTP 204).
Needs webhook_id from bird_webhooks_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`string`, required): ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"webhook_id":"<webhook_id>"}`

### `bird_whatsapp_group_delete`

Delete WhatsApp Group · Destructive

Delete the group at WhatsApp. Every participant loses access, your business included, and the invite link stops working.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `group_id` (`string`, required): ID of the group to delete. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>"}`

### `bird_whatsapp_group_participant_delete`

Remove Participant from a WhatsApp Group · Destructive

Remove one person from the group. Name them by either identifier the group's `participants` list them under: `bsuid`, which everyone has, or `phone_number`, which is there only when WhatsApp shares it.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `group_id` (`string`, required): ID of the group to remove someone from. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `participant_ref` (`string`, required): The person to remove, named by either identifier the group lists them under: their `bsuid`, or their `phone_number` in E.164 format (`+16505551234`) when WhatsApp gives you one. Pass the value as it reads: percent-encode the leading `+` as `%2B` only when your client does not do that for you. A value naming someone who is not in the group returns a `422` `WhatsAppGroupParticipantNotFound`. Example: +16505551234
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>","participant_ref":"<participant_ref>"}`

### `bird_whatsapp_group_pinned_message_delete`

Unpin Message in a WhatsApp Group · Destructive

Unpin a message in a WhatsApp group. Takes the message off the top of the group's chat before its pin would have expired.
Returns an object with id, whatsapp_number_id, waba, subject, description, status, join_approval_mode, invite_link, participants, participant_count, pinned_messages, profile_picture_url and more.
Needs group_id from bird_whatsapp_groups_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `group_id` (`string`, required): ID of the group to unpin a message in. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
- `message_id` (`string`, required): ID of the message to unpin, as returned in the send response's `id`. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"group_id":"<group_id>","message_id":"<message_id>"}`

### `bird_whatsapp_keyword_rule_delete`

Delete WhatsApp Keyword Rule · Destructive

Delete a rule you created. The next rule in the ladder answers that scope straight away, so Bird's own keywords keep opting people out; the keywords the rule added go with it, and a word only that rule matched stops meaning anything.
Returns an empty response on success (HTTP 204).
Needs id from bird_whatsapp_keyword_rules_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the keyword rule, as returned by the list operation. Bird's own rules and yours share one ID space. Example: wkr_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"id":"<id>"}`

### `bird_whatsapp_message_reaction_delete`

Remove Your Reaction from a WhatsApp Message · Destructive

Remove your reaction from a WhatsApp message. Takes back the reaction this workspace placed on a message, the same way tapping your own reaction in WhatsApp does.
Returns an empty response on success (HTTP 202).
Needs message_id from bird_whatsapp_messages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `message_id` (`string`, required): ID of the message to take your reaction off, as returned in the `id` field of the message. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"message_id":"<message_id>"}`

### `bird_whatsapp_suppression_delete`

End WhatsApp Suppression · Destructive

End a WhatsApp suppression. Ends the suppression, so the address can be messaged again.
Returns an empty response on success (HTTP 204).
Needs suppression_id from bird_whatsapp_suppressions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `suppression_id` (`string`, required): ID of the WhatsApp suppression record to retrieve or end. Example: was_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"suppression_id":"<suppression_id>"}`

### `bird_whatsapp_template_delete`

Delete WhatsApp Message Template · Destructive

Delete a template and every language it holds. Built-in templates cannot be deleted.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_whatsapp_templates_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"template_ref":"<template_ref>"}`

### `bird_whatsapp_template_language_delete`

Delete WhatsApp Language from the Draft · Destructive

Remove one language from the template's draft. The template's default language cannot be removed, and a language under active review at Meta refuses removal until that review finishes.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list; language from bird_whatsapp_template_version_languages_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, required): The language, as a BCP-47 tag. Case and separator variance is accepted and normalised, and the canonical form is returned. Example: nl-BE
- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"language":"<language>","template_ref":"<template_ref>","version_id":"<version_id>"}`

### `bird_whatsapp_template_version_delete`

Delete WhatsApp Template's Open Draft · Destructive

Delete the draft and leaves the template without an open draft.
Returns an empty response on success (HTTP 204).
Needs template_ref from bird_whatsapp_templates_list; version_id from bird_whatsapp_template_versions_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `template_ref` (`string`, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug. Example: bird_otp
- `version_id` (`string`, required): ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
- `idempotency_key` (`string`, optional): Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay. On a supported operation, if idempotency protection is unavailable before execution, the API returns `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with backoff using the same key and request. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c

Example input: `{"template_ref":"<template_ref>","version_id":"<version_id>"}`

## Related

Other Communication connectors ([all 132](/agentkit/connectors/?category=communication)):

- [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools
- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
