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.
- Tools
- 457
- What they doRead · write · destructive
- 252 · 155 · 50252 read155 write50 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Bird connection
In AgentKit > Connections, create a Bird connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts 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.actionsconst connector = 'bird'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'bird_amb_business_accounts_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_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.actionsconnection_name = "bird"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="bird_amb_business_accounts_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Bird credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbird_amb_attachment_getReturn the metadata of an attachment by its `aat_` ID.Read-onlyGet Apple Messages Attachment
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.
Inputs
attachment_idstringrequired- Attachment identifier. Starts with `aat_`. Example: aat_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_business_account_events_listReturn account activity with event time, summary and source metadata, newest first by default.Read-onlyList Apple Business Account Events
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_amb_business_account_getReturn your workspace's Apple Messages for Business record, including its current status with Apple.Read-onlyGet Apple Messages for Business Record
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.
Inputs
business_account_idstringrequired- Bird business account ID (abz_) or Apple business UUID. Both resolve within the current workspace. Example: abz_01jbx7k3m9p2q5r8s4t6v0w1yz
bird_amb_business_account_submissions_listReturn review attempts with frozen evidence for this business, newest first, with fresh private evidence URLs.Read-onlyList Apple Messages for Business Submissions
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_amb_business_accounts_listReturn a paginated list of your workspace's Apple Messages for Business records.Read-onlyList Apple Messages for Business Records
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Possible values: `created_at`. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_amb_channel_settings_getReturn 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.Read-onlyGet Apple Messages for Business Channel Settings
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_conversation_getReturn one conversation, including closed conversations.Read-onlyGet Apple Messages Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_conversation_messages_listReturn the messages in a conversation, newest first, both received and sent.Read-onlyList Apple Messages Messages in a Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
directionstring- Filter to received (`inbound`) or sent (`outbound`) messages. Example: outboundone of
outboundinbound ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_amb_conversation_stats_summary_getReturn one aggregate row of Apple Messages for Business conversation lifecycle counts (`started`, `reopened`, `closed`, `conversations`) for the requested period.Read-onlyGet Aggregate Apple Messages for Business Conversation Statistics
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.
Inputs
comparestring- 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_periodone of
previous_period fromstring- 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
timezonestring- 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
tostring- 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
bird_amb_conversation_stats_timeseries_getGet 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.Read-onlyGet Apple Messages for Business Conversation Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly fromstring- 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
timezonestring- 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
tostring- 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
bird_amb_conversations_listReturn the conversations your business has with customers on Apple Messages for Business, newest first by last message.Read-onlyList Apple Messages Conversations
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.
Inputs
assigned_tostring- 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_idstring- Filter to conversations belonging to this business. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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_idstring- 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_statusstring- Filter by workspace inbox status. Omit to include open and resolved conversations. Example: openone of
openresolved intent_idstring- 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
labelarray- 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"]
limitinteger- Maximum number of items to return per page. Example: 25
queuestring- Filter to conversations in this queue. Pass an empty string to match unrouted conversations, the ones no routing rule has claimed. Example: support
starting_afterstring- 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
statusstring- Filter to conversations with this status. Omit to return both open and closed conversations. Example: openone of
openclosed
bird_amb_inbound_stats_breakdown_getGet inbound Apple Messages for Business statistics for a period grouped by one dimension (dimension): businesses, intents.Read-onlyGet Inbound Apple Messages for Business Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/amb/stats/inbound/. Example: businessesone of
businessesintents fromstring- 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
limitinteger- Maximum number of business rows to return, ranked by received volume descending. Example: 50
timezonestring- 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
tostring- 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
bird_amb_inbound_stats_summary_getReturn one aggregate row of inbound Apple Messages for Business counts for the requested period.Read-onlyGet Aggregate Inbound Apple Messages for Business Statistics
Return one aggregate row of inbound Apple Messages for Business counts for the requested period. Returns an object with period, attribution, received, comparison.
Inputs
comparestring- 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_periodone of
previous_period fromstring- 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
timezonestring- 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
tostring- 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
bird_amb_inbound_stats_timeseries_getGet 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.Read-onlyGet Inbound Apple Messages for Business Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly fromstring- 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
timezonestring- 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
tostring- 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
bird_amb_message_events_listReturn a message's lifecycle events in chronological order, one entry per status transition (`amb.accepted`, `amb.sent`, `amb.send_failed`, `amb.received`).Read-onlyList Apple Messages Events for a Message
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.
Inputs
message_idstringrequired- Message identifier. Starts with `amb_`. Example: amb_01krdgeqcxet5s7t44vh8rt9mg
typestring- Keep only events of this exact type (for example `amb.sent` or `amb.send_failed`). Omit for the full timeline.
bird_amb_message_getReturn a single Apple Messages for Business message: its current status, the content it carries, and failure detail when it failed.Read-onlyGet Apple Messages Message
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.
Inputs
message_idstringrequired- Message identifier. Starts with `amb_`. Example: amb_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_messages_listReturn your business's Apple Messages for Business messages across conversations, newest first, both received and sent.Read-onlyList Apple Messages Messages
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.
Inputs
business_account_idstring- Filter to messages belonging to this business. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
categorystring- Filter to outbound messages sent with this category, exact match. Example: order_update
conversation_idstring- Filter to messages belonging to this conversation. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
created_afterstring- 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_beforestring- 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
directionstring- Filter to received (`inbound`) or sent (`outbound`) messages. Example: outboundone of
outboundinbound ending_beforestring- 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
kindstring- Filter to messages whose content is this shape. Example: textone of
textattachmentrich_linkquick_replylist_pickertime_pickerformapple_payauthenticateimessage_appinteractive limitinteger- Maximum number of items to return per page. Example: 25
referencestring- 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_afterstring- 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
statusstring- Filter to messages with this status. Example: acceptedone of
acceptedsentsend_failedrejectedreceived tagarray- 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.
bird_amb_routing_rule_getReturn 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.Read-onlyGet Apple Messages for Business Routing Rule
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.
Inputs
routing_rule_idstringrequired- ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_routing_rules_listReturn the workspace's Apple Messages for Business routing rules, highest precedence first.Read-onlyList Apple Messages for Business Routing Rules
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.
Inputs
business_account_idstring- Keep only routing rules belonging to this business. Omit to return rules across all businesses in the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_stats_breakdown_getGet outbound Apple Messages for Business statistics for a period grouped by one dimension (dimension): businesses, message kinds, intents, groups, categories, tags, error codes.Read-onlyGet Outbound Apple Messages for Business Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/amb/stats/. Example: businessesone of
businessesmessage-kindsintentsgroupscategoriestagserror-codes fromstring- 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
limitinteger- Maximum number of business rows to return, ranked by accepted volume descending. Example: 50
timezonestring- 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
tostring- 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
bird_amb_stats_summary_getReturn one aggregate row of outbound Apple Messages for Business counts and latency percentiles (`p50`, `p95`, and `p99`) for the requested period.Read-onlyGet Aggregate Outbound Apple Messages for Business Statistics
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.
Inputs
business_account_idstring- 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
categorystring- 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
comparestring- 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_periodone of
previous_period fromstring- 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
groupstring- 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
intentstring- 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_kindstring- 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: textone of
textattachmentrich_linkquick_replylist_pickertime_pickerformapple_payauthenticateimessage_appinteractive tagstring- 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
timezonestring- 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
tostring- 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
bird_amb_stats_timeseries_getGet 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.Read-onlyGet Outbound Apple Messages for Business Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly business_account_idstring- 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
categorystring- 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
fromstring- 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
groupstring- 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
intentstring- 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_kindstring- 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: textone of
textattachmentrich_linkquick_replylist_pickertime_pickerformapple_payauthenticateimessage_appinteractive tagstring- 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
timezonestring- 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
tostring- 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
bird_amb_suppression_getReturn the suppression episode for the given ID, including one that has already ended.Read-onlyGet Apple Messages for Business Suppression
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.
Inputs
suppression_idstringrequired- ID of the suppression episode to retrieve or end. Example: asp_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_suppressions_listReturn 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.Read-onlyList Apple Messages for Business Suppressions
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.
Inputs
addressstring- 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_typestring- Keep only suppressions of this kind. Example: opaque_user_idone of
phone_numberopaque_user_id business_account_idstring- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
reasonstring- Keep only suppressions with this reason. Example: manual
starting_afterstring- 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
bird_amb_template_getReturn one Apple Messages template's metadata, policies, language states, draft revision, and draft and live version IDs.Read-onlyGet Apple Messages Template
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.
Inputs
template_refstringrequired- 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
bird_amb_template_version_getReturn one version with its variables and text in every language.Read-onlyGet Apple Messages Template Version
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.
Inputs
template_refstringrequired- The template's ID (`amt_…`) or slug. Example: order-shipped
version_idstringrequired- The version to read or reset. Example: amv_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_template_version_language_getReturn one language's full text, revision, content hash, and update time.Read-onlyGet Apple Messages Template Version's Language
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.
Inputs
languagestringrequired- The language as a BCP-47 tag. Case and separator differences are accepted and canonicalized. Example: pt-BR
template_refstringrequired- The template's ID (`amt_…`) or slug. Example: order-shipped
version_idstringrequired- The version that holds the language. Example: amv_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_template_version_languages_listReturn the languages a version holds, ordered by canonical language tag, without their text.Read-onlyList Apple Messages Template Version's Languages
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.
Inputs
template_refstringrequired- The template's ID (`amt_…`) or slug. Example: order-shipped
version_idstringrequired- The version whose languages to list. Example: amv_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_template_versions_listReturn a cursor-paginated version history, newest first.Read-onlyList Apple Messages Template's Versions
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.
Inputs
template_refstringrequired- The template's ID (`amt_…`) or slug. Example: order-shipped
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_amb_templates_listReturn Apple Messages templates as a cursor-paginated list.Read-onlyList Apple Messages Templates
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.
Inputs
categorystring- Return templates in this category. Example: transactionalone of
transactionalmarketing content_kindstring- Return templates whose live or draft content is this kind. Example: textone of
textattachmentrich_linkquick_replylist_pickertime_pickerformapple_payauthenticateimessage_appinteractive ending_beforestring- 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
languagestring- Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match. Example: pt-BR
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc qstring- A case-insensitive substring search across slug, name, and description. Example: jane
scopestring- Filter by who owns the template. Use `system` for built-in templates and `workspace` for templates your workspace created. Example: systemone of
systemworkspace sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
statusstring- Return templates with this lifecycle status. Example: activeone of
draftpendingactiverejectedinactive
bird_asset_folder_getReturn one folder from the workspace's media library, including its resolved path.Read-onlyGet Media-library Folder by ID
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.
Inputs
folder_idstringrequired- ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
bird_asset_folders_listReturn the workspace's media-library folders as a flat list, each carrying its `parent_id` and its resolved `path`, most recently created first.Read-onlyList Workspace Media-library Folders
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_asset_getReturn one media-library asset.Read-onlyGet Media-library Asset by ID
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.
Inputs
asset_idstringrequired- ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
bird_asset_references_listReturn editable resources that reference this asset.Read-onlyList Editable Resources That Use an Asset
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.
Inputs
asset_idstringrequired- ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
bird_asset_upload_session_getReturn the upload session and its saved publication receipt.Read-onlyGet Media-library Upload Session
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.
Inputs
upload_idstringrequired- ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
bird_assets_listReturn a cursor page of the workspace's media-library assets, most recently created first.Read-onlyList Workspace Media-library Assets
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.
Inputs
content_typestring- Return only assets stored with this media type. Example: image/pngone of
image/pngimage/jpegimage/gifvideo/mp4video/webmvideo/quicktimeaudio/mpegaudio/mp4audio/oggaudio/wavapplication/pdf deletedstring- Whether to include assets that have been removed from the library. Removed assets keep serving at their original URL, so they remain listable. Example: excludeone of
excludeincludeonly ending_beforestring- 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_idstring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
kindstring- Return only assets in this category. This groups exact `content_type` values into images, video, audio, and documents. Example: imageone of
imagevideoaudiodocument limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc qstring- A case-insensitive substring match against the asset's name. Example: jane
root_onlyboolean- Return only the assets at the top level of the library, filed in no folder. Cannot be combined with `folder_id`. Example: false
sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_audience_contacts_listList the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first.Read-onlyList Audience's Contacts
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.
Inputs
audience_idstringrequired- ID of the audience whose contacts to list. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- 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_afterstring- 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
bird_audience_getReturn a single audience: its name, description, and type.Read-onlyGet Audience
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.
Inputs
audience_idstringrequired- ID of the audience to fetch. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
bird_audience_membership_getReturn the exact number of audience members at the source evaluation instant, including contacts without email and unsubscribed contacts.Read-onlyGet Audience Membership
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.
Inputs
audience_idstringrequired- ID of the audience whose membership to read. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
bird_audience_membership_statistics_getReturn the first successful observation for each requested UTC date, in chronological order.Read-onlyGet Audience Membership Statistics
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.
Inputs
audience_idstringrequired- ID of the audience whose observations to read. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
fromstring- Inclusive first UTC date. Defaults to 30 days before to, yielding 31 inclusive dates. Example: 2026-01-15
tostring- Inclusive last UTC date. Defaults to today in UTC; future dates are rejected. At most 365 inclusive dates. Example: 2026-01-15
bird_audiences_listReturn a paginated list of audiences in the workspace, newest first.Read-onlyList Audiences
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- Case-insensitive substring match against the audience's name. Example: newsletter
starting_afterstring- 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
bird_available_number_getReturn a single phone number available for purchase, whether it is already in inventory or can be acquired for you.Read-onlyGet Available Phone Number
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.
Inputs
numberstringrequired- Phone number in E.164 format. The leading `+` is optional. Example: +14155550123
bird_available_numbers_listReturn phone numbers available for purchase in a country.Read-onlyList Available Phone Numbers
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.
Inputs
country_codestringrequired- ISO 3166-1 alpha-2 country code to search in. Example: US
capabilitiesarray- Filter by capability. Repeat the parameter to require several at once: `capabilities=sms&capabilities=voice` returns only numbers that support both. Example: ["example"]
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
number_typestring- Return only numbers of this physical type after applying the country and prefix filters. Example: +14155550123
prefixstring- 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_afterstring- 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
bird_compliance_attachments_listReturn the registration attachments uploaded for the workspace, most recent first.Read-onlyList Registration Attachments
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).
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_compliance_identities_listReturn the parties this workspace has stored, newest first.Read-onlyList Identities
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_atname starting_afterstring- 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
bird_compliance_identity_getReturn one of this workspace's parties, with the business details it holds.Read-onlyGet Identity
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.
Inputs
identity_idstringrequired- Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
bird_compliance_requirements_getReturn 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.Read-onlyGet What a Registration Needs
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.
Inputs
country_codestringrequired- The destination country. For `identity` send `ZZ`, the international coordinate: your business registers once, not per country. Example: US
subject_kindstringrequired- What you are registering. Example: sms_senderone of
sms_sendernumbernumber_emergencyidentity identity_idstring- 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
programstring- 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_idstring- 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
bird_compliance_submission_getReturn every answer on a submission and where each one stands.Read-onlyGet Submission
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.
Inputs
submission_idstringrequired- Submission ID. Example: csb_01krdgeqcxet5s7t44vh8rt9mg
bird_contact_getReturn a single contact, including its custom `data` values and the channels it can be reached on.Read-onlyGet Contact
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.
Inputs
contact_idstringrequired- ID of the contact to fetch. Example: con_01krdgeqcxet5s7t44vh8rt9mg
bird_contact_preferences_listReturn 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.Read-onlyList Contact's Preferences
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.
Inputs
contact_idstringrequired- ID of the contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_contact_properties_listReturn a paginated list of the workspace's contact properties, newest first.Read-onlyList Contact Properties
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_contact_property_getReturn a single contact property: its immutable key and type, the fallback value, and whether it is archived.Read-onlyGet Contact Property
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.
Inputs
property_idstringrequired- ID of the contact property to fetch. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
bird_contacts_listList contacts in the workspace, optionally filtered and sorted.Read-onlyList Contacts
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.
Inputs
emailstring- 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_beforestring- 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_idstring- 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
identifierstring- Filter to contacts that have a specific identifier on file. Example: emailone of
emailphone_number include_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
phone_numberarray- 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"]
qstring- 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_afterstring- 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
bird_email_broadcast_clicked_links_listReturn the destination URLs a broadcast's recipients clicked, grouped by URL and sorted by click count.Read-onlyList Email Broadcast's Clicked Links
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.
Inputs
broadcast_idstringrequired- ID of the broadcast whose clicked links to read. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
bird_email_broadcast_counts_getReturn 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.Read-onlyGet Email Broadcast's Audience Counts
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
bird_email_broadcast_events_listReturn the per-recipient delivery timeline for a broadcast, oldest first, as a cursor page.Read-onlyList Email Events for a Broadcast
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.
Inputs
broadcast_idstringrequired- ID of the broadcast whose event timeline to read. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
typestring- 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
bird_email_broadcast_getReturn one broadcast, with its audience reference and counters.Read-onlyGet Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
bird_email_broadcast_previewRender a broadcast's template for one contact using the saved broadcast plus any changes in this request, without saving or sending.Read-onlyPreview Email Broadcast for a Contact
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
contact_idstring- 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
fromobject- 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>
headersobject- 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_keystring- 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_toarray- Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
templateobject- Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}
bird_email_broadcast_recipients_listReturn recipient-level delivery state for a broadcast, paginated.Read-onlyList Email Recipients of a Broadcast
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.
Inputs
broadcast_idstringrequired- ID of the broadcast whose recipients to read. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
tostring- 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
bird_email_broadcast_send_quota_getReturn how many recipients the organization's email send allowance covers.Read-onlyGet Email Send Allowance for a Broadcast
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.
Inputs
broadcast_idstringrequired- ID of the broadcast to check the email send allowance for. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
send_atstring- 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
bird_email_broadcast_validateCheck the saved broadcast or the changes supplied in this request against the template's published content.Read-onlyValidate Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
fromobject- 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>
headersobject- 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_keystring- 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_toarray- Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
templateobject- Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}
bird_email_broadcasts_listReturn a paginated list of broadcasts in the workspace, newest first.Read-onlyList Email Broadcasts
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.
Inputs
audience_idstring- Filter by audience. Only broadcasts that use this audience are returned. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
created_afterstring- 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_beforestring- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- 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_afterstring- 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
statusarray- Filter by lifecycle status. Repeat the parameter to match more than one status, for example `?status=accepted&status=sending`.
tagstring- 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`.
bird_email_competitive_brand_campaign_getReturn one campaign an email panel observed a watched brand sending.Read-onlyGet Email One Campaign a Watched Brand Sent
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.
Inputs
campaign_idstringrequired- The campaign to return, taken from the brand's campaign list. Example: 3914827265
watchlist_brand_idstringrequired- The watched brand that sent the campaign. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
bird_email_competitive_brand_campaigns_listReturn a page of campaigns an email panel observed a watched brand sending over the period, in the requested order.Read-onlyGet Email Campaigns a Watched Brand Sent
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.
Inputs
watchlist_brand_idstringrequired- The watchlist entry whose campaigns to return. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc rangeinteger- 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: 30one of
73090 sortstring- Field to sort campaigns by. Example: sent_atone of
sent_at starting_afterstring- 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
bird_email_competitive_brand_getReturn one watched brand's figures for the period, together with how each mailbox provider treated its mail and how that compares with your own.Read-onlyGet Email Watched Brand's Figures
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.
Inputs
watchlist_brand_idstringrequired- The watchlist entry to act on. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
rangeinteger- 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: 30one of
73090
bird_email_competitive_brand_send_time_getReturn 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.Read-onlyGet Email When a Watched Brand Sends
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.
Inputs
watchlist_brand_idstringrequired- The watchlist entry whose sending pattern to return. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
timezonestring- 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
bird_email_competitive_brands_searchSearch 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.Read-onlySearch Email Brands to Add to the Watchlist
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.
Inputs
qstringrequired- A brand name, or a sending domain to look up the brand behind it. Example: everlane
bird_email_competitive_notable_campaigns_listReturn the campaigns worth a second look across every brand the workspace watches, surfaced for what they did rather than for when they were sent.Read-onlyGet Email Notable Campaigns Across Watched Brands
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.
Inputs
rangeinteger- 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: 30one of
73090
bird_email_competitive_volume_series_getReturn daily send volume for the watched brands you name, plus a line for your own sending, over one shared axis.Read-onlyGet Email Send Volume Over Time for Watched Brands
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.
Inputs
brand_idsarray- 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"]
rangeinteger- 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: 30one of
73090
bird_email_competitive_watchlist_getReturn 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.Read-onlyGet Email Competitor Watchlist with Its Latest Figures
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.
Inputs
rangeinteger- 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: 30one of
73090
bird_email_domain_events_listReturn the domain's activity history, newest first by default: - Registration.Read-onlyList Domain Events
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.
Inputs
domain_idstringrequired- ID of the domain whose events to list. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_email_domain_getReturn the domain with its capability statuses and every DNS record's current verification state.Read-onlyGet Sending Domain
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.
Inputs
domain_idstringrequired- ID of the domain to fetch. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
bird_email_domains_listReturn all sending domains for the current workspace, newest first by default.Read-onlyList Sending Domains
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
namestring- Substring match against the domain name (case-insensitive). Example: sk-test-sample
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_atname starting_afterstring- 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
bird_email_health_getReturn your workspace's sending-health verdict for the requested window, together with reference deliverability limits and the boundaries used to classify risk.Read-onlyGet Email Sending Health and Deliverability Limits
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.
Inputs
fromstring- Start date (inclusive) in `YYYY-MM-DD`, UTC. Defaults to 7 days before `to` when omitted. Example: 2026-05-19
tostring- 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
bird_email_inbound_address_getReturn a single inbound address: the `address` you forward a mailbox to, and the `label` you gave it.Read-onlyGet Email Inbound Address
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.
Inputs
inbound_address_idstringrequired- Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_addresses_listReturn a paginated list of the workspace's inbound addresses.Read-onlyList Email Inbound Addresses
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_inbound_message_attachments_listReturn metadata for each attachment on a received email: - The `attachment_id`.Read-onlyList Received Email's Attachments
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.
Inputs
inbound_message_idstringrequired- Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_message_body_getReturn the parsed, decoded body of a received email as JSON: the `html` and `text` parts, each `null` when the message had no such part.Read-onlyGet Received Email's Body
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.
Inputs
inbound_message_idstringrequired- Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_message_getReturn the parsed metadata for a received email: - Addresses.Read-onlyGet Received Email
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.
Inputs
inbound_message_idstringrequired- Received email identifier. Starts with `rem_`. Example: rem_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_messages_listReturn a paginated list of received emails for the workspace, newest first.Read-onlyList Received Emails
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.
Inputs
ending_beforestring- 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
fromstring- 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_idstring- Filter to messages received on a specific inbound address. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
limitinteger- Maximum number of items to return per page. Example: 25
mailbox_idstring- Filter to messages received by a specific mailbox. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg
received_afterstring- Filter to messages received at or after this time. Example: 2026-01-15T09:30:00Z
received_beforestring- Filter to messages received at or before this time. Example: 2026-01-15T09:30:00Z
starting_afterstring- 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
bird_email_inbound_route_getReturn a single inbound route: - Its match rule.Read-onlyGet Email Inbound Route
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.
Inputs
route_idstringrequired- Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_routes_listReturn a paginated list of the workspace's inbound routes in evaluation order, lowest priority number first.Read-onlyList Email Inbound Routes
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.
Inputs
domainstring- Filter to routes on this domain. Example: mail.acme.com
enabledboolean- Set to `true` for active routes or `false` for routes skipped during evaluation. Example: false
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_inbox_insights_authentication_getReturn 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...Read-onlyGet Email Authentication Standing for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
comparestring- Include the prior equal-length period, populating `compared_to`. Example: previous_periodone of
previous_period fromstring- 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
tostring- Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17
bird_email_inbox_insights_blocklists_getCheck 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.Read-onlyCheck Email Whether a Sending Domain's Infrastructure Is Blocklisted
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.
Inputs
sending_domainstringrequired- 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
bird_email_inbox_insights_complaints_getReturn 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.Read-onlyGet Email Google-reported Spam Rate for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
comparestring- Include the prior equal-length period, populating `compared_to` and the rate's delta. Example: previous_periodone of
previous_period fromstring- 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_bystring- Bucket size for the series. Defaults to day. Example: dayone of
dayweekmonth tostring- Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17
bird_email_inbox_insights_domains_getReturn a page of sending domains this workspace can report on, in alphabetical order by default, and whether Inbox Insights is switched on for each.Read-onlyList Sending Domains and Their Inbox Insights Status
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).
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: ascone of
ascdesc searchstring- Substring match against the sending domain (case-insensitive). Example: jane
sending_domainstring- Exact sending domain to return. Matching is case-insensitive. Example: mail.example.com
sortstring- Field to sort by. Defaults to `domain`. Example: domainone of
domain starting_afterstring- 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
bird_email_inbox_insights_industry_benchmark_getReturn 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.Read-onlyGet Email Industry Placement Benchmark for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
bird_email_inbox_insights_placement_getReturn 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.Read-onlyGet Inbox Placement for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
comparestring- Include the prior equal-length period, populating `compared_to` and every delta field. Example: previous_periodone of
previous_period fromstring- 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_bystring- Bucket size for the series. Defaults to day. Example: dayone of
dayweekmonth include_ip_detailsboolean- Include per-IP placement detail for the domain's sending infrastructure. Off by default; only the sending-infrastructure view needs it. Example: false
series_providersarray- 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"]
tostring- Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17
bird_email_inbox_insights_seed_test_configuration_getReturn 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.Read-onlyGet Email Choices Available for a New Seed Test
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.
Inputs
sending_domainstringrequired- 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
bird_email_inbox_insights_seed_tests_listReturn 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.Read-onlyGet Email Seed Tests for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
fromstring- 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
tostring- Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17
bird_email_inbox_insights_spam_traps_getReturn 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.Read-onlyGet Email Spam-trap Hits for a Sending Domain
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.
Inputs
sending_domainstringrequired- 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
comparestring- Include the prior equal-length period, populating `compared_to` and `delta`. Example: previous_periodone of
previous_period fromstring- 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
tostring- Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today. Example: 2026-08-17
bird_email_message_content_getReturn the stored HTML and text bodies for a sent message.Read-onlyGet Email Stored Message Content
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.
Inputs
message_idstringrequired- 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_idstring- 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
bird_email_message_events_listReturn the message's per-recipient event timeline, oldest first, as a cursor page.Read-onlyList Email Events for a Message
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.
Inputs
message_idstringrequired- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
typestring- Filter by event type, for example `email.bounced` or `email.opened`.
bird_email_message_getReturn a single message with its aggregate delivery `status` and per-state recipient counts.Read-onlyGet Email Message
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.
Inputs
message_idstringrequired- 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
bird_email_message_recipients_listReturn 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.Read-onlyList Email Recipients of a Message
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.
Inputs
message_idstringrequired- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_messages_listReturn the workspace's sent and scheduled messages, newest first, as a cursor page.Read-onlyList Email Messages
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.
Inputs
broadcast_idstring- Filter messages by broadcast ID. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
categorystring- Filter by category. Example: marketingone of
marketingtransactional created_afterstring- 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_beforestring- 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_beforestring- 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
fromstring- Filter by sender address. Exact match against the message `from` field. The address is normalized to lowercase before comparison. Example: noreply@acme.com
limitinteger- Maximum number of items to return per page. Example: 25
referencestring- 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_afterstring- 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
statusstring- Filter by aggregate delivery status. Example: scheduledone of
scheduledacceptedprocesseddeferreddeliveredpartial_failurebouncedcomplainedrejectedcanceled tagarray- 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.
tostring- 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
bird_email_smtp_config_getReturn the SMTP send-option config stored for the given API key.Read-onlyGet Email SMTP Config
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.
Inputs
api_key_idstringrequired- ID of the API key the config applies to, the same key your SMTP client authenticates with. Example: key_01krdgeqcxet5s7t44vh8rt9mg
bird_email_smtp_configs_listReturn the SMTP send-option configs stored for API keys in this workspace, as a cursor page.Read-onlyList Email SMTP Configs
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Sort by `created_at`, the default and only supported field. Example: created_atone of
created_at starting_afterstring- 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
bird_email_stats_breakdown_getGet email statistics for a period grouped by one dimension (dimension): sending ips, sending domains, mailbox providers, mailbox provider regions, recipient domains, templates.Read-onlyGet Email Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/email/stats/. Example: sending-ipsone of
sending-ipssending-domainsmailbox-providersmailbox-provider-regionsrecipient-domainstemplates categorystring- 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_beforestring- 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
fromstring- 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_trendboolean- 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
limitinteger- Maximum number of IP rows to return, ranked by the `sort` field descending. Example: 50
sortstring- 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: deliveredone of
deliveredbouncedcomplaineddeferredbounces.hardbounces.softbounces.adminbounces.blockbounces.undetermineddelivery_ratebounce_ratecomplaint_ratebounces.hard_ratebounces.soft_ratebounces.admin_ratebounces.block_ratebounces.undetermined_rate starting_afterstring- 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
timezonestring- 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
tostring- 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_grainstring- Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: dailyone of
dailyhourly
bird_email_stats_by_bounce_code_getReturn bounce counts for the requested period, grouped by the SMTP error code the receiving mail server returned.Read-onlyGet Email Bounces by SMTP Error Code
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).
Inputs
categorystring- 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_beforestring- 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
fromstring- 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
limitinteger- Maximum number of bounce-code rows to return, ranked by the `sort` field descending. Example: 50
sortstring- 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: bouncedone of
bouncedbounces.hardbounces.softbounces.adminbounces.blockbounces.undetermined starting_afterstring- 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
timezonestring- 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
tostring- 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
bird_email_stats_by_broadcast_getReturn 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.Read-onlyGet Email Statistics by Broadcast
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).
Inputs
categorystring- 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_beforestring- 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
fromstring- 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
limitinteger- Maximum number of broadcast rows to return, ranked by the `sort` field descending. Example: 50
sortstring- 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: processedone of
processeddeliveredbouncedcomplaineddeferredrejectedoob_bouncesbounces.hardbounces.softbounces.adminbounces.blockbounces.undeterminedopensopens_non_prefetchedunique_opensunique_opens_non_prefetchedclicksunique_clicksunsubscribesdelivery_ratebounce_ratecomplaint_rateopen_rateclick_rateunsubscribe_ratebounces.hard_ratebounces.soft_ratebounces.admin_ratebounces.block_ratebounces.undetermined_rate starting_afterstring- 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
timezonestring- 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
tostring- 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
bird_email_stats_by_category_getReturn delivery and engagement counts for the requested period, grouped by category, so you can compare deliverability and engagement between your transactional and marketing traffic.Read-onlyGet Email Statistics by Category
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).
Inputs
ending_beforestring- 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
fromstring- 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_trendboolean- 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
limitinteger- Maximum number of category rows to return, ranked by the `sort` field descending. Example: 50
sortstring- 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: processedone of
processeddeliveredbouncedcomplaineddeferredrejectedoob_bouncesbounces.hardbounces.softbounces.adminbounces.blockbounces.undeterminedopensopens_non_prefetchedunique_opensunique_opens_non_prefetchedclicksunique_clicksunsubscribesdelivery_ratebounce_ratecomplaint_rateopen_rateclick_rateunsubscribe_ratebounces.hard_ratebounces.soft_ratebounces.admin_ratebounces.block_ratebounces.undetermined_rate starting_afterstring- 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
timezonestring- 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
tostring- 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_grainstring- Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: dailyone of
dailyhourly
bird_email_stats_by_complaint_type_getReturn spam-complaint counts for the requested period, grouped by the feedback-loop complaint type the mailbox provider reported, for example `abuse`, `fraud`, or `virus`.Read-onlyGet Email Complaints by Type
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).
Inputs
categorystring- 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_beforestring- 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
fromstring- 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
limitinteger- Maximum number of complaint-type rows to return, ranked by `complained` descending. Example: 50
sortstring- Metric to rank rows by, applied descending. It defaults to `complained`, the only sortable metric for this breakdown. Example: complainedone of
complained starting_afterstring- 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
timezonestring- 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
tostring- 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
bird_email_stats_by_tag_getReturn delivery and engagement counts for the requested period, grouped by tag.Read-onlyGet Email Statistics by Tag
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).
Inputs
categorystring- 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_beforestring- 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
fromstring- 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_trendboolean- 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
limitinteger- Maximum number of tag rows to return, ranked by the `sort` field descending. Example: 50
namestring- Restrict the breakdown to this tag name. Names match case-sensitively. Example: sk-test-sample
sortstring- 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: processedone of
processeddeliveredbouncedcomplaineddeferredrejectedoob_bouncesbounces.hardbounces.softbounces.adminbounces.blockbounces.undeterminedopensopens_non_prefetchedunique_opensunique_opens_non_prefetchedclicksunique_clicksunsubscribesdelivery_ratebounce_ratecomplaint_rateopen_rateclick_rateunsubscribe_ratebounces.hard_ratebounces.soft_ratebounces.admin_ratebounces.block_ratebounces.undetermined_rate starting_afterstring- 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
timezonestring- 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
tostring- 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_grainstring- Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: dailyone of
dailyhourly
bird_email_stats_engagement_breakdown_getGet email engagement statistics for a period grouped by one dimension (dimension): locations, clients.Read-onlyGet Email Engagement Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/email/stats/. Example: locationsone of
locationsclients categorystring- 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_beforestring- 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
fromstring- 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_bystring- 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: countryone of
countryregioncity limitinteger- Maximum number of location rows to return, ranked by the `sort` field descending. Example: 50
sortstring- Metric to rank rows by, applied descending. It defaults to `unique_opens`. Only engagement counts are sortable. This breakdown has no rates. Example: unique_opensone of
opensopens_non_prefetchedunique_opensunique_opens_non_prefetchedclicksunique_clicks starting_afterstring- 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
timezonestring- 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
tostring- 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
bird_email_stats_queryQuery 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.Read-onlyQuery Email Delivery and Engagement Metrics
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.
Inputs
fromstringrequired- 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
metricsarrayrequired- 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"]
tostringrequired- 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_beforestring- 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
filtersobject- 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"]}}
grainstring- 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: weekone of
quarter_hourhourhalf_daydayweekmonth group_bystring- 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_domainone of
sending_domaincategorytemplate_idtagrecipient_domainmailbox_providermailbox_provider_regionsending_ipip_pool_idbroadcast_idcountryregioncityagent_familyos_familydevice_familysmtp_error_codefeedback_type idempotency_keystring- 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
limitinteger- Grouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series. Example: 25
orderstring- Grouped requests only. Defaults to desc. Example: ascone of
ascdesc sortstring- 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_acceptedone of
sends_acceptedacceptedprocesseddeliveredbouncedhard_bouncedsoft_bouncedadmin_bouncedblock_bouncedundetermined_bouncedcomplaineddeferredrejectedoob_bouncesopensopens_non_prefetchedclicksunsubscribesunique_opensunique_opens_non_prefetchedunique_clicksconfirmed_unique_opensconfirmed_unique_opens_non_prefetchedeffective_deliveredall_bouncesdelivery_ratebounce_ratecomplaint_ratedeferral_rateopen_rateclick_rateunsubscribe_rateoob_rateprocessing_p50_msprocessing_p95_msprocessing_p99_mstotal_p50_mstotal_p95_mstotal_p99_ms starting_afterstring- Grouped requests only. Opaque next_cursor from the previous response. Mutually exclusive with ending_before. Example: WyIyMDI2LTAxLTE1VDA5OjMwOjAwWiJd
timezonestring- IANA timezone for dates and bucket boundaries. Defaults to UTC. Example: UTC
bird_email_stats_summary_getReturn 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).Read-onlyGet Aggregate Email Statistics
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.
Inputs
categorystring- 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
comparestring- 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_periodone of
previous_period fromstring- 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_domainstring- 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_domainstring- 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_ipstring- 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
tagstring- 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
templatestring- 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
timezonestring- 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
tostring- 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
bird_email_stats_timeseries_getGet email statistics for a period as a time series, one row per day or per hour (granularity), with the same filters as the summary.Read-onlyGet Email Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly categorystring- 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
fromstring- 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_domainstring- 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_domainstring- 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_ipstring- 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
tagstring- 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
templatestring- 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
timezonestring- 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
tostring- 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
bird_email_suppression_getReturn one suppression record: - The address.Read-onlyGet Email Suppression
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.
Inputs
suppression_idstringrequired- ID of the suppression record, as returned when the suppression was created or listed. Example: sup_01krdgeqcxet5s7t44vh8rt9mg
bird_email_suppressions_listReturn the workspace's suppressed email addresses as a paginated list, newest first.Read-onlyList Email Suppressions
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.
Inputs
emailstring- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
reasonstring- 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_bounceone of
hard_bouncecomplaintunsubscribemanual scope_typestring- 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: workspaceone of
workspacecategoryaudiencetopiccontactdomain starting_afterstring- 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
bird_email_template_broadcasts_listReturn the broadcasts that block deleting this template, as a cursor page, newest first.Read-onlyList Email Broadcasts Blocking a Template Delete
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.
Inputs
template_refstringrequired- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_template_getReturn a template's metadata, language states, sendable languages, draft revision, and draft and published version IDs.Read-onlyGet Email Template
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.
Inputs
template_refstringrequired- 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
bird_email_template_language_getReturn one language's content from a version (its subject and bodies) plus the `revision` to send back when saving it.Read-onlyGet Email One Language of a Version
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.
Inputs
languagestringrequired- The language as a BCP-47 tag. Example: pt-BR
template_refstringrequired- 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_idstringrequired- The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
bird_email_template_parameters_getGet the parameters and variables used by the template's published content in one language.Read-onlyGet Published Email Template Parameters
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.
Inputs
template_refstringrequired- Workspace template ID, workspace template slug, or built-in template slug. Example: welcome_email
languagestring- Language of the template's published content. Omission uses the template's default language. Example: pt-BR
bird_email_template_previewRender an email template with sample parameter values (and optionally a contact) without sending anything.Read-onlyGet Email Template Preview
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.
Inputs
template_refstringrequired- The template to preview: a workspace template's id (`emt_…`) or slug, or a built-in `system` template's `bird_` slug. Example: welcome-email
contactstring- 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
contentobject- 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_keystring- 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
languagestring- 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
parametersobject- 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"}
versionstring- Preview a specific published version by its id, instead of the current draft. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
bird_email_template_version_getReturn a single version of an email template: - Its lifecycle metadata (`status`, `version_number`, `published_at`).Read-onlyGet Email Template Version
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.
Inputs
template_refstringrequired- 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_idstringrequired- The version to read or reset. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
bird_email_template_version_languages_listReturn every language the version holds, ordered by language tag, without the content itself, so listing a template with twenty-five languages stays small.Read-onlyList Email Version's Languages
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.
Inputs
template_refstringrequired- 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_idstringrequired- The version whose languages to list. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
bird_email_template_versions_listReturn the template's versions as a cursor page (the current draft plus all published versions), newest first.Read-onlyList Email Template Versions
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.
Inputs
template_refstringrequired- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_templates_listReturn a paginated list of email templates, newest first.Read-onlyList Email Templates
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.
Inputs
categorystring- Return only `transactional` or `marketing` templates; omit to return both categories. Example: transactionalone of
transactionalmarketing ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- A case-insensitive substring search across the template's slug, name, and description. Example: jane
scopestring- 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: systemone of
systemworkspace sourcestring- Return only templates authored in this format. Example: example
starting_afterstring- 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
themestring- 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: arcaneone of
arcanebarebonematteprotocolstudio
bird_email_thread_getReturn a single conversation.Read-onlyGet Email Thread
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.
Inputs
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
bird_email_thread_message_attachments_listReturn the attachments on a message in a conversation.Read-onlyList Email Thread Message's Attachments
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.
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
bird_email_thread_message_body_getReturn the original rendered HTML and plain-text body of a message in a conversation.Read-onlyGet Email Thread Message's Original Body
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.
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
bird_email_thread_message_getReturn a single message in a conversation, including its extracted plain text.Read-onlyGet Email Message in a Thread
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.
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
bird_email_thread_messages_listReturn the messages in a conversation, newest first, both received and sent.Read-onlyList Email Messages in a Thread
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.
Inputs
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
directionstring- Filter to received (`inbound`) or sent (`outbound`) messages. Example: outboundone of
outboundinbound ending_beforestring- 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
includestring- Set to `extracted_text` to inline each message's extracted plain text. Example: extracted_textone of
extracted_text labelstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_email_threads_listReturn a paginated list of conversations across the workspace's mailboxes, most recently active first.Read-onlyList Email Threads
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.
Inputs
afterstring- 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
beforestring- 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_idstring- Filter to conversations linked to a specific contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
folderstring- Filter to a folder. Defaults to inbox when neither folder nor custom labels are supplied. Example: inboxone of
inboxarchivespamblockedsenttrash labelsarray- Match every listed custom label. Repeat labels to supply more than one. System label names are refused. Names match in any casing. Example: ["urgent"]
limitinteger- Maximum number of items to return per page. Example: 25
mailbox_idstring- 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
participantstring- 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_statestring- Filter to read or unread conversations. Omit for either state. Example: readone of
readunread starting_afterstring- 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
subjectstring- Conversations whose subject contains this text (case-insensitive). Example: quarterly invoice
bird_esim_assignment_getReturn the assigned person.Read-onlyGet eSIM Assignment
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.
Inputs
esim_idstringrequired- The esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_compatible_offers_listReturn offers currently compatible with this eSIM’s network, package capacity, and existing packages.Read-onlyList Offers an eSIM Can Take
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.
Inputs
esim_idstringrequired- Identifier of the eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
recurring_onlyboolean- Keep only offers with recurring service configured. Enrollment still checks supplier support and the published recurring price. Example: false
bird_esim_credentials_getReturn installation details for an eSIM, including an iOS installation link, an activation code, and manual setup components.Read-onlyGet eSIM Install Credentials
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
accept_languagestring- 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
bird_esim_deliveries_listReturn the credential deliveries sent for this eSIM, newest first (the most recent 50), each with its outcome.Read-onlyList eSIM's Credential Deliveries
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.
Inputs
esim_idstringrequired- Identifier of the eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_getReturn one eSIM: lifecycle status, device installation state, current data packages with balances, service-period timestamps, and the most recent network attachment.Read-onlyGet eSIM
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_offer_checkout_options_getReturn published one-time terms and automatic renewal availability for a new eSIM, including tax-inclusive totals and current funding shortfalls.Read-onlyGet eSIM Checkout Options
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.
Inputs
offer_idstringrequired- The offer. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_offer_getReturn one eSIM offer with its pricing and embedded coverage zone.Read-onlyGet eSIM Offer
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.
Inputs
offer_idstringrequired- Offer ID. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_offer_recurrence_getReturn the published whole-package recurring price and calendar-month or fixed-day cadence.Read-onlyGet Recurring eSIM Offer Terms
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.
Inputs
offer_idstringrequired- The offer. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_offer_requirements_getReturn identification guidance as a JSON Schema for each country in the offer's coverage zone.Read-onlyGet Country Identification Requirements for an eSIM Offer
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.
Inputs
offer_idstringrequired- Offer ID. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_offers_listReturn the eSIM offers your workspace can order as a cursor-paginated list.Read-onlyList eSIM Offers
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.
Inputs
countrystring- Keep only offers whose coverage zone includes this country (ISO 3166-1 alpha-2). Example: US
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Possible values: created_at. Example: created_atone of
created_at starting_afterstring- 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
statusstring- Filter by offer availability. Omitted, only active offers are returned. Example: draftone of
draftactiveretired zone_idstring- Keep only offers selling this coverage zone. Example: ezn_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_order_getReturn one order.Read-onlyGet Order
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.
Inputs
order_idstringrequired- Order ID. Example: eor_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_orders_listReturn the workspace's orders as a cursor-paginated list, newest first.Read-onlyList Orders
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.
Inputs
completed_afterstring- 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_beforestring- 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_afterstring- 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_beforestring- 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_beforestring- 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_idstring- Keep only orders for this eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
limitinteger- Maximum number of items to return per page. Example: 25
modestring- Keep only orders created in this mode. Without it, both live and test orders are returned. Example: liveone of
livetest starting_afterstring- 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
statusarray- Keep only orders whose `status` matches; repeat the parameter to match any of several. Example: ["scheduled"]
bird_esim_package_getReturn one data package with its balance, validity, speed class, and status.Read-onlyGet Data Package
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
package_idstringrequired- Data package ID. Example: epk_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_packages_listReturn 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.Read-onlyList eSIM's Data Packages
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_recurring_periods_listReturn funded periods with their original charges, confirmed credits, and delivery orders.Read-onlyList Recurring eSIM Periods
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.
Inputs
subscription_idstringrequired- The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_esim_recurring_subscription_getReturn the current paid period separately from package delivery and cancellation state.Read-onlyGet Recurring eSIM Subscription
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.
Inputs
subscription_idstringrequired- The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_recurring_subscriptions_listReturn recurring services for assigned eSIMs in this workspace.Read-onlyList Recurring eSIM Subscriptions
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.
Inputs
ending_beforestring- 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_idstring- Filter by esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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_idstring- Return eSIMs assigned to this subscriber. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_settings_getReturn your workspace’s eSIM settings, including defaults for fields you have not changed.Read-onlyGet eSIM Settings
Return your workspace’s eSIM settings, including defaults for fields you have not changed. Returns an object with credential_delivery_enabled.
Inputs
This tool takes no inputs.
bird_esim_subscriber_getReturn the contact reference for a subscriber in this workspace.Read-onlyGet eSIM Subscriber
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.
Inputs
subscriber_idstringrequired- The subscriber id. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_subscribers_listReturn person references in this workspace, newest first.Read-onlyList eSIM Subscribers
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.
Inputs
contact_idstring- The contact id. Example: con_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_esim_zone_getReturn one coverage zone with its authoritative country list.Read-onlyGet eSIM Coverage Zone
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.
Inputs
zone_idstringrequired- Zone ID. Example: ezn_01krdgeqcxet5s7t44vh8rt9mg
bird_esim_zones_listReturn the coverage zones behind the offer catalog as a cursor-paginated list.Read-onlyList eSIM Coverage Zones
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.
Inputs
countrystring- Keep only zones that include this country (ISO 3166-1 alpha-2). Example: US
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Possible values: created_at. Example: created_atone of
created_at starting_afterstring- 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
bird_esims_listReturn your workspace's eSIMs as a cursor-paginated list, newest first.Read-onlyList eSIMs
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.
Inputs
created_afterstring- 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_beforestring- 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_namestring- 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_beforestring- 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
iccidstring- Filter by ICCID (exact match). Example: example
iccid_prefixstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
modestring- Keep only eSIMs created in this mode. Without it, both live and test eSIMs are returned. Example: liveone of
livetest phone_numberstring- 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
renewalarray- 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_afterstring- 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
statusarray- Keep only eSIMs whose current `status` matches; repeat the parameter to match any of several. Example: ["provisioning"]
subscriber_idstring- Return eSIMs assigned to this subscriber. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
tagarray- 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"]
bird_mailbox_getReturn a single mailbox by ID or email address in this workspace.Read-onlyGet Mailbox
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
bird_mailbox_labels_listReturn the labels available in a mailbox.Read-onlyList Mailbox's Labels
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
bird_mailbox_messages_listReturn the messages in a mailbox across all of its conversations, newest first.Read-onlyList Mailbox's Messages
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
afterstring- 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
beforestring- 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
directionstring- Filter to received (`inbound`) or sent (`outbound`) messages. Example: outboundone of
outboundinbound ending_beforestring- 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
includestring- Set to `extracted_text` to inline each message's extracted plain text. Example: extracted_textone of
extracted_text labelstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
statusstring- Filter sent messages by combined delivery status: `accepted`, `sent`, `delivered`, or `failed`. Example: acceptedone of
acceptedsentdeliveredfailed
bird_mailbox_receive_rules_listReturn a paginated list of the mailbox's receive rules, oldest first.Read-onlyList Email Receive Rules
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
actionstring- Return only `allow` or `block` rules; omit to return both actions. Example: allowone of
allowblock ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_mailbox_scheduled_message_getRead the scheduled send and its dispatch, failure or cancellation state.Read-onlyGet Scheduled Mailbox Send
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
scheduled_message_idstringrequired- Scheduled send identifier from scheduled_message_id in the acceptance response. Example: msm_01krdgeqcxet5s7t44vh8rt9mg
bird_mailbox_scheduled_messages_listList scheduled sends separately from conversation messages, including completed and canceled records.Read-onlyList Scheduled Mailbox Sends
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
statusstring- Filter by scheduling state. Example: scheduledone of
scheduledsendingsentfailedcanceled thread_idstring- Filter by the reserved conversation identifier. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
bird_mailbox_stats_getReturn the mailbox's sent and received email statistics over a time window: a period-wide summary plus a bucketed series.Read-onlyGet Mailbox Email Statistics
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
fromstring- 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
granularitystring- Granularity of the series: `day` (default) or `hour`. Echoed back as `period.grain`. Example: dayone of
dayhour timezonestring- 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
tostring- 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
bird_mailboxes_listReturn a paginated list of the workspace's mailboxes, newest first.Read-onlyList Mailboxes
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.
Inputs
addressstring- Filter to the mailbox with exactly this address. Example: concierge@inbox.ai
domainstring- Filter to mailboxes whose address is on this domain. Example: inbox.ai
ending_beforestring- 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_deletedboolean- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- Case-insensitive substring match on the mailbox's `address`, `name`, or `display_name`. Example: concierge
starting_afterstring- 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
statestring- Return only `active` or `suspended` mailboxes. Use `include_deleted` for restorable deleted mailboxes. Example: activeone of
activesuspended
bird_number_getReturn a single phone number allocated to your workspace, whether it is a dedicated number you bought or a shared number managed for you.Read-onlyGet Allocated Number
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.
Inputs
number_idstringrequired- Identifier of the number, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
bird_numbers_listReturn a paginated list of the phone numbers currently allocated to your workspace, newest first.Read-onlyList Your Allocated Numbers
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.
Inputs
capabilitiesarray- Filter by capability. Repeat the parameter to require several at once: `capabilities=sms&capabilities=voice` returns only numbers that support both. Example: ["example"]
country_codestring- Filter by the country a number belongs to, as an ISO 3166-1 alpha-2 code. Example: US
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
numberstring- 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_typestring- Return only allocated numbers of this physical type after applying the country and prefix filters. Example: +14155550123
prefixstring- 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
referencestring- Return numbers with this exact reference. Matching is case-sensitive. Example: example
searchstring- 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_afterstring- 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
bird_numbers_order_getReturn a single number order by id, including its current lifecycle state and, once completed, the number it produced.Read-onlyGet Number Order
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.
Inputs
order_idstringrequired- Identifier of the order. Example: nor_01krdgeqcxet5s7t44vh8rt9mg
bird_numbers_orders_listReturn your workspace's number orders, newest first.Read-onlyList Your Number Orders
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
statusstring- Return only orders with status `charging`, `ordering`, `pending`, `completed`, or `failed`. Example: active
bird_preference_getReturn one preference: the key it is about, the current statement on it, and the statement's provenance.Read-onlyGet Preference
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.
Inputs
preference_idstringrequired- 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
bird_preferences_listReturn the workspace's recorded preferences, most recently created first.Read-onlyList Preferences
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.
Inputs
channelstring- Return only preferences on this channel. Example: sms
ending_beforestring- 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
handlestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_realtime_app_getReturn a single Realtime app with its configuration and connection details (`app_id`, `region`).Read-onlyGet Realtime App
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.
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
bird_realtime_app_keys_listReturn the app's keys, oldest first.Read-onlyList Realtime App's Keys
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.
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
include_revokedboolean- When true, include revoked keys in the response. Example: false
bird_realtime_apps_listReturn the workspace's Realtime apps as a paginated list, filterable by a case-insensitive `name` substring.Read-onlyList Realtime Apps
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
namestring- Substring match against the app name (case-insensitive). Example: sk-test-sample
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_atname starting_afterstring- 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
bird_realtime_regions_listReturn the regions a Realtime app can be created in.Read-onlyList Realtime Regions
Return the regions a Realtime app can be created in. Returns data, an array of items with id.
Inputs
This tool takes no inputs.
bird_sms_inbound_stats_breakdown_getGet inbound SMS statistics for a period grouped by one dimension (dimension): countries, operators, numbers.Read-onlyGet Inbound SMS Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/sms/stats/inbound/. Example: countriesone of
countriesoperatorsnumbers fromstring- 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
limitinteger- 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
timezonestring- 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
tostring- 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
bird_sms_inbound_stats_summary_getReturn the total number of messages your numbers received over the period, using the time the carrier received each message.Read-onlyGet Aggregate Inbound SMS Statistics
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.
Inputs
comparestring- 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_periodone of
previous_period fromstring- 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
timezonestring- 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
tostring- 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
bird_sms_inbound_stats_timeseries_getGet 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.Read-onlyGet Inbound SMS Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly fromstring- 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
timezonestring- 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
tostring- 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
bird_sms_keyword_rule_getReturn one keyword rule, either one of Bird's defaults or one you created, including every keyword that matches it and the reply it sends.Read-onlyGet SMS Keyword Rule
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.
Inputs
idstringrequired- ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_keyword_rules_listReturn the default and workspace keyword rules that apply to inbound messages, most specific first.Read-onlyList SMS Keyword Rules
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.
Inputs
countrystring- 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_countrystring- 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
numberstring- 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
operationstring- Keep only rules for this operation. Omit for all of them. Example: stop
scopestring- Keep only default rules (`system`) or only the rules you created (`workspace`). Omit for both. Example: systemone of
systemworkspace
bird_sms_message_events_listReturn the lifecycle event timeline for a message, in chronological order.Read-onlyList Events for an SMS Message
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.
Inputs
message_idstringrequired- ID of the SMS message (`sms_` prefix), as returned when the message was accepted. Example: sms_01krdgeqcxet5s7t44vh8rt9mg
typestring- Filter by event type, such as `sms.delivered` or `sms.failed`. Example: example
bird_sms_message_getReturn a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed.Read-onlyGet SMS Message
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.
Inputs
message_idstringrequired- ID of the message, as returned in the send response's `id` field. Example: sms_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_messages_listReturn the workspace's SMS messages as a cursor-paginated list, newest first.Read-onlyList SMS Messages
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.
Inputs
categorystring- Filter by category. Example: transactionalone of
transactionalmarketingauthenticationservice countrystring- 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_afterstring- 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_beforestring- 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
directionstring- Filter by direction. Omit for both. Example: outboundone of
outboundinbound ending_beforestring- 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_codearray- 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"]
fromstring- Filter by sender (E.164, alphanumeric, or short code; exact match). Example: +15557654321
limitinteger- Maximum number of items to return per page. Example: 25
referencestring- 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_afterstring- 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
statusarray- 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"]
tagarray- 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.
tostring- Filter by recipient phone number (E.164 exact match). Example: +14155550100
bird_sms_messaging_profile_getReturn one messaging profile, including its senders, reply numbers, and sending defaults.Read-onlyGet SMS Messaging Profile
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.
Inputs
profile_idstringrequired- ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_messaging_profiles_listReturn your workspace's messaging profiles, newest first.Read-onlyList SMS Messaging Profiles
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_sms_sender_getReturn one of your workspace's SMS senders with its per-country registration status.Read-onlyGet SMS Sender
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.
Inputs
sender_idstringrequired- ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_sender_requirements_listReturn the countries a sender can reach, each country's requirements, and the current registration status.Read-onlyList SMS What a Sender Needs to Send
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.
Inputs
sender_idstringrequired- ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg
country_codestring- Ask about one destination country. Omit to return every country relevant to the sender. Example: US
bird_sms_senders_listReturn the dedicated numbers and alphanumeric senders your workspace holds, newest first, with each sender's per-country registration status.Read-onlyList Your SMS Senders
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
number_idstring- 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
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- 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_atone of
created_atsender starting_afterstring- 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
typestring- Filter senders by source type: a dedicated number, shared shortcode, or alphanumeric sender string. Example: example
bird_sms_stats_breakdown_getGet outbound SMS statistics for a period grouped by one dimension (dimension): originators, countries, categories, error codes, carriers, tags, cost centers.Read-onlyGet Outbound SMS Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/sms/stats/. Example: originatorsone of
originatorscountriescategorieserror-codescarrierstagscost-centers fromstring- 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_trendboolean- 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
limitinteger- Maximum number of originator rows to return, ranked by the `sort` field descending. Example: 50
sortstring- 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: acceptedone of
acceptedsentdeliveredundeliveredfailedrejectedexpireddelivery_ratefailure_rate timezonestring- 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
tostring- 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_grainstring- Bucket grain for the `trend` series. Has no effect unless `include_trend=true`. Example: dailyone of
dailyhourly
bird_sms_stats_by_status_getReturn one row per lifecycle status with activity in the requested period, ordered by count descending.Read-onlyGet Outbound SMS Statistics by Status
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.
Inputs
fromstring- 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
timezonestring- 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
tostring- 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
bird_sms_stats_summary_getReturn one aggregate row for the requested period.Read-onlyGet Aggregate Outbound SMS Statistics
Return one aggregate row for the requested period. Returns an object with period, delivery, latency, comparison.
Inputs
carrierstring- Restrict the statistics to a single delivery carrier. Mutually exclusive with the other dimension filters; only one may be set per request. Example: Verizon
categorystring- Restrict the statistics to a single category. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
comparestring- 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_periodone of
previous_period cost_centerstring- 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
countrystring- 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
fromstring- 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
originatorstring- 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
timezonestring- 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
tostring- 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
bird_sms_stats_timeseries_getGet 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.Read-onlyGet Outbound SMS Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly carrierstring- Restrict the statistics to a single delivery carrier. Mutually exclusive with the other dimension filters; only one may be set per request. Example: Verizon
categorystring- Restrict the statistics to a single category. Mutually exclusive with the other dimension filters; only one may be set per request. Example: transactional
cost_centerstring- 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
countrystring- 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
fromstring- 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
originatorstring- 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
timezonestring- 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
tostring- 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
bird_sms_suppression_getReturn 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.Read-onlyGet SMS Suppression
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.
Inputs
suppression_idstringrequired- ID of the suppression, as returned when it was created or listed. Example: ssu_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_suppressions_listReturn the suppressions currently stopping your messages, most recent opt-out first.Read-onlyList SMS Suppressions
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.
Inputs
destinationstring- Return only suppressions for this exact subscriber number in E.164 form. Prefix matching is unsupported. Example: +15550001234
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
originatorstring- Return only suppressions covering this sender. Example: +15557654321
reasonstring- 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_stopone of
keyword_stopcarrier_opted_outmanual starting_afterstring- 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
bird_sms_template_getReturn one SMS template's metadata, policies, language states, draft revision, and draft and live version IDs.Read-onlyGet SMS Template
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.
Inputs
template_refstringrequired- 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
bird_sms_template_version_getReturn one version with its variables and text in every language.Read-onlyGet SMS Template Version
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.
Inputs
template_refstringrequired- The template's ID (`smt_…`) or slug. Example: order-shipped
version_idstringrequired- The version to read or reset. Example: smv_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_template_version_language_getReturn one language's full text, revision, content hash, and update time.Read-onlyGet SMS Template Version's Language
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.
Inputs
languagestringrequired- The language as a BCP-47 tag. Case and separator differences are accepted and canonicalized. Example: pt-BR
template_refstringrequired- The template's ID (`smt_…`) or slug. Example: order-shipped
version_idstringrequired- The version that holds the language. Example: smv_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_template_version_languages_listReturn the languages a version holds, ordered by canonical language tag, without their text.Read-onlyList SMS Template Version's Languages
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.
Inputs
template_refstringrequired- The template's ID (`smt_…`) or slug. Example: order-shipped
version_idstringrequired- The version whose languages to list. Example: smv_01krdgeqcxet5s7t44vh8rt9mg
bird_sms_template_versions_listReturn a cursor-paginated version history, newest first.Read-onlyList SMS Template's Versions
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.
Inputs
template_refstringrequired- The template's ID (`smt_…`) or slug. Example: order-shipped
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_sms_templates_listReturn SMS templates as a cursor-paginated list.Read-onlyList SMS Templates
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.
Inputs
categorystring- Return templates in this category. Example: transactionalone of
transactionalmarketingauthentication ending_beforestring- 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
languagestring- Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match. Example: pt-BR
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc qstring- A case-insensitive substring search across slug, name, and description. Example: jane
scopestring- Filter by who owns the template. Use `system` for built-in templates and `workspace` for templates your workspace created. Example: systemone of
systemworkspace sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
statusstring- Return templates with this lifecycle status. Example: activeone of
draftpendingactiverejectedinactive
bird_voice_call_recordings_listReturn everything captured across every leg of one call: its stored audio, each leg's view of it, and every transcription attempt over it.Read-onlyList Voice Call's Recordings and Transcripts
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.
Inputs
call_idstringrequired- 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
bird_voice_call_transcript_getReturn 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.Read-onlyGet Voice Call's Transcript
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.
Inputs
call_idstringrequired- 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
bird_voice_destinations_listReturn 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.Read-onlyList Voice Destination Countries
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.
Inputs
This tool takes no inputs.
bird_voice_leg_getReturn a single leg at any point in its lifecycle.Read-onlyGet Voice Leg
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.
Inputs
leg_idstringrequired- ID of the call leg to retrieve, as returned by the leg list or webhook events. Example: vcl_01k0p3v9wera3v6q6xw3e9y2mh
bird_voice_legs_listReturn a paginated list of the workspace's legs, ordered by start time descending.Read-onlyList Voice Legs
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.
Inputs
call_idstring- Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated. Example: vcs_01krdgeqcxet5s7t44vh8rt9mg
directionstring- Return only legs in this direction. Example: outboundone of
inboundoutbound ending_beforestring- 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
fromstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
numberstring- 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_idstring- Return only legs carried by this SIP trunk. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
started_afterstring- Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp. Example: 2026-01-15T09:30:00Z
started_beforestring- Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp. Example: 2026-01-15T09:30:00Z
starting_afterstring- 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
statusarray- Return only legs with one of these statuses, comma-separated. In-flight and final statuses may be combined freely. Example: ["answered"]
tagarray- 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.
tostring- 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
bird_voice_number_getReturn one of the numbers your workspace can use for voice.Read-onlyGet Voice Number
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.
Inputs
number_idstringrequired- ID of the voice number to retrieve or update, as returned by the voice number list. Example: vnu_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_numbers_listList 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.Read-onlyList Numbers You Can Use for Voice
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: ascone of
ascdesc providerstring- 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: allocationone of
allocationverified_number routestring- 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: rejectone of
rejecttrunkforwardsequencering_group searchstring- Matches part of the phone number or name, ignoring case. Characters such as `%` and `_` match literally. Example: jane
sortstring- Field to sort by. Example: phone_numberone of
phone_number starting_afterstring- 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
bird_voice_ring_group_getReturn one ring group.Read-onlyGet Voice Ring Group
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.
Inputs
ring_group_idstringrequired- ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_ring_group_members_listReturn the ring group's members, in the order they joined.Read-onlyList Voice Ring Group's Members
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.
Inputs
ring_group_idstringrequired- ID of the ring group whose members to list or add to. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_ring_groups_listReturn the workspace's ring groups.Read-onlyList Voice Ring Groups
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.
Inputs
This tool takes no inputs.
bird_voice_settings_getReturn the voice settings for your workspace.Read-onlyGet Voice Settings
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.
Inputs
This tool takes no inputs.
bird_voice_trunk_gateway_getReturn a single gateway by ID.Read-onlyGet Voice SIP Trunk Gateway
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.
Inputs
gateway_idstringrequired- ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
trunk_idstringrequired- ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_trunk_gateways_listReturn the gateway addresses used to forward inbound calls to this trunk, ordered by priority.Read-onlyList Voice SIP Trunk's Gateways
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.
Inputs
trunk_idstringrequired- ID of the SIP trunk whose gateways to list or create. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_trunk_getReturn a single SIP trunk, including its Bird-assigned `domain`, its IP access control lists, and its allowed API keys.Read-onlyGet Voice SIP Trunk
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.
Inputs
trunk_idstringrequired- ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_trunks_listReturn the workspace's SIP trunks as a paginated list, each with its assigned `domain` and access control lists.Read-onlyList Voice SIP Trunks
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_voice_verified_number_getReturn the verified number with the given ID, including its verification status.Read-onlyGet Voice Verified Number
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.
Inputs
verified_number_idstringrequired- ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
bird_voice_verified_numbers_listReturn a paginated list of the workspace's verified numbers and their verification status.Read-onlyList Voice Verified Numbers
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_webhook_attempts_listReturn the endpoint's recent delivery attempts, newest first.Read-onlyList Delivery Attempts
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
afterstring- Only return attempts strictly after this timestamp. Example: 2026-01-15T09:30:00Z
beforestring- Only return attempts strictly before this timestamp. Example: 2026-01-15T09:30:00Z
ending_beforestring- 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
limitinteger- Maximum number of attempts to return. Defaults to 50, capped at 100. Example: 50
starting_afterstring- 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
bird_webhook_callback_attempts_listReturn the workspace's recent delivery attempts to SMS callback URLs, newest first.Read-onlyList Callback Delivery Attempts
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).
Inputs
afterstring- Only return attempts strictly after this timestamp. Example: 2026-01-15T09:30:00Z
beforestring- Only return attempts strictly before this timestamp. Example: 2026-01-15T09:30:00Z
ending_beforestring- 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
limitinteger- Maximum number of attempts to return. Defaults to 50, capped at 100. Example: 50
starting_afterstring- 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
bird_webhook_getReturn one webhook endpoint's configuration and current delivery `status`, including its URL and subscribed event types.Read-onlyGet Webhook Endpoint
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
bird_webhooks_listReturn the workspace's webhook endpoints as a cursor-paginated list, newest first by default.Read-onlyList Webhook Endpoints
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort webhook endpoints by: `created_at` (the default; newest first with the default `order`) or the endpoint URL. Example: created_atone of
created_aturl starting_afterstring- 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
urlstring- 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/
bird_whatsapp_agent_notification_getReturn 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.Read-onlyGet WhatsApp Notification Sent to an Agent
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.
Inputs
notification_idstringrequired- ID of the notification (`waan_` prefix), as returned when it was sent. Example: waan_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_agent_notifications_listReturn the notifications you have sent your agents, newest first, each with what came of it.Read-onlyList WhatsApp Notifications Sent to Your Agents
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.
Inputs
ending_beforestring- 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
fromstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
statusstring- Return only notifications in this state. Example: successone of
acceptedsuccessskippedfailed tostring- 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
bird_whatsapp_business_account_getReturn 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.Read-onlyGet WhatsApp Business Account
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.
Inputs
business_account_refstringrequired- 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
bird_whatsapp_business_account_reach_estimate_getReturn Meta's estimate of how many marketing deliveries, and at what cost, each candidate maximum price would have won over `window`.Read-onlyEstimate WhatsApp Marketing Reach for a Maximum Price
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.
Inputs
business_account_refstringrequired- 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
countriesarrayrequired- 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"]
windowstring- The days of recent auctions the estimate is based on, ending now. Omit it to use the last 7 days. Example: 7done of
1d7d14d28d
bird_whatsapp_business_accounts_listReturn a paginated list of the WhatsApp Business Accounts your workspace has connected, so you can choose which one a template belongs to.Read-onlyList WhatsApp Business Accounts
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.
Inputs
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_whatsapp_conversation_events_listReturn the conversation's activity history, newest first: - A move of control between the Meta Business Agent and your application.Read-onlyList WhatsApp Conversation Events
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
typestring- Keep only events of this exact type (for example `whatsapp_conversation.control_changed`). Omit for every type.
bird_whatsapp_conversation_getReturn 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.Read-onlyGet WhatsApp Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_conversation_message_getReturn one message in a conversation.Read-onlyGet Message in a WhatsApp Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
message_idstringrequired- Message identifier. Starts with `wam_`. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_conversation_messages_listReturn the messages in one conversation, newest first, as a cursor-paginated list.Read-onlyList Messages in a WhatsApp Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
directionstring- Return only messages the contact sent (`inbound`) or only messages sent to them (`outbound`). Omit for both. Example: outboundone of
outboundinbound ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_whatsapp_conversations_listReturn the workspace's WhatsApp conversations as a cursor-paginated list, most recently active first.Read-onlyList WhatsApp Conversations
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.
Inputs
assigned_tostring- 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_numberstring- Return only conversations on this WhatsApp business phone number, in E.164 format. Omit to cover every number in the workspace. Example: +15550001234
controlstring- Return only conversations the agent holds (`meta_business_agent`) or that your workspace holds (`bird`). Example: bird
ending_beforestring- 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_statusstring- Filter by workspace inbox status. Omit to include open and resolved conversations. Example: openone of
openresolved labelarray- 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"]
limitinteger- Maximum number of items to return per page. Example: 25
qstring- 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_statusstring- Return only conversations whose customer-service window is `open` or `closed`. Example: openone of
openclosed starting_afterstring- 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
bird_whatsapp_group_getReturn one group as it currently stands, including who is in it.Read-onlyGet WhatsApp Group
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.
Inputs
group_idstringrequired- ID of the group, as returned when it was created. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_group_join_requests_listReturn the join requests still waiting for a decision, oldest first.Read-onlyList WhatsApp Group's Join Requests
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.
Inputs
group_idstringrequired- ID of the group whose join requests are being listed. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `asc`, which sorts alphabetically or from oldest to newest, depending on the selected sort field. Example: ascone of
ascdesc sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
bird_whatsapp_groups_listReturn the WhatsApp groups your workspace created as a cursor-paginated list, newest first.Read-onlyList WhatsApp Groups
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.
Inputs
created_afterstring- 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_beforestring- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
numberstring- 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
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc qstring- Case-insensitive substring match against the group's subject or description. Example: support
sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
statusarray- Filter by status. Repeat the parameter to match any of several statuses. Example: ["active"]
wabastring- Filter by the WABA identifier returned on the group. Groups with `waba: null` do not match this filter. Example: 102290129340398
bird_whatsapp_inbound_stats_by_phone_number_getReturn how many WhatsApp messages each of your business phone numbers received.Read-onlyGet Inbound WhatsApp Statistics by Phone Number
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.
Inputs
fromstring- 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
limitinteger- Maximum number of phone-number rows to return, ranked by received-message volume descending. Example: 50
timezonestring- 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
tostring- 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
bird_whatsapp_inbound_stats_summary_getReturn the total number of WhatsApp messages your business numbers received over the period, using the time each message reached your number.Read-onlyGet Aggregate Inbound WhatsApp Statistics
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.
Inputs
comparestring- 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_periodone of
previous_period fromstring- 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
timezonestring- 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
tostring- 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
bird_whatsapp_inbound_stats_timeseries_getGet 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.Read-onlyGet Inbound WhatsApp Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly fromstring- 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
timezonestring- 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
tostring- 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
bird_whatsapp_keyword_rule_getReturn one keyword rule, either one of Bird's own or one you created, with its `effective_keywords` and the reply it sends.Read-onlyGet WhatsApp Keyword Rule
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.
Inputs
idstringrequired- ID of the keyword rule, as returned by the list operation. Bird's own rules and yours share one ID space. Example: wkr_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_keyword_rules_listReturn the keyword rules that apply to inbound messages, most specific first.Read-onlyList WhatsApp Keyword Rules
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.
Inputs
countrystring- 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
operationstring- 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
scopestring- Keep only Bird's own rules (`system`) or only the rules you created (`workspace`). Omit for both. Example: workspaceone of
systemworkspace wabastring- 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
bird_whatsapp_message_events_listReturn a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (`whatsapp.accepted`, `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`).Read-onlyList Events for a WhatsApp Message
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.
Inputs
message_idstringrequired- ID of the message, as returned in the send response's `id` field. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
typestring- Keep only events of this exact type (for example `whatsapp.delivered` or `whatsapp.failed`). Omit for the full timeline.
bird_whatsapp_message_getReturn a single WhatsApp message: its current delivery status, per-stage timestamps (`sent_at`, `delivered_at`, `read_at`), and failure detail when it failed.Read-onlyGet WhatsApp Message
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.
Inputs
message_idstringrequired- ID of the message, as returned in the send response's `id` field. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_message_reaction_events_listReturn 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.Read-onlyList Reaction Events for a WhatsApp Message
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.
Inputs
message_idstringrequired- ID of the message whose reactions to read, as returned in the `id` field of the message. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_whatsapp_messages_listReturn the workspace's WhatsApp messages as a cursor-paginated list, newest first, outbound and inbound alike.Read-onlyList WhatsApp Messages
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.
Inputs
bsuidstring- 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
categorystring- Filter by category. Example: transactional
created_afterstring- 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_beforestring- 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
directionstring- Filter by whether the business sent the message (`outbound`) or received it from the contact (`inbound`). Example: outboundone of
outboundinbound ending_beforestring- 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
fromstring- 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_idstring- 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
limitinteger- Maximum number of items to return per page. Example: 25
phone_numberstring- 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
referencestring- 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_afterstring- 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
statusarray- Filter by status. Repeat the parameter to match any of several statuses. Example: ["scheduled"]
tagarray- 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.
tostring- 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
bird_whatsapp_number_events_listReturn the number's activity history, newest first by default: - The number being added, and every change of its status.Read-onlyList WhatsApp Number Events
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.
Inputs
number_idstringrequired- ID of the WhatsApp number whose events to list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc sortstring- Field to sort by. Defaults to `created_at`. Example: created_atone of
created_at starting_afterstring- 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
bird_whatsapp_number_getReturn a WhatsApp number connected to the workspace and its state as of `meta_synced_at`.Read-onlyGet WhatsApp Number
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.
Inputs
number_idstringrequired- ID of the WhatsApp number (`wan_` prefix), as returned by the number list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_number_profile_getReturn the business profile WhatsApp shows to people this number messages, read from WhatsApp on each request rather than from a stored copy.Read-onlyGet WhatsApp Number's Business Profile
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.
Inputs
number_idstringrequired- ID of the WhatsApp number (`wan_` prefix), as returned by the number list. Example: wan_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_numbers_listReturn a paginated list of the WhatsApp numbers your workspace can send from.Read-onlyList WhatsApp Numbers
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.
Inputs
ending_beforestring- 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_totalboolean- When true, the response includes a `total` field with the total number of items matching the request's filters across all pages. Example: false
limitinteger- Maximum number of items to return per page. Example: 25
orderstring- Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Example: descone of
ascdesc phone_numberstring- 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
scopestring- 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: workspaceone of
systemworkspace sortstring- Field to sort by. Example: created_atone of
created_at starting_afterstring- 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
statusarray- 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"]
wabastring- 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
bird_whatsapp_stats_breakdown_getGet outbound WhatsApp statistics for a period grouped by one dimension (dimension): error codes, templates, template categories, tags, phone numbers, countries.Read-onlyGet Outbound WhatsApp Statistics Breakdown
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.
Inputs
dimensionstringrequired- What to group the statistics by. Each value maps to its own Bird endpoint under /v1/whatsapp/stats/. Example: error-codesone of
error-codestemplatestemplate-categoriestagsphone-numberscountries fromstring- 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
limitinteger- Maximum number of error-code rows to return, ranked by failure count descending. Example: 50
timezonestring- 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
tostring- 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
bird_whatsapp_stats_summary_getReturn one aggregate row for the requested period.Read-onlyGet Aggregate Outbound WhatsApp Statistics
Return one aggregate row for the requested period. Returns an object with period, delivery, engagement, latency, comparison.
Inputs
categorystring- 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
comparestring- 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_periodone of
previous_period fromstring- 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_numberstring- 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
tagstring- 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
templatestring- 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
timezonestring- 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
tostring- 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
bird_whatsapp_stats_timeseries_getGet 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.Read-onlyGet Outbound WhatsApp Statistics Time Series
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.
Inputs
granularitystringrequired- Time bucket size for the series: daily returns one row per day, hourly one row per hour. Example: dailyone of
dailyhourly categorystring- 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
fromstring- 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_numberstring- 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
tagstring- 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
templatestring- 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
timezonestring- 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
tostring- 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
bird_whatsapp_suppression_getReturn the suppression record for the given ID, including one that has already ended.Read-onlyGet WhatsApp Suppression
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.
Inputs
suppression_idstringrequired- ID of the WhatsApp suppression record to retrieve or end. Example: was_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_suppressions_listReturn a paginated list of the WhatsApp addresses the workspace is currently suppressing.Read-onlyList WhatsApp Suppressions
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.
Inputs
addressstring- Address prefix filter (case-insensitive). A complete address returns only that address; a partial value returns all matches. Example: +5511977670804
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
reasonstring- Return only suppressions with this reason: - `manual`: Added through the API or dashboard. Example: manualone of
manual starting_afterstring- 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
bird_whatsapp_template_getReturn 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.Read-onlyGet WhatsApp Message Template
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.
Inputs
template_refstringrequired- 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
bird_whatsapp_template_version_getReturn one version: the content of every language it holds and what its submission did with each.Read-onlyGet WhatsApp Template Version
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.
Inputs
template_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_template_version_language_getReturn 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.Read-onlyGet WhatsApp Version's Language
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.
Inputs
languagestringrequired- 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_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_template_version_languages_listReturn 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.Read-onlyList WhatsApp Version's Languages
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.
Inputs
template_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
bird_whatsapp_template_versions_listReturn the template's versions, newest first.Read-onlyList WhatsApp Template's Versions
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.
Inputs
template_refstringrequired- 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_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
starting_afterstring- 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
bird_whatsapp_templates_listReturn 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`.Read-onlyList WhatsApp Available Message Templates
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.
Inputs
categorystring- Filter by template category. Example: transactional
ending_beforestring- 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
limitinteger- Maximum number of items to return per page. Example: 25
qstring- A case-insensitive substring search across the template's slug, name, and description. Example: jane
scopestring- 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: systemone of
systemworkspace starting_afterstring- 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
statusarray- Filter by lifecycle status. Repeat the parameter to match any of several. Our built-in templates are always `active`. Example: ["active"]
wabastring- 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
bird_workspace_getReturn 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.Read-onlyGet Current Workspace
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.
Inputs
This tool takes no inputs.
bird_workspace_quotas_listReturn 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.Read-onlyList Workspace Quotas
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.
Inputs
This tool takes no inputs.
bird_workspace_rate_limits_listOnly relevant to organizations with several workspaces, or one left with a workspace limit or enabled allocation after a deletion.Read-onlyList Workspace Rate Limits
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.
Inputs
This tool takes no inputs.
bird_amb_attachment_createUpload a file to Apple for the business account identified by `from` and returns an attachment you can send by `attachment_id`.WriteUpload Apple Messages Attachment
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.
Inputs
fromstringrequired- 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_keystringrequired- 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_urlstringrequired- 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_typestring- Media type of the file. Defaults to the type Bird detects from the contents. Example: application/pdf
namestring- Display filename. Defaults to the last segment of the source_url path. Example: receipt.pdf
bird_amb_business_account_createCreate an Apple Messages for Business record in your workspace.WriteCreate Apple Messages for Business Record
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.
Inputs
namestringrequired- The brand name shown for this business record inside Bird. Example: Acme Retail
apple_business_idstring- 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_keystring- 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
bird_amb_business_account_reconnectRestore the local connection.WriteReconnect Apple Business Account
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record to reconnect, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_amb_business_account_submission_createSubmit an account for review and queues an automated review of its three evidence attachments.WriteSubmit Apple Messages for Business Business for Review
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
readiness_attachment_idstringrequired- Uploaded PDF attachment containing the business readiness assessment. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
use_cases_attachment_idstringrequired- Uploaded PDF attachment describing the proposed customer use cases. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
video_attachment_idstringrequired- Uploaded MP4 attachment demonstrating the customer experience. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_amb_business_account_updateChange your workspace's Apple Messages for Business record.WriteUpdate Apple Messages for Business Record
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
apple_business_idstring- 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_keystring- 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
namestring- The brand name shown for this business record inside Bird. Example: Acme Retail
bird_amb_channel_settings_updateChange the channel settings for your workspace's Apple Messages for Business record.WriteUpdate Apple Messages for Business Channel Settings
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.
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
brand_namestring- The brand name shown on the Bird-hosted landing page customers use to connect this business. Example: Acme Retail
default_localestring- 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_pointsarray- 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_keystring- 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_idstring- The business's logo, as an asset in your media library. Send null to clear it. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
bird_amb_conversation_typing_sendSend a typing indicator to the customer's device on this conversation.WriteSend Apple Messages Typing Indicator
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
eventstringrequired- 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_startone of
typing_starttyping_end idempotency_keystring- 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
bird_amb_conversation_updateUpdate assignment, labels, inbox status, queue, or shared workspace read state, or settles a pending `routing_change`.WriteUpdate Apple Messages Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `acv_`. Example: acv_01krdgeqcxet5s7t44vh8rt9mg
assigned_tostring- 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_keystring- 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_statusstring- 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: openone of
openresolved labelsarray- 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"]
queuestring- 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
readstring- 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_changeobject- 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"}
bird_amb_message_sendSend an Apple Messages for Business message into a conversation with an Apple customer.WriteSend Apple Messages Message
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.
Inputs
fromstringrequired- 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
tostringrequired- 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
categorystring- 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
groupstring- Department identifier for this message. Example: example
idempotency_keystring- 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
intentstring- Purpose of this conversation. Example: example
interactiveobject- 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"}]}]}}
localestring- Apple locale identifier, for example en_US. Defaults to the conversation locale.
metadataobject- 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"}
referencestring- 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_linkobject- 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_typingboolean- 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
sourcestring- 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: operatorone of
operatorautomationapi tagsarray- Structured `{name, value}` labels for filtering. Maximum 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
templateobject- 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"}
textobject- 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."}
bird_amb_routing_rule_createCreate a routing rule for one of your Apple Messages for Business brands.WriteCreate Apple Messages for Business Routing Rule
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.
Inputs
business_account_idstringrequired- The Apple Messages for Business brand this rule belongs to. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
match_kindstringrequired- 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: bothone of
intentgroupboth queuestringrequired- The queue a matching conversation is filed into. Your console lists whichever values your rules use. Example: billing
idempotency_keystring- 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_defaultboolean- 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_idstring- 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_idstring- 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
precedenceinteger- Evaluation order among this business's rules. The highest-precedence rule a conversation matches wins. Omit it to default to 0. Example: 10
bird_amb_routing_rule_updateChange a routing rule's business, match, queue, precedence, or default status.WriteUpdate Apple Messages for Business Routing Rule
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.
Inputs
routing_rule_idstringrequired- ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg
business_account_idstring- Move this rule to another Apple Messages for Business brand in the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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_defaultboolean- 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_idstring- 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_idstring- 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_kindstring- 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: bothone of
intentgroupboth precedenceinteger- Change this rule's evaluation order among the business's other rules. Example: 20
queuestring- Change the queue this rule files a matching conversation into. Example: billing
bird_amb_suppression_createManually opens a suppression episode for a address, blocking every outbound path to it: operator and automated replies, API sends, typing indicators, and invitations.WriteCreate Apple Messages for Business Suppression
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.
Inputs
addressstringrequired- The phone number or opaque identifier to suppress. For a phone number, supply canonical E.164 with a leading plus sign. Example: +15551234567
address_typestringrequired- 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_numberone of
phone_numberopaque_user_id business_account_idstring- Limit this manual block to one account. Omit to cover the same address across the workspace. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_folder_createCreate a folder in the workspace's media library.WriteCreate Folder in the Media Library
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.
Inputs
namestringrequired- 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_keystring- 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_idstring- 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
bird_asset_folder_updateRename or move a media-library folder.WriteRename or Move a Media-library Folder
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.
Inputs
folder_idstringrequired- ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
namestring- 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_idstring- 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
bird_asset_updateUpdate asset metadata or folder placement.WriteUpdate Asset Metadata or Folder Placement
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.
Inputs
asset_idstringrequired- ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
alt_textstring- Default alternative text describing the image. Send null to clear it. Example: Hello from Bird
folder_idstring- 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_keystring- 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
namestring- The asset's display name. Example: sk-test-sample
bird_asset_upload_session_browser_openOffer an existing upload session to a signed-in person with asset write access in its workspace.WriteOpen Browser Fallback for a Media Upload
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.
Inputs
upload_idstringrequired- ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_upload_session_cancelCancel an unfinished upload.WriteCancel Media-library Upload
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.
Inputs
upload_idstringrequired- ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_upload_session_completeVerify the uploaded file and publishes a media-library asset at a permanent public URL.WriteComplete Media-library Upload
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.
Inputs
upload_idstringrequired- ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_upload_session_createCreate or recovers a session.WriteCreate Media-library Upload Session
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.
Inputs
client_referencestringrequired- 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
fileobjectrequired- 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_textstring- Default alternative text for the asset. Example: Hello from Bird
folder_idstring- Destination folder in this workspace. Omit it to use the library root. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
namestring- Display name. Omitted or blank names default to the sanitized filename. Example: sk-test-sample
bird_asset_upload_session_prepareRefresh the temporary upload instruction for a pending session.WriteRefresh Media-library Upload Instruction
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.
Inputs
upload_idstringrequired- ID of the media-library upload session. Example: aus_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_audience_contacts_addAdd up to 1,000 contacts to an audience.WriteAssign Contacts to an Audience
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.
Inputs
audience_idstringrequired- ID of the audience to add contacts to. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
contact_idsarrayrequired- 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_keystring- 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
bird_audience_contacts_removeRemove up to 1,000 contacts from an audience.WriteUnassign Contacts from an Audience
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.
Inputs
audience_idstringrequired- ID of the audience to remove contacts from. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
contact_idsarrayrequired- 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_keystring- 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
bird_audience_createCreate an audience in the workspace.WriteCreate Audience
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.
Inputs
namestringrequired- Display name for the audience. Example: sk-test-sample
descriptionstring- Longer description of who this audience is. Example: Created by the Scalekit connector
idempotency_keystring- 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
typestring- How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts. Example: staticone of
static
bird_audience_updateUpdate an audience's name or description.WriteUpdate Audience
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.
Inputs
audience_idstringrequired- ID of the audience to update. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
descriptionstring- Longer description of who this audience is. Set to null to clear. Example: Created by the Scalekit connector
idempotency_keystring- 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
namestring- 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
bird_compliance_identity_createCreate an identity.WriteCreate Identity
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.
Inputs
namestringrequired- What you call this party. Yours to choose; it is never sent to a carrier. Example: Goldcrest Communications SAS
idempotency_keystring- 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
bird_compliance_identity_updateUpdate an identity name.WriteUpdate Identity Name
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.
Inputs
identity_idstringrequired- Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
namestringrequired- What you call this party. Yours to choose; it is never sent to a carrier. Example: Goldcrest Communications SAS
idempotency_keystring- 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
bird_compliance_submission_createSubmit every answer at once.WriteCreate Registration Submission
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.
Inputs
answersarrayrequired- 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_codestringrequired- ISO 3166-1 alpha-2 country code. Example: US
programstringrequired- 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_idstringrequired- 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_kindstringrequired- 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_senderone of
sms_sendernumbernumber_emergencyidentity idempotency_keystring- 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
identityobject- 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_idstring- 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
bird_compliance_submission_resupplyReplace rejected, expired, or missing answers on an existing submission.WriteUpdate Compliance Answers
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.
Inputs
answersarrayrequired- 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_idstringrequired- Submission ID. Example: csb_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_contact_createCreate a contact in the workspace, identified by an email address, a phone number, or both; at least one is required.WriteCreate Contact
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.
Inputs
dataobject- 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"}
emailstring- 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_idstring- Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
first_namestring- The contact's first name. Example: Jane
idempotency_keystring- 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_namestring- The contact's last name. Example: Doe
phone_numberstring- 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
bird_contact_property_archiveArchiving is how you remove a contact property.WriteArchive Contact Property
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.
Inputs
property_idstringrequired- ID of the contact property to archive. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_contact_property_createCreate a contact property.WriteCreate Contact Property
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.
Inputs
keystringrequired- 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
typestringrequired- 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
stringnumberbooleandatetime fallback_valuestring- 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_keystring- 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
bird_contact_property_unarchiveRestore an archived contact property with its stored values.WriteUnarchive Contact Property
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.
Inputs
property_idstringrequired- ID of the contact property to unarchive. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_contact_property_updateUpdate a contact property's fallback value, the only mutable field.WriteUpdate Contact Property
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.
Inputs
property_idstringrequired- ID of the contact property to update. Example: prp_01krdgeqcxet5s7t44vh8rt9mg
fallback_valuestring- 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_keystring- 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
bird_contact_updateUpdate a contact.WriteUpdate Contact
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.
Inputs
contact_idstringrequired- ID of the contact to update. Example: con_01krdgeqcxet5s7t44vh8rt9mg
dataobject- 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"}
emailstring- 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_idstring- Your own identifier for this contact. Unique within the workspace when set. Set to `null` to clear. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
first_namestring- The contact's first name. Set to `null` to clear. Example: Jane
idempotency_keystring- 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_namestring- The contact's last name. Set to `null` to clear. Example: Doe
phone_numberstring- 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
bird_contacts_batch_createCreate or updates up to 1,000 contacts in one request.WriteCreate or Update Contacts in Bulk
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.
Inputs
contactsarrayrequired- 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_idsarray- 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_modestring- 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: mergeone of
mergereplace idempotency_keystring- 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_onstring- 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: emailone of
emailphone_numberexternal_id
bird_email_broadcast_cancelCancel a broadcast that is scheduled, accepted, sending, waiting for funds, or paused.WriteCancel Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
idempotency_keystring- 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
bird_email_broadcast_createCreate a broadcast for a stored audience.WriteCreate Email Broadcast
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.
Inputs
audience_idstring- 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
categorystring- 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: marketingone of
marketingtransactional fromobject- 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>
headersobject- 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_keystring- 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_idstring- 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
metadataobject- 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_toarray- 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_atstring- 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
sendboolean- 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
tagsarray- 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"}]
templateobject- 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_clicksboolean- Whether to track link clicks for this broadcast. Example: true
track_opensboolean- Whether to track opens for this broadcast. Example: true
bird_email_broadcast_resumeResume a broadcast.WriteResume Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
confirmboolean- 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_keystring- 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
bird_email_broadcast_sendSend a draft or scheduled broadcast, either immediately or at `scheduled_at`.WriteSend Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
idempotency_keystring- 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_atstring- 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
bird_email_broadcast_test_sendSupply 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.WriteSend Email Rendered Broadcast Test
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Example: eb_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystringrequired- 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_fingerprintstringrequired- The `preview_fingerprint` returned by the preview whose content you are sending. Example: fingerprint_from_matching_preview
tostringrequired- The email address of a current organization member with access to this workspace. Example: member@example.com
contact_idstring- 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
fromobject- 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>
headersobject- 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_toarray- Replaces the reply-to addresses for this request. Null removes them. Example: ["Jane Doe <jane@acme.com>"]
templateobject- Replaces the template, language or parameters for this request. Null removes the template for this request. Example: {"id": "emt_01krdgeqcxet5s7t44vh8rt9mg", "language": "pt-BR"}
bird_email_broadcast_updateUpdate a draft or scheduled broadcast.WriteUpdate Email Broadcast
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.
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
audience_idstring- 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
categorystring- 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: marketingone of
marketingtransactional fromobject- 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>
headersobject- 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_keystring- 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_idstring- 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
metadataobject- 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_toarray- Where replies to this broadcast should go. Set this to null to remove the addresses already set. Example: ["Jane Doe <jane@acme.com>"]
tagsarray- 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"}]
templateobject- 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_clicksboolean- Whether to track link clicks for this broadcast. Example: false
track_opensboolean- Whether to track opens for this broadcast. Example: false
bird_email_competitive_watchlist_brand_addAdd a brand to the workspace's watchlist so its figures appear next to your own.WriteAdd Email Competitor Brand to the Watchlist
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.
Inputs
brand_idstringrequired- 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_keystring- 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
bird_email_domain_createCreate a sending domain.WriteCreate Sending Domain
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.
Inputs
domainstringrequired- 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
dkimobject- DKIM signing configuration. Example: {"mode": "txt"}
idempotency_keystring- 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_pathobject- 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"}
settingsobject- Per-domain behavior toggles. Changes apply immediately to new sends. Example: {"click_tracking": false, "open_tracking": false}
trackingobject- 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"}
bird_email_domain_updateUpdate settings and configuration on a sending domain.WriteUpdate Sending Domain
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.
Inputs
domain_idstringrequired- ID of the domain to update. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
default_ip_pool_idstring- 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
dkimobject- 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_keystring- 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
inboundobject- 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_pathobject- Change the return-path name part. Cannot be removed: the return-path is required for sending. Example: {"name": "send"}
settingsobject- Per-domain behavior toggles. Changes apply immediately to new sends. Example: {"click_tracking": false, "open_tracking": false}
trackingobject- 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"}
bird_email_domain_verifyVerify a domain.WriteVerify Domain
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.
Inputs
domain_idstringrequired- ID of the domain to verify. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_inbound_address_createCreate a new inbound address.WriteCreate Email Inbound Address
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.
Inputs
idempotency_keystring- 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
labelstring- Your own label for this address, typically the source mailbox it maps to. Example: Support mailbox
bird_email_inbound_address_updateUpdate the label on an inbound address.WriteUpdate Email Inbound Address
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.
Inputs
inbound_address_idstringrequired- Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
labelstring- 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
bird_email_inbound_route_createCreate a routing rule that delivers matching inbound mail on one of your domains to a mailbox, or drops it.WriteCreate Email Inbound Route
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.
Inputs
actionstringrequired- 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_mailboxone of
deliver_to_mailboxdrop domainstringrequired- The domain the route applies to. It has to be one of your inbound-enabled custom domains. Example: mail.acme.com
match_typestringrequired- 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: addressone of
addresscatch_all enabledboolean- Whether the route is evaluated. Example: true
idempotency_keystring- 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_valuestring- The local part an `address` route matches. Required for `address` routes. Stored lowercase. Example: refunds
priorityinteger- 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_idstring- The mailbox that receives matching mail. Required for `deliver_to_mailbox` routes. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbound_route_updateUpdate an inbound route.WriteUpdate Email Inbound Route
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.
Inputs
route_idstringrequired- Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg
actionstring- 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_mailboxone of
deliver_to_mailboxdrop enabledboolean- Whether the route is evaluated. Example: false
idempotency_keystring- 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_typestring- How the route matches recipients. Example: addressone of
addresscatch_all match_valuestring- The local part an `address` route matches. `null` for `catch_all` routes. Example: sk-test-value
priorityinteger- 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_idstring- The mailbox that receives matching mail. `null` for `drop` routes. Example: mbx_01krdgeqcxet5s7t44vh8rt9mg
bird_email_inbox_insights_domain_monitoring_setSwitch Inbox Insights on for the workspace's main sending domain.WriteSwitch Inbox Insights on for the Workspace's Main Sending Domain
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.
Inputs
idempotency_keystring- 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
bird_email_inbox_insights_domain_updateChange the workspace's monitoring preference for one of its verified sending domains.WriteSwitch Inbox Insights on or Off for a Sending Domain
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.
Inputs
monitoredbooleanrequired- 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_domainstringrequired- 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_keystring- 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
bird_email_inbox_insights_seed_test_createRegister a seed test and get its addresses.WriteRegister Email Seed Test and Get Its Addresses
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.
Inputs
engagement_profilestringrequired- Which engagement behaviour the seeds should simulate. Mixing both behaviours is what makes the engaged-against-dormant comparison measurable. Example: all
list_typestringrequired- Which seed pool to draw addresses from. Use a value the seed-test configuration reports as available for this account. Example: private
regionsarrayrequired- The regions to place seeds in, as the seed-test configuration names them. Example: ["North America - US", "Europe - UK"]
sending_domainstringrequired- The sending domain the test measures: one of the workspace's verified sending domains, exactly as it appears there. Example: mail.acme.com
idempotency_keystring- 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
labelstring- A name attached to this registration. It is not returned in seed-test history. Example: Fall preview send
bird_email_message_cancelCancel a message that was scheduled with `scheduled_at` before it sends.WriteCancel Email Scheduled Message
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.
Inputs
message_idstringrequired- ID of the scheduled message to cancel, from the send response's `id` field. Example: em_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_message_sendSend an email to explicit to, cc and bcc recipients, either inline (subject plus html or text) or from a published template with template parameters.WriteCreate Email Message
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.
Inputs
fromobjectrequired- 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"}
toarrayrequired- 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"}]
attachmentsarray- 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"}]
bccarray- 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>"]
categorystring- 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: marketingone of
marketingtransactional ccarray- 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>"]
headersobject- 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"}
htmlstring- HTML body. At least one of html or text must be provided. Example: <p>My first Bird email.</p>
idempotency_keystring- 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_idstring- 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
metadataobject- 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"}
parametersobject- 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"}
referencestring- 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_toarray- 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_atstring- 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
subjectstring- Message subject line. Required for inline sends. Omit it when sending a `template` (the template supplies the subject). Example: Hello from Bird
tagsarray- 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"}]
templateobject- 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"}
textstring- Plain-text body. At least one of html or text must be provided. Example: Hello from Bird
track_clicksboolean- Whether to track click events for this message. Example: true
track_opensboolean- Whether to track open events for this message. Example: true
bird_email_messages_batch_sendSend a batch of independent email messages in one request, each with its own recipients and content or template.WriteCreate Batch of Email Messages
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.
Inputs
messagesarrayrequired- 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_keystring- 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
bird_email_smtp_config_updateSet the default send options applied to messages submitted over SMTP with this API key: - Which IP pool to send from.WriteUpdate Email SMTP Config for an API Key
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.
Inputs
api_key_idstringrequired- ID of the API key the config applies to, the same key your SMTP client authenticates with. Example: key_01krdgeqcxet5s7t44vh8rt9mg
categorystring- 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: marketingone of
marketingtransactional idempotency_keystring- 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_idstring- 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
tagsarray- 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_clicksboolean- Whether to track click events for messages submitted over SMTP with this key. Omit to leave unchanged. Example: false
track_opensboolean- Whether to track open events for messages submitted over SMTP with this key. Omit to leave unchanged. Example: false
bird_email_suppression_createAdd an email address to the suppression list, stopping all email to it.WriteCreate Email Suppression
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.
Inputs
emailstringrequired- The address to stop sending to. Normalized before storage and matching: lowercased and trimmed of surrounding whitespace. Example: jane@example.com
idempotency_keystring- 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
bird_email_template_createCreate a template and its first editable draft.WriteCreate Email Template
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.
Inputs
categorystringrequired- Whether the template is for `transactional` email or `marketing` email. Example: transactionalone of
transactionalmarketing slugstringrequired- 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
sourcestringrequired- 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: htmlone of
html default_languagestring- 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
descriptionstring- What the template is for, in your own words. Example: Sent to new customers after signup.
idempotency_keystring- 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_requiredboolean- 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
languagesobject- 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>\n<p>Hi {{ first_name }}, thanks for signing up.</p>\n</body>\n</html>\n"}}
namestring- 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_languagestring- What a send does when it asks for a language this template does not carry. Defaults to `fallback` on email. Example: fallbackone of
fallbackfail
bird_email_template_duplicateCreate a new template by copying an existing one: one of your workspace templates, or a built-in `system` template (by its `bird_` slug).WriteDuplicate Email Template
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.
Inputs
template_refstringrequired- 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_keystring- 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
slugstring- 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
bird_email_template_language_setUpsert one language of a draft.WriteUpsert Email One Language of a Draft
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.
- Idempotent
Inputs
languagestringrequired- The language as a BCP-47 tag. Example: pt-BR
subjectstringrequired- 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_refstringrequired- 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_idstringrequired- The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
htmlstring- The HTML body for this language. Example: <h1>Hi {{ bird.contact.first_name }}</h1>
idempotency_keystring- 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_textstring- 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
revisioninteger- 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
textstring- 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
bird_email_template_language_updateChange 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.WriteUpdate Email One Language of a Draft
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.
Inputs
languagestringrequired- The language as a BCP-47 tag. Example: pt-BR
template_refstringrequired- 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_idstringrequired- The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
htmlstring- A new HTML body for this language. Example: <h1>Hi {{ bird.contact.first_name }}</h1>
idempotency_keystring- 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_textstring- 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
revisioninteger- 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
subjectstring- The email subject line. It may be empty in a draft but is required to publish. Example: Welcome to Acme, {{ bird.contact.first_name }}!
textstring- 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
bird_email_template_rollbackRoll back an email template.WriteRoll Back an Email Template
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.
Inputs
revisionintegerrequired- 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_refstringrequired- 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_idstringrequired- The published version to restore. Example: emv_01krdgeqcxet5s7t44vh8rt9mh
idempotency_keystring- 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
bird_email_template_updateUpdate a template's metadata and draft settings, such as its name or default language.WriteUpdate Email Template
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.
Inputs
revisionintegerrequired- 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_refstringrequired- 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_languagestring- 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
descriptionstring- What the template is for, in your own words. Send `null` to clear it. Example: Created by the Scalekit connector
idempotency_keystring- 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_requiredboolean- 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
namestring- 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_languagestring- What a send does when it asks for a language this template does not carry. Example: fallbackone of
fallbackfail
bird_email_template_version_submitSubmit the template's draft as a new immutable, numbered version and makes it the live version used by sends.WriteSubmit Email Template Version
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.
Inputs
template_refstringrequired- 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_idstringrequired- The draft version to validate or publish. Example: emv_01krdgeqcxet5s7t44vh8rt9mh
expected_revisioninteger- 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_keystring- 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
languagesarray- 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_onlyboolean- 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
bird_email_thread_message_replyReply to a message in a mailbox email thread, keeping the reply in the same thread.WriteReply Email to a Thread Message
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.
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
attachmentsarray- 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"}]
bccarray- 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_replyboolean- 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
categorystring- 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: transactionalone of
marketingtransactional ccarray- 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"]
htmlstring- HTML body of the reply. At least one of html or text must be provided. Example: <p>Hello from Bird</p>
idempotency_keystring- 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
metadataobject- Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized. Example: {"key": "value"}
reply_allboolean- Also send the reply to the original To and Cc recipients, minus the mailbox's own address. Example: false
scheduled_atstring- 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
tagsarray- Structured `{name, value}` labels for filtering and analytics on the sent-message log. Cap: 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
textstring- Plain-text body of the reply. At least one of html or text must be provided. Example: Hello from Bird
bird_email_thread_message_updateUpdate a message in a thread.WriteUpdate Email Message in a Thread
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.
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
contact_idstring- Contact to link this message to, or null to unlink the current contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
labelsobject- 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"]}
bird_email_thread_restoreRestore the conversation's unexpired trashed messages and updates its message and unread counts.WriteRestore Email Thread from Trash
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.
Inputs
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_thread_updateSet the conversation's `read` state and `folder`, adds or removes custom `labels`, and links or unlinks a contact.WriteUpdate Email Thread
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.
Inputs
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
contact_idstring- Contact to link this conversation to, or null to unlink the current contact. Example: con_01krdgeqcxet5s7t44vh8rt9mg
folderstring- 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: inboxone of
inboxarchivespam idempotency_keystring- 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
labelsobject- 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"]}
readboolean- Mark all retained received messages read or unread. Includes trash, spam and blocked messages; unread_count continues to exclude them. Example: false
bird_esim_assignment_createAssign an existing, allocated eSIM to a subscriber in the same workspace.WriteAssign eSIM to a Person
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.
Inputs
esim_idstringrequired- The esim id. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
subscriber_idstringrequired- Subscriber in this workspace to assign to the eSIM. Example: esub_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_credentials_deliverSend a hosted installation link by email or SMS.WriteSend Install Credentials to the Traveler
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.
Inputs
channelstringrequired- Channel the install credentials are delivered over. Example: smsone of
emailsms esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
tostringrequired- Recipient address. An email address for the email channel, an E.164 phone number for the sms channel. Example: +31612345678
idempotency_keystring- 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
localestring- Language for the message. Falls back to the closest available language, then English. Example: nl
bird_esim_install_link_createCreate a link to a hosted installation page for one eSIM.WriteCreate Hosted Install Link
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_order_cancelCancel an order waiting for funds in `charging`.WriteCancel Unfunded Order
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.
Inputs
order_idstringrequired- Order ID. Example: eor_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_order_createOrder a data package.WriteOrder Data Package
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.
Inputs
offer_idstringrequired- Offer to purchase. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
acknowledge_shortened_validityboolean- 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_namestring- Free-text label for the new eSIM, for your own reference. Ignored when esim_id is set. Example: Amsterdam trip, order 8812
esim_idstring- Existing eSIM to add the package to. Omit to provision a new eSIM. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
expected_priceobject- 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_keystring- 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
metadataobject- 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_revisioninteger- 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
recurrenceobject- 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_idstring- 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
tagsarray- Tags for the new eSIM, echoed on its lifecycle webhook events. Ignored when esim_id is set. Example: [{"name": "category", "value": "welcome"}]
bird_esim_recurring_subscription_cancelStop future package renewal at the current paid boundary.WriteCancel Recurring eSIM Renewal
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.
Inputs
subscription_idstringrequired- The recurring eSIM service. Example: ers_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_recurring_subscription_createStart a recurring package on an assigned eSIM and purchases the first period.WriteCreate Recurring eSIM Subscription
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.
Inputs
accepted_priceobjectrequired- 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_idstringrequired- Assigned eSIM receiving the recurring package. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystringrequired- 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_idstringrequired- Offer whose recurring terms the buyer accepted. Example: eof_01krdgeqcxet5s7t44vh8rt9mg
offer_revisionintegerrequired- The accepted offer revision. Example: 1
recurrence_revisionintegerrequired- The accepted recurring configuration revision. Example: 1
bird_esim_resumeResume a suspended eSIM so it can use data again.WriteResume eSIM
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_settings_updateUpdate the eSIM settings.WriteUpdate eSIM Settings
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.
Inputs
credential_delivery_enabledboolean- 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_keystring- 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
bird_esim_subscriber_createCreate or returns the subscriber associated with a contact in this workspace.WriteCreate eSIM Subscriber
Create or returns the subscriber associated with a contact in this workspace. Returns an object with id, contact_id, created_at, updated_at.
Inputs
contact_idstringrequired- Existing contact in this workspace; requires Contacts read permission. Example: con_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_suspendSuspend the eSIM's data service, for example during a payment dispute or a suspected-fraud hold.WriteSuspend eSIM
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_updateUpdate the eSIM's display name, tags, or metadata.WriteUpdate eSIM
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.
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
display_namestring- Free-text label for your own reference. Null clears it. Example: Jane Doe
idempotency_keystring- 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
metadataobject- Replaces the eSIM's metadata. Maximum 2 KB serialized. Example: {"key": "value"}
tagsarray- Replaces the eSIM's tags. Example: [{"name": "category", "value": "welcome"}]
bird_lookup_email_batch_createCreate a batch of email address lookups.WriteCreate Batch of Email Address Lookups
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.
Inputs
emailsarrayrequired- 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_keystring- 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
bird_lookup_email_createReturn a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available.WriteCreate Email Address Lookup
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.
Inputs
emailstringrequired- 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_keystring- 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
bird_lookup_email_getLook up an email address given in the URL for deliverability.WriteGet Email Address Lookup by URL
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.
- Idempotent
Inputs
addressstringrequired- 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
bird_lookup_phone_number_createReturn the number's serving and issuing networks, porting state, country, and line type.WriteCreate Phone Number Lookup
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.
Inputs
phone_numberstringrequired- 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_keystring- 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
typearray- 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"]
bird_lookup_phone_number_getLook up a phone number given in the URL: serving and issuing network, porting state, country and line type, plus optional extra blocks.WriteGet Phone Number Lookup by URL
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.
- Idempotent
Inputs
numberstringrequired- 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
typearray- 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"]
bird_mailbox_createCreate a mailbox.WriteCreate Mailbox
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.
Inputs
default_reply_tostring- Default `Reply-To` address stamped on mail sent from this mailbox. Example: jane@example.com
display_namestring- Name shown to your team in the dashboard and tools. Defaults to `name` when omitted. Example: Acme Concierge
domainstring- 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_keystring- 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_partstring- 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
metadataobject- Your own key/value data to attach to the mailbox. Up to 2 KB. Keys starting with `__bird` are reserved. Example: {"key": "value"}
namestring- 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_policystring- 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: openone of
openreplies_onlyallowlistdrop retention_tierstring- 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: 30done of
30d90d1y
bird_mailbox_forwarding_address_createCreate a mailbox forwarding address.WriteCreate Mailbox Forwarding Address
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
idempotency_keystring- 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
bird_mailbox_message_sendSend a new email from an agent mailbox, starting a new thread (or scheduling it for later).WriteCreate Message from a Mailbox
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
subjectstringrequired- Message subject line. Example: Hello from Bird
toarrayrequired- 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>"]
attachmentsarray- 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"}]
bccarray- 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_replyboolean- 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
categorystring- 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: transactionalone of
marketingtransactional ccarray- 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>"]
htmlstring- HTML body. At least one of html or text must be provided. Example: <p>Hello from Bird</p>
idempotency_keystring- 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
metadataobject- Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized. Example: {"key": "value"}
reply_toarray- 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_atstring- 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
tagsarray- Structured `{name, value}` labels for filtering and analytics on the sent-message log. Cap: 20 tags per send. Example: [{"name": "category", "value": "welcome"}]
textstring- Plain-text body. At least one of html or text must be provided. Example: Hello from Bird
bird_mailbox_receive_rule_createAdd an allow or block rule to the mailbox.WriteCreate Email Receive Rule
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.
Inputs
actionstringrequired- 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: allowone of
allowblock entrystringrequired- The sender address (`alice@example.com`) or domain (`example.com`) to match. Domains also match their subdomains. Stored lowercase.
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
idempotency_keystring- 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
notestring- Your own note about why the rule exists. Example: example
bird_mailbox_restoreRestore receiving and access to unexpired messages.WriteRestore Deleted Mailbox
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
idempotency_keystring- 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
bird_mailbox_resumeResume a mailbox that was suspended because the organization dropped below the plan needed to keep it active.WriteResume Suspended Mailbox
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
idempotency_keystring- 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
bird_mailbox_scheduled_message_cancelCancel a scheduled send before the scheduler claims dispatch.WriteCancel Scheduled Mailbox Send
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace that owns the scheduled send. Example: concierge@inbox.ai
scheduled_message_idstringrequired- Scheduled send identifier from scheduled_message_id in the acceptance response. Example: msm_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_mailbox_updateUpdate a mailbox.WriteUpdate Mailbox
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.
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
confirmboolean- 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_tostring- Default `Reply-To` address stamped on mail sent from this mailbox. `null` clears it. Example: jane@example.com
display_namestring- Name shown to your team in the dashboard and tools. `null` clears the override and uses `name`. Example: Jane Doe
idempotency_keystring- 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
metadataobject- Replaces the mailbox's key/value data. Up to 2 KB. Keys starting with `__bird` are reserved. Example: {"key": "value"}
namestring- 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_policystring- 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: openone of
openreplies_onlyallowlistdrop retention_tierstring- 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: 30done of
30d90d1y
bird_number_updateUpdate the name and reference for a number allocated to your workspace.WriteUpdate Allocated Number
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.
Inputs
number_idstringrequired- Identifier returned by the allocated-number list. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
namestring- 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
referencestring- 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
bird_numbers_order_createCreate a number order.WriteCreate Number Order
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.
Inputs
numberstringrequired- The number to acquire, in E.164 format, as returned by `GET /v1/numbers/available`. Example: +18005550100
complianceobject- 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_keystring- 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
referencestring- 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
bird_preference_createRecord one statement, a grant or an opt-out, for a handle on one channel.WriteRecord Preference
Record one statement, a grant or an opt-out, for a handle on one channel. Returns an object with applied, transition_id, preference.
Inputs
channelstringrequired- 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
handlestringrequired- 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
statusstringrequired- 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: revokedone of
grantedrevoked consented_atstring- 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
coveragestring- 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_transactionalone of
allnon_transactional idempotency_keystring- 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_scopestring- 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
sourcestring- 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
bird_realtime_app_createCreate a Realtime app.WriteCreate Realtime App
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.
Inputs
namestringrequired- A label for the app, shown wherever it is listed. Example: chat-production
regionstringrequired- 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: us1one of
us1eu1 authorized_connectionsboolean- Require every connection to be authorized. Example: false
client_eventsboolean- Allow clients to trigger events directly (client events). Example: false
connection_count_eventsboolean- 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_countingboolean- Count the connections subscribed to each channel and expose the count on channel queries. Example: false
idempotency_keystring- 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_eventsboolean- 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
bird_realtime_app_key_createAdd a new key to the app and returns it with its secret.WriteCreate Realtime App Key
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.
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_realtime_app_updateUpdate a Realtime app's name and configuration flags.WriteUpdate Realtime App
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.
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
authorized_connectionsboolean- Require every connection to be authorized. Example: false
client_eventsboolean- Allow clients to trigger events directly (client events). Example: false
connection_count_eventsboolean- 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_countingboolean- Count the connections subscribed to each channel and expose the count on channel queries. Example: false
idempotency_keystring- 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
namestring- A label for the app, shown wherever it is listed. Example: chat-production
watchlist_eventsboolean- 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
bird_sms_keyword_rule_createCreate a workspace keyword rule.WriteCreate SMS Keyword Rule
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.
Inputs
operationstringrequired- 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_managedboolean- 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
countrystring- 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_keystring- 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
keywordsarray- 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"]
languagestring- 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
numberstring- 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
replystring- 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.
bird_sms_keyword_rule_updateChange the reply or the added keywords of a rule you created.WriteUpdate SMS Keyword Rule
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.
Inputs
idstringrequired- ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg
confirmed_self_managedboolean- 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_keystring- 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
keywordsarray- 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"]
replystring- 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.
bird_sms_message_sendSend 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).WriteCreate SMS Message
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.
Inputs
tostringrequired- 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_idstring- Preview feature: audience-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
binaryobject- 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_idstring- Preview feature: broadcast correlation. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
campaign_idstring- Preview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
categorystring- 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: transactionalone of
transactionalmarketingauthenticationservice contact_idstring- Preview feature: contact-targeted sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
cost_centerstring- 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
fromstring- 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_keystring- 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_urlsarray- Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: ["https://example.com/hooks/bird"]
messaging_profile_idstring- 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
metadataobject- 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"}
optionsobject- 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}
personalizationobject- Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: {"key": "value"}
referencestring- 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_atstring- Preview feature: send-later scheduling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: 2026-01-15T09:30:00Z
tagsarray- 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"}]
templateobject- 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"}
textstring- 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_codestring- 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_idstring- Preview feature: topic-gated sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`. Example: id_01jbx7k3m9p2q5r8s4t6v0w1yz
validity_periodinteger- 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
bird_sms_messages_batch_sendSend a batch of independent SMS messages in one request, each with its own recipient and content or template.WriteCreate Batch of SMS Messages
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.
Inputs
messagesarrayrequired- 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_keystring- 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
bird_sms_messaging_profile_createCreate a messaging profile for one program in your workspace.WriteCreate SMS Messaging Profile
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.
Inputs
namestringrequired- A label for the profile. Names are not unique, so two profiles can share one. Example: device-activation
callback_eventsarray- 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_centerstring- A label for assigning the cost of this profile's messages. A send that omits `cost_center` uses it. Example: CC001234
default_categorystring- 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: authenticationone of
transactionalmarketingauthenticationservice idempotency_keystring- 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
inboundobject- 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"}
optionsobject- Sending options for messages that do not set their own. Booleans default to `false`. Example: {"smart_encoding": false, "ignore_suppression": false}
sendersarray- 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_periodinteger- How many seconds a message stays valid before it expires undelivered. A send that omits `validity_period` uses it. Example: 3600
bird_sms_messaging_profile_updateChange a messaging profile.WriteUpdate SMS Messaging Profile
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.
Inputs
profile_idstringrequired- ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg
callback_eventsarray- 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_centerstring- 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_categorystring- 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: authenticationone of
transactionalmarketingauthenticationservice idempotency_keystring- 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
inboundobject- Changes how the profile receives replies. Omitted properties keep their value. Example: {"numbers": [{"number": "34001"}], "callback_url": "https://receipts.example.com/bird/sms/inbound"}
namestring- A new label for the profile. Names are not unique, so two profiles can share one. Example: device-activation
optionsobject- Changes the sending options for messages that do not set their own. Omitted properties keep their value. Example: {"smart_encoding": false, "ignore_suppression": false}
sendersarray- 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_periodinteger- 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
bird_sms_sender_createCreate an SMS sender.WriteCreate SMS Sender
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.
Inputs
senderstringrequired- 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
typestringrequired- 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: alphaone of
alpha idempotency_keystring- 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
bird_sms_sender_registration_createCreate a sender registration for a country.WriteCreate SMS Sender Registration for a Country
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.
Inputs
country_codestringrequired- ISO 3166-1 alpha-2 country code. Example: US
sender_idstringrequired- ID of the SMS sender (`snd_` prefix), as returned when the sender was created. Example: snd_01krdgeqcxet5s7t44vh8rt9mg
categorystring- Message category to register the sender for. Omit to register the sender for all categories. Example: transactionalone of
transactionalmarketingauthenticationservice idempotency_keystring- 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
bird_sms_suppression_createStop a sender's messages to a subscriber, with reason `manual`, blocking every category including transactional.WriteCreate SMS Suppression
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.
Inputs
destinationstringrequired- The subscriber to stop messaging, in E.164 format. Example: +15550001234
originatorstringrequired- 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_keystring- 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
bird_verification_checkCheck a one-time passcode a user entered against an active verification.WriteCreate Verification Passcode Check
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.
Inputs
codestringrequired- 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
toobjectrequired- 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_keystring- 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
bird_verification_next_channel_sendSend a fresh passcode for an active verification on its next configured channel, for example voice after SMS.WriteCreate Next Verification Channel Attempt
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.
Inputs
toobjectrequired- 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_keystring- 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
bird_verification_sendStart 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.WriteCreate Verification
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.
Inputs
toobjectrequired- 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_keystring- 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
metadataobject- Optional key/value pairs to attach to the verification, for example a correlation id. Returned on the verification.
optionsobject- 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"]}
bird_voice_call_createPlace an outbound voice call from one of your numbers to a phone number or SIP endpoint, running a voice sequence or connecting the parties.WriteCreate Voice Call
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.
Inputs
fromstringrequired- Calling number that this workspace is permitted to present. Example: +12025550100
sequenceobjectrequired- 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": {}}
tostringrequired- Recipient number in canonical E.164 form. Example: +12025550101
idempotency_keystring- 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_secondsinteger- Maximum ringing time for the original dialing attempt, shared across routing candidates. Example: 30
bird_voice_destinations_updateUpdate enabled Voice destination countries.WriteUpdate Enabled Voice Destination Countries
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.
Inputs
destinationsarrayrequired- 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_keystring- 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
bird_voice_number_updateChange what you have said about this number: the label you gave it, and what happens when a call arrives for it.WriteUpdate Voice Number
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.
Inputs
number_idstringrequired- ID of the voice number to retrieve or update, as returned by the voice number list. Example: vnu_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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_configurationobject- 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"}}
namestring- Your own label for this number. Send null to remove the one it has. Omit the field to leave it alone. Example: Support line
bird_voice_ring_group_createCreate a ring group with no members.WriteCreate Voice Ring Group
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.
Inputs
namestringrequired- The ring group's name. Example: Support
idempotency_keystring- 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
bird_voice_ring_group_member_createAdd a workspace user to the ring group.WriteAdd Voice Member to a Ring Group
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.
Inputs
ring_group_idstringrequired- ID of the ring group whose members to list or add to. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
user_idstringrequired- 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_keystring- 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
bird_voice_ring_group_updateUpdate a ring group.WriteUpdate Voice Ring Group
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.
Inputs
namestringrequired- The ring group's new name. Example: Tier 2 support
ring_group_idstringrequired- ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_session_credential_createIssue a workspace-scoped SIP digest credential valid for five minutes.WriteCreate Voice SIP Session Credential
Issue a workspace-scoped SIP digest credential valid for five minutes. Returns an object with username, password, realm, expires_at, handshake_token.
Inputs
idempotency_keystring- Does not deduplicate this operation. Every successful attempt creates a fresh credential. Example: 3f1c2b9e-6a4d-4e1b-9c2a-7d8e5f4a1b2c
bird_voice_settings_updateChange your workspace's voice settings.WriteUpdate Voice Settings
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.
Inputs
daily_spend_limitobject- 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_keystring- 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_configurationobject- 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"}}
bird_voice_trunk_createCreate a SIP trunk.WriteCreate Voice SIP Trunk
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.
Inputs
namestringrequired- A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain. Example: Production PBX trunk
digest_algorithmsarray- 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_keystring- 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_enabledboolean- 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
mediaobject- How the new trunk carries call audio. An omitted member takes its default. Example: {"encryption": "preferred"}
media_bypassboolean- 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_enabledboolean- 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_enabledboolean- 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
bird_voice_trunk_gateway_createAdd a gateway address for forwarding inbound calls to this trunk.WriteCreate Voice Gateway on a SIP Trunk
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.
Inputs
priorityintegerrequired- 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_uristringrequired- 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_idstringrequired- ID of the SIP trunk whose gateways to list or create. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
destination_formatstring- 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_keystring- 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_formatstring- 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}
bird_voice_trunk_gateway_updateUpdate the gateway's `sip_uri`, its `priority`, either number format, or any combination.WriteUpdate Voice SIP Trunk Gateway
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.
Inputs
gateway_idstringrequired- ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
trunk_idstringrequired- ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
destination_formatstring- 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_keystring- 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_formatstring- 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}
priorityinteger- 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_uristring- 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
bird_voice_trunk_updateUpdate a SIP trunk's `name`, access control (`ip_acls`, `allowed_api_key_ids`), and Digest algorithm offer (`digest_algorithms`).WriteUpdate Voice SIP Trunk
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.
Inputs
trunk_idstringrequired- ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
allowed_api_key_idsarray- 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_algorithmsarray- 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_keystring- 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_enabledboolean- 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_aclsarray- 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"}]
mediaobject- A change to how the trunk encrypts call audio. Example: {"encryption": "preferred"}
media_bypassboolean- 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
namestring- A human-readable label for this SIP trunk. Mutable, and distinct from the generated wire domain. Example: Production PBX trunk
outbound_enabledboolean- 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_enabledboolean- 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
bird_voice_verified_number_createCreate a verified number.WriteCreate Voice Verified Number
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.
Inputs
phone_numberstringrequired- 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_keystring- 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
namestring- 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
bird_voice_verified_number_updateSet the verified number's label.WriteUpdate Voice Verified Number
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.
Inputs
namestringrequired- 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_idstringrequired- ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_verified_number_verifyVerify number ownership.WriteVerify Voice Number Ownership
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.
Inputs
verified_number_idstringrequired- ID of the verified number registration whose ownership challenge to complete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
codestring- 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_keystring- 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
bird_webhook_callback_replayReplay failed callback deliveries.WriteReplay Failed Callback Deliveries
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).
Inputs
idempotency_keystring- 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
sincestring- 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
untilstring- 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
bird_webhook_callback_signing_secret_rotateRotate callback signing secret.WriteRotate Callback Signing Secret
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.
Inputs
idempotency_keystring- 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
bird_webhook_createCreate a webhook endpoint.WriteCreate Webhook Endpoint
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.
Inputs
eventsarrayrequired- 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"]
descriptionstring- Human-readable label for this endpoint, up to 256 characters. Example: Production webhook endpoint
destinationobject- How each delivery is built. Omit to post the signed event to `url` unchanged, the same as `{"type": "webhook"}`. Example: {"type": "webhook"}
filterobject- Limit delivery to one mailbox and only email_mailbox events. Omit to include all resources. Example: {"mailbox_id": "mbx_01kr97a6rje4wbe5z40wxdfcy9"}
idempotency_keystring- 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
urlstring- 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
bird_webhook_replayReplay failed deliveries.WriteReplay Failed Deliveries
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
sincestring- 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
untilstring- 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
bird_webhook_secret_rotateRotate webhook signing secret.WriteRotate Webhook Signing Secret
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_webhook_testSend a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency.WriteTest Webhook with a Sample Event
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
event_typestring- 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_keystring- 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
bird_webhook_updateUpdate the webhook endpoint.WriteUpdate Webhook Endpoint
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.
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
descriptionstring- Human-readable label for this endpoint, up to 256 characters. Example: Updated webhook endpoint
destinationobject- 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"}}
eventsarray- 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"]
filterobject- 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_keystring- 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
statusstring- `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: activeone of
activepaused urlstring- 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
bird_whatsapp_agent_notification_createSend an agent a notification.WriteSend WhatsApp Agent a Notification
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.
Inputs
descriptionstringrequired- What happened, in a sentence the agent can tell the contact. Example: Order 88213 left the warehouse and arrives on Thursday.
fromstringrequired- 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
namestringrequired- 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
payloadstringrequired- 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"}
tostringrequired- 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_keystring- 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
bird_whatsapp_conversation_updateUpdate assignment, inbox status, labels, or shared workspace read state.WriteUpdate WhatsApp Conversation
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.
Inputs
conversation_idstringrequired- Conversation identifier. Starts with `wacv_`. Example: wacv_01krdgeqcxet5s7t44vh8rt9mg
assigned_tostring- 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_keystring- 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_statusstring- 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: openone of
openresolved labelsarray- 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"]
readstring- 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
bird_whatsapp_group_createCreate a WhatsApp group administered by one of your business numbers.WriteCreate WhatsApp Group
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.
Inputs
subjectstringrequired- 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_idstringrequired- 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
descriptionstring- The group's description, shown alongside the subject. Example: Jim would like to learn about new car purchase options for current year models.
idempotency_keystring- 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_modestring- 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_approveone of
auto_approveapproval_required
bird_whatsapp_group_invite_link_rotateIssue a new invite link for the group.WriteRotate WhatsApp Group's Invite Link
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.
Inputs
group_idstringrequired- ID of the group whose invite link is being replaced. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_group_join_requests_approveApprove the named join requests, up to 50 in one call.WriteApprove WhatsApp Group Join Requests
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.
Inputs
group_idstringrequired- ID of the group whose join requests are being decided. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
join_request_idsarrayrequired- 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_keystring- 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
bird_whatsapp_group_join_requests_rejectReject the named join requests, up to 50 in one call.WriteReject WhatsApp Group Join Requests
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.
Inputs
group_idstringrequired- ID of the group whose join requests are being decided. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
join_request_idsarrayrequired- 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_keystring- 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
bird_whatsapp_group_pinned_message_createPin 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.WritePin Message in a WhatsApp Group
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.
Inputs
group_idstringrequired- ID of the group to pin a message in. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
message_idstringrequired- 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_daysinteger- How many days the message stays pinned before WhatsApp unpins it, from 1 to 30. Example: 7
idempotency_keystring- 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
bird_whatsapp_group_updateChange what participants see at the top of the group: its subject, its description, and its picture.WriteUpdate WhatsApp Group
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.
Inputs
group_idstringrequired- ID of the group to change. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
descriptionstring- 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_keystring- 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_urlstring- 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
subjectstring- A new name for the group. Participants see the change in the group's chat. Example: Watch Enthusiasts
bird_whatsapp_keyword_rule_createCreate a keyword rule.WriteCreate WhatsApp Keyword Rule
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.
Inputs
operationstringrequired- 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_outone of
opt_inopt_out countrystring- 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_keystring- 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
keywordsarray- 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"]
replystring- 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.
wabastring- 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
bird_whatsapp_keyword_rule_updateChange the reply or the added keywords of a rule you created.WriteUpdate WhatsApp Keyword Rule
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.
Inputs
idstringrequired- 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_keystring- 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
keywordsarray- 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"]
replystring- 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.
bird_whatsapp_message_reaction_setPlace an emoji reaction on a message this workspace received, the same way tapping and holding a message in WhatsApp does.WriteReact to a WhatsApp Message
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.
- Idempotent
Inputs
emojistringrequired- 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_idstringrequired- 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_keystring- 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
bird_whatsapp_message_read_receipt_sendMark an inbound WhatsApp message as read, showing the contact the blue ticks.WriteMark WhatsApp Message as Read
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.
Inputs
message_idstringrequired- ID of the inbound message to acknowledge. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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_indicatorboolean- 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
bird_whatsapp_message_sendSend 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.WriteSend WhatsApp Message
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.
Inputs
tostringrequired- 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
audioobject- Free-form audio; requires an open customer service window. Example: {"url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true}
contact_cardsarray- 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"}]}]
documentobject- 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"}
fromstring- 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_keystring- 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
imageobject- 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_idstring- Message to quote, from this conversation (`to` and `from`) within the last 15 days. Example: wam_01kya19eknftrs2s6p82asmvnh
interactiveobject- 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"}}]}
locationobject- 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"}
metadataobject- Per-message JSON context, such as internal IDs, returned on reads. Maximum 2 KB serialized. Use `tags` for filterable labels. Example: {"key": "value"}
referencestring- 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
stickerobject- Free-form sticker; requires an open customer service window. Example: {"url": "https://cdn.example.com/stickers/thumbs-up.webp"}
tagsarray- 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"}]
templateobject- 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"}}
textobject- Free-form text; requires an open customer service window. Example: {"body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true}
videoobject- Free-form video; requires an open customer service window. Example: {"url": "https://cdn.example.com/unboxing.mp4", "caption": "How to set it up"}
bird_whatsapp_suppression_createManually adds a WhatsApp address to the suppression list with reason `manual`.WriteCreate WhatsApp Suppression
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.
Inputs
addressstringrequired- 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_keystring- 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
wabastring- 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
bird_whatsapp_template_createCreate a WhatsApp message template.WriteCreate WhatsApp Message Template
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.
Inputs
categorystringrequired- 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: utilityone of
authenticationutilitymarketing default_languagestringrequired- 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
slugstringrequired- 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
wabastringrequired- 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
descriptionstring- What the template is for. Free text. Example: Sent when a customer's order ships.
idempotency_keystring- 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_requiredboolean- 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
languagesobject- 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"}]}]}}
namestring- 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_languagestring- 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: fallbackone of
fallbackfail
bird_whatsapp_template_draft_createOpen the template's draft, seeded from the newest submitted version, or an empty draft if the template has none.WriteCreate WhatsApp Template Draft
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.
Inputs
template_refstringrequired- 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_keystring- 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
bird_whatsapp_template_duplicateDuplicate a message template.WriteDuplicate WhatsApp Message Template
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.
Inputs
template_refstringrequired- 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
wabastringrequired- 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_languagestring- 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_keystring- 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_languagesarray- 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"]
namestring- The copy's display name. Inherited from the source when omitted. Example: sk-test-sample
slugstring- 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
bird_whatsapp_template_language_edits_discardRestore one language of the template's draft to the copy the draft was branched from, discarding the edits made to it since.WriteDiscard WhatsApp Language's Draft Edits Back to Its Submitted Copy
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.
Inputs
languagestringrequired- 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_refstringrequired- 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_idstringrequired- Version ID. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
revisioninteger- 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
bird_whatsapp_template_language_setWrite one language of the template's draft, creating it when absent (`201`) and replacing it when present (`200`).WriteUpsert WhatsApp Language's Content
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.
- Idempotent
Inputs
languagestringrequired- 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_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
componentsarray- 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_keystring- 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_secondsinteger- 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_specobject- 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_bindingsobject- 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"}
revisioninteger- 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
bird_whatsapp_template_updateUpdate a template's metadata.WriteUpdate WhatsApp Message Template
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.
Inputs
template_refstringrequired- 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_languagestring- 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
descriptionstring- What the template is for. Send `null` to clear it. Example: Created by the Scalekit connector
idempotency_keystring- 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_requiredboolean- Whether a send has to name a language. Example: false
namestring- The template's display name. Editable at any time; it is not what a send references. Example: Order update
on_missing_languagestring- 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: fallbackone of
fallbackfail slugstring- 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
bird_whatsapp_template_version_submitSubmit a template version for review.WriteSubmit WhatsApp Template Version for Review
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.
Inputs
template_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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_onlyboolean- 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
bird_amb_business_account_deleteStop new and queued sends while retaining the account, Apple UUID, approval, credentials and history.DestructiveDisconnect Apple Business Account
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.
- Idempotent
Inputs
business_account_idstringrequired- ID of the Apple Messages for Business record to disconnect, as returned by the business list. Example: abz_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_amb_routing_rule_deleteDelete a routing rule.DestructiveDelete Apple Messages for Business Routing Rule
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.
- Idempotent
Inputs
routing_rule_idstringrequired- ID of the routing rule to read, update, or delete. Example: arr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_amb_suppression_deleteEnd an Apple Messages for Business suppression.DestructiveEnd Apple Messages for Business Suppression
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.
- Idempotent
Inputs
suppression_idstringrequired- ID of the suppression episode to retrieve or end. Example: asp_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_deleteRemove an asset from the library.DestructiveRemove Asset from the Media Library
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.
- Idempotent
Inputs
asset_idstringrequired- ID of the asset. Example: ast_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_asset_folder_deleteDelete a folder.DestructiveDelete Folder and Move Its Contents Up
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.
- Idempotent
Inputs
folder_idstringrequired- ID of the asset folder. Example: asf_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_audience_contact_removeRemove a contact's membership in an audience.DestructiveUnassign Contact from an Audience
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.
- Idempotent
Inputs
audience_idstringrequired- ID of the audience to remove the contact from. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
contact_idstringrequired- ID of the contact to remove. Example: con_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_audience_deleteDelete an audience and its memberships.DestructiveDelete Audience
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.
- Idempotent
Inputs
audience_idstringrequired- ID of the audience to delete. Example: adn_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_compliance_attachment_deleteDelete an uploaded registration attachment.DestructiveDelete Registration Attachment
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.
- Idempotent
Inputs
attachment_idstringrequired- Attachment ID. Example: tca_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_compliance_identity_deleteDelete an identity.DestructiveDelete Identity
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.
- Idempotent
Inputs
identity_idstringrequired- Identity ID. Example: cid_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_contact_deleteDelete a contact permanently and removes it from every audience it belongs to.DestructiveDelete Contact
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.
- Idempotent
Inputs
contact_idstringrequired- ID of the contact to delete. Example: con_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_broadcast_deleteDelete a draft broadcast.DestructiveDelete Email Broadcast
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.
- Idempotent
Inputs
broadcast_idstringrequired- Broadcast identifier. Starts with `eb_`. Example: eb_01jbx7k3m9p2q5r8s4t6v0w1yz
idempotency_keystring- 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
bird_email_competitive_watchlist_brand_deleteRemove a competitor brand from the watchlist.DestructiveRemove Email Competitor Brand from the Watchlist
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).
- Idempotent
Inputs
watchlist_brand_idstringrequired- The watchlist entry to act on. Example: cwb_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_domain_deleteRemove the domain and revokes its sender authorization.DestructiveDelete Sending Domain
Remove the domain and revokes its sender authorization. Returns an empty response on success (HTTP 204). Needs domain_id from bird_email_domains_list.
- Idempotent
Inputs
domain_idstringrequired- ID of the domain to delete. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_domain_tracking_releaseRemove the link tracking configuration from this domain and releases the claim on its tracking subdomain, so another organization can configure the same hostname.DestructiveRelease Link Tracking Configuration
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.
Inputs
domain_idstringrequired- ID of the domain to release tracking for. Example: dom_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_inbound_address_deleteDelete an inbound address.DestructiveDelete Email Inbound Address
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.
- Idempotent
Inputs
inbound_address_idstringrequired- Inbound address identifier. Starts with `ina_`. Example: ina_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_inbound_route_deleteDelete an inbound route.DestructiveDelete Email Inbound Route
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.
- Idempotent
Inputs
route_idstringrequired- Inbound route identifier. Starts with `ein_`. Example: ein_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_suppression_deletePermanently deletes the selected suppression record.DestructiveDelete Email Suppression
Permanently deletes the selected suppression record. Returns an empty response on success (HTTP 204). Needs suppression_id from bird_email_suppressions_list.
- Idempotent
Inputs
suppression_idstringrequired- ID of the suppression record, as returned when the suppression was created or listed. Example: sup_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_template_deleteDelete the template from authoring and lists.DestructiveDelete Email Template
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.
- Idempotent
Inputs
template_refstringrequired- 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_keystring- 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
bird_email_template_language_deleteRemove one language from the template's draft, along with its content.DestructiveDelete Email One Language from a Draft
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.
- Idempotent
Inputs
languagestringrequired- The language as a BCP-47 tag. Example: pt-BR
template_refstringrequired- 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_idstringrequired- The version that holds the language. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_template_version_deleteDiscard 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.DestructiveDelete Email Template Draft
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.
- Idempotent
Inputs
template_refstringrequired- 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_idstringrequired- The version to read or reset. Example: emv_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_email_thread_deleteDelete a thread.DestructiveDelete Email Thread
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.
- Idempotent
Inputs
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
permanentboolean- Permanently delete the conversation and its messages immediately instead of moving them to the trash. Example: false
bird_email_thread_message_deleteDelete a message in a thread.DestructiveDelete Email Message in a Thread
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.
- Idempotent
Inputs
message_idstringrequired- Message ID (`rem_` for a received message, `em_` for a sent one). Example: rem_01jbx7k3m9p2q5r8s4t6v0w1yz
thread_idstringrequired- Thread identifier. Starts with `thr_`. Example: thr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
permanentboolean- Permanently delete the message immediately instead of moving it to the trash. Example: false
bird_esim_install_link_deleteRevoke a hosted install link.DestructiveRevoke Hosted Install Link
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.
- Idempotent
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
install_link_idstringrequired- Hosted install link ID. Example: eil_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_esim_package_deleteRemove a data package and frees capacity under the eSIM's `package_limit`.DestructiveRemove Data Package
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.
- Idempotent
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
package_idstringrequired- Data package ID. Example: epk_01krdgeqcxet5s7t44vh8rt9mg
acknowledge_balance_forfeitboolean- 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_keystring- 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
bird_esim_releasePermanently releases an eSIM.DestructiveRelease eSIM
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.
- Idempotent
Inputs
esim_idstringrequired- eSIM ID. Example: esm_01krdgeqcxet5s7t44vh8rt9mg
acknowledge_balance_forfeitboolean- 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_keystring- 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
bird_mailbox_deleteDelete a mailbox.DestructiveDelete Mailbox
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.
- Idempotent
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
idempotency_keystring- 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
bird_mailbox_receive_rule_deleteRemove a receive rule from the mailbox.DestructiveDelete Email Receive Rule
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.
- Idempotent
Inputs
mailbox_idstringrequired- Mailbox ID or email address in this workspace. Example: concierge@inbox.ai
rule_idstringrequired- Receive-rule identifier. Starts with `erl_`. Example: erl_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_number_cancelCancel one of your workspace's dedicated numbers at the end of its current billing period.DestructiveCancel Dedicated Number
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.
- Idempotent
Inputs
number_idstringrequired- Identifier of the number to cancel, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_number_releaseRelease one of your workspace's dedicated numbers now and stops its recurring charge.DestructiveRelease Dedicated Number
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.
Inputs
number_idstringrequired- Identifier of the number to release, as returned in the id field of GET /v1/numbers. Example: nda_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_preference_deleteDelete a preference, returning its key to having no record, as if nothing had ever been stated.DestructiveDelete Preference
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.
- Idempotent
Inputs
preference_idstringrequired- 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_keystring- 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
bird_realtime_app_deletePermanently deletes the app: disconnects all clients and removes its keys and configuration.DestructiveDelete Realtime App
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.
- Idempotent
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_realtime_app_key_revokeRevoke a Realtime app key.DestructiveRevoke Realtime App Key
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.
Inputs
realtime_app_idstringrequired- ID of the Realtime app (`rap_` prefix), as returned when the app was created. Example: rap_01krdgeqcxet5s7t44vh8rt9mg
realtime_app_key_idstringrequired- ID of the Realtime app key (`rak_` prefix), as returned when the key was created. Example: rak_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_sms_keyword_rule_deleteDelete a rule you created.DestructiveDelete SMS Keyword Rule
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.
- Idempotent
Inputs
idstringrequired- ID of the default or workspace keyword rule, as returned by the list operation. Example: skw_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_sms_messaging_profile_deleteDelete a messaging profile and releases its reply numbers and keyword, so another profile can use them and a new profile can reuse the name.DestructiveDelete SMS Messaging Profile
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.
- Idempotent
Inputs
profile_idstringrequired- ID of the messaging profile, as returned when you created or listed profiles. Example: mpr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_sms_suppression_deleteDelete an SMS suppression.DestructiveDelete SMS Suppression
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.
- Idempotent
Inputs
suppression_idstringrequired- ID of the suppression, as returned when it was created or listed. Example: ssu_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_ring_group_deleteDelete the ring group and its member list.DestructiveDelete Voice Ring Group
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.
- Idempotent
Inputs
ring_group_idstringrequired- ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_ring_group_member_deleteRemove the user from the ring group.DestructiveRemove Voice Member from a Ring Group
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.
- Idempotent
Inputs
ring_group_idstringrequired- ID of the ring group. Example: vrg_01krdgeqcxet5s7t44vh8rt9mg
user_idstringrequired- ID of the member to remove. Example: usr_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_trunk_deleteRemove the SIP trunk.DestructiveDelete Voice SIP Trunk
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.
- Idempotent
Inputs
trunk_idstringrequired- ID of the SIP trunk to retrieve, update, or delete. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_trunk_gateway_deleteRemove the gateway.DestructiveDelete Voice SIP Trunk Gateway
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.
- Idempotent
Inputs
gateway_idstringrequired- ID of the inbound gateway to retrieve, update, or delete. Example: vtg_01krdgeqcxet5s7t44vh8rt9mg
trunk_idstringrequired- ID of the SIP trunk that owns the gateway. Example: spt_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_voice_verified_number_deleteRemove the verified number.DestructiveDelete Voice Verified Number
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.
- Idempotent
Inputs
verified_number_idstringrequired- ID of the verified number to retrieve, update, or delete. Example: vvn_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_webhook_deletePermanently removes the webhook endpoint and stops all deliveries to it, including retries of earlier failed deliveries.DestructiveDelete Webhook Endpoint
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.
- Idempotent
Inputs
webhook_idstringrequired- ID of the webhook endpoint (`whk_` prefix), as returned when it was created. Example: whk_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_group_deleteDelete the group at WhatsApp.DestructiveDelete WhatsApp Group
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.
- Idempotent
Inputs
group_idstringrequired- ID of the group to delete. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_group_participant_deleteRemove one person from the group.DestructiveRemove Participant from a WhatsApp Group
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.
- Idempotent
Inputs
group_idstringrequired- ID of the group to remove someone from. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
participant_refstringrequired- 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_keystring- 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
bird_whatsapp_group_pinned_message_deleteUnpin a message in a WhatsApp group.DestructiveUnpin Message in a WhatsApp Group
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.
- Idempotent
Inputs
group_idstringrequired- ID of the group to unpin a message in. Example: wag_01krdgeqcxet5s7t44vh8rt9mg
message_idstringrequired- ID of the message to unpin, as returned in the send response's `id`. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_keyword_rule_deleteDelete a rule you created.DestructiveDelete WhatsApp Keyword Rule
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.
- Idempotent
Inputs
idstringrequired- 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_keystring- 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
bird_whatsapp_message_reaction_deleteRemove your reaction from a WhatsApp message.DestructiveRemove Your Reaction from a WhatsApp Message
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.
- Idempotent
Inputs
message_idstringrequired- ID of the message to take your reaction off, as returned in the `id` field of the message. Example: wam_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_suppression_deleteEnd a WhatsApp suppression.DestructiveEnd WhatsApp Suppression
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.
- Idempotent
Inputs
suppression_idstringrequired- ID of the WhatsApp suppression record to retrieve or end. Example: was_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_template_deleteDelete a template and every language it holds.DestructiveDelete WhatsApp Message Template
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.
- Idempotent
Inputs
template_refstringrequired- 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_keystring- 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
bird_whatsapp_template_language_deleteRemove one language from the template's draft.DestructiveDelete WhatsApp Language from the Draft
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.
- Idempotent
Inputs
languagestringrequired- 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_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
bird_whatsapp_template_version_deleteDelete the draft and leaves the template without an open draft.DestructiveDelete WhatsApp Template's Open Draft
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.
- Idempotent
Inputs
template_refstringrequired- 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_idstringrequired- ID of the template version (`wav_` prefix), as returned by the version list. Example: wav_01krdgeqcxet5s7t44vh8rt9mg
idempotency_keystring- 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
No tools match.