Bird

Add up to 1,000 existing contacts to a static audience by ID. Fails entirely if any contact ID does not exist. To add contacts you have not created yet, use `contacts_batch` with `audience_ids` instead: it matches or creates each contact by email address and assigns it to the audience in one call.

audiences_add_contacts

Assign the workspace's US long codes to a 10DLC campaign so they can send to US recipients once the carriers confirm each number. Either every number in the request is assigned or none is.

sms_10dlc_campaigns_numbers_assign

Cancel a scheduled, accepted, or sending broadcast. This stops every delivery that has not gone out yet. Recipients already dispatched are not recalled. Calling this again on a broadcast already canceling or canceled returns its current state rather than an error. A draft cannot be canceled, because it was never sent. Delete it with `email_broadcasts_delete` instead.

email_broadcasts_cancel

Stops a dedicated number renewing and keeps it allocated until the end of the period already paid for, when it is released. Cannot be undone; read `releases_at` for when it goes. Asking again returns the same schedule. A number with no subscription behind it is released now. Refused while a renewal payment is overdue. To give the number up now, use `numbers_release` instead.

numbers_cancel

Cancel a scheduled email before it sends. Only works while the message's `status` is still `scheduled`. Once it starts sending, or was already canceled, the call returns a conflict error. Canceling does not return consumed scheduled-send quota.

email_cancel

Cancels a draft verification and frees the toll-free number it held, so the number can be put on a new one. Only a draft can be canceled: once a verification has been submitted the carrier is holding it, and it is locked.

sms_tfn_verifications_cancel

Cancel an order waiting for funds. Inspect the returned status: an unfunded order fails with failure_code canceled; an initial recurring order whose payment was recovered continues delivery with future renewal stopped. One-time orders already funded return a conflict.

esim_orders_cancel

Stops future package renewal at the current paid boundary. A period already committed remains payable. The installed profile and separately purchased packages are preserved.

esim_recurring_subscriptions_cancel

Point one website entry on the agent on this WhatsApp number at a new address. WhatsApp reads the new page in place of the old one, so check the entry's `crawl_status` with `whatsapp_agents_websites_get` before expecting answers from it.

whatsapp_agents_websites_update

Check whether WhatsApp will accept a phone number before buying it: take a number from `numbers_available_list`, check it here, and order it with `numbers_orders_create` only if this check answers `available`. It is a write rather than a lookup, so check the number you intend to buy rather than sweeping a list of candidates, and reuse an `Idempotency-Key` to get the stored answer back instead of asking WhatsApp again.

whatsapp_numbers_precheck

Check blocklist standing for the sending infrastructure of a verified domain owned by the workspace. This is a current lookup and accepts no date window. Inspect each target status and checked_at; a null active_count means the lookup service supplied no count. Zero and an empty target list do not establish complete coverage. API-key calls require Insights preview access for your organization.

email_inbox_insights_blocklists

Check whether one email address is suppressed before sending to it. Returns suppressed=true with the matching suppression records (id, reason) when it is.

email_suppressions_check

Register a 10DLC brand with the business identity details US carriers require. The brand starts pending while the registry reviews it; only once it is approved can you register a campaign under it. If the registry rejects it, correct the details and resubmit with `sms_10dlc_brands_submissions_create`.

sms_10dlc_brands_create

Order external vetting for a 10DLC brand: `standard`, `enhanced`, or `political` for any approved brand, or `auth_plus` for a `public_profit` brand with a `business_contact_email` set (required before its campaigns can run, and never ordered automatically). Charges a one-off fee that varies by class; returns 402 when the wallet cannot cover it. Use `sms_10dlc_brands_vettings_list` to check status.

sms_10dlc_brands_vettings_create

Register a 10DLC campaign under an approved brand. A brand registered as a publicly-traded company must hold active Auth+ vetting first. The campaign starts pending while the registry reviews it. Assign the workspace's long codes to it with `sms_10dlc_campaigns_numbers_assign` while it is still pending; they can only start sending once the campaign is approved and the carriers confirm each number. If the registry rejects the campaign, correct the details and resubmit with `sms_10dlc_campaigns_submissions_create`.

sms_10dlc_campaigns_create

Analyze a DMARC aggregate report supplied as `report_xml`. Returns totals, per-source-IP SPF and DKIM alignment results, and actionable findings. The analysis is offline and sends no message.

email_tools_analyze_dmarc_report

Provision a Realtime app and its first key. `region` is immutable once set and must be one of `realtime_regions_list`. The response is the only place the key's secret ever appears, and no operation can read it back: recovering from a lost secret means creating another key. An app is what the publish and channel-inspection operations address.

realtime_apps_create

Add a key to an app and read its secret. Takes no body. This response is the only place the secret appears, so a caller that does not capture it has to create another key. The app's existing keys keep working, which is what makes this the first step of a rotation: add, roll out, then revoke the old key.

realtime_apps_keys_create

Mint a short-lived SIP digest credential a calling client authenticates with. The password is returned once and cannot be retrieved again.

voice_session_credentials_create

Create a new SIP trunk for the workspace. Returns the Bird-assigned domain to configure in the customer's PBX or SIP client.

voice_trunks_create

Create a WhatsApp group administered by one of your business numbers. The number must hold Official Business Account status, which `whatsapp_numbers_list` reports as is_official_business_account. The response is the accepted group with status pending; WhatsApp confirms it moments later, which is when the group gains its invite link and becomes messageable. Re-read the group until its status is active.

whatsapp_groups_create

Replace the reply Bird sends for opt-out or opt-in, or add keywords of your own. Your rule takes precedence over Bird's at the same grain and keeps Bird's keywords unless you add more. A keyword Bird has bound to one operation cannot be reused for the other.

whatsapp_keyword_rules_create

Connect a number the workspace already holds to WhatsApp. Take the number's id from `numbers_list`, where a connectable number is a dedicated one (`nda_` prefix) that can receive text messages; WhatsApp proves ownership for you, so no verification code is asked for. The number comes back `preparing` and takes a couple of minutes. Read it back with `whatsapp_numbers_get` until it reports `awaiting_signup`, at which point it carries `finish_setup_url` (a browser flow behind an OAuth screen that a person must complete, and that no operation here can substitute for). `failed` means it could not be prepared and `error` says why.

whatsapp_numbers_create

Record a WhatsApp address on the workspace suppression list.

whatsapp_suppressions_add

Send up to 100 independent SMS messages in one call. Each item is a full send (free-text or template) with its own ID, status, and cost; all items are validated before any are queued, so one invalid item rejects the batch.

sms_send_batch

Assess up to 1,000 email addresses in one request. Results preserve input order and duplicates; malformed addresses receive individual assessments. Each answered entry is billed. Use a separate idempotency key per batch and reuse it for retries. Requests are limited to 128 KiB; responses over 256 KiB cannot be replayed and a retry can incur another charge.

lookup_email_batch

Send up to 100 emails in one call. All items are validated before any are queued, so one invalid item rejects the whole batch instead of a partial success. The response has one entry per message, in submission order, each with its own `id`. An item can set `scheduled_at`, and one batch can mix scheduled and immediate messages. Attachments are supported on individual messages, subject to both the per-message generated-size cap and the hard batch request-body cap.

email_send_batch

Create a broadcast that sends one piece of template content to a stored audience. Leave `send` as `false` (the default) to save an editable draft. Update it with `email_broadcasts_update` and send it later with `email_broadcasts_send`. Set `send` to `true`, optionally with `scheduled_at`, to send it in this call. A send needs a verified `from` address, an `audience_id`, and a `template`.

email_broadcasts_create

Proposes a real outbound call for browser confirmation. Requires voice_management:write and voice:write; normal calling charges apply. Set `sequence.id` to run a saved sequence's active publication, or `sequence.definition` to run a complete definition once without saving it; never both. An inline definition must pass publication checks; an invalid one is refused with a 422 naming its first problem under `/sequence/definition` only when the person runs the call. An inline run executes at most 16 commands. Supply a stable idempotency_key and reuse it with identical input for retries. The confirmation expires after 90 minutes. After the person places the call, a 202 response reserves call, leg and run IDs; it does not prove connection. Use `voice_legs_get` with `initial_leg_id` to inspect the leg outcome, and inspect the sequence run in the dashboard. Never use a new key merely because an earlier result is missing.

voice_calls_create

Create a contact identified by an email address, an E.164 phone number, or both. Fails with a conflict if the email, phone_number, or external_id is already used by another contact. For bulk import or create-or-update semantics use `contacts_batch`.

contacts_create

Define a custom contact property (key + value type) that becomes available in contact data and as a broadcast template variable. The key and type cannot change after creation; a workspace holds at most 200 properties, archived included.

contact_properties_create

Purchase one or more dedicated IPs into an IP pool. The first purchase creates a dedicated pool automatically; later purchases require `ip_pool_id`. This paid organization-level action can require a wallet top-up.

email_dedicated_ips_create

Add an address for inbound call delivery. Enable inbound calling on the trunk first; a trunk supports up to 20 gateways.

voice_trunks_gateways_create

Create a private hosted installation link for one eSIM. The recipient needs no Bird login. Links expire after seven days; earlier links remain valid until expiry or revocation. Requires esim_credentials permission. Returns 501 when new hosted links are unavailable.

esim_install_links_create

Create a mailbox: a durable agent identity that owns an email address, groups mail into conversations, and remembers conversations for its retention tier.

email_mailboxes_create

Send a new email from this mailbox's own address, starting a new conversation. Replies to it thread back automatically. To reply within an existing conversation, use the reply endpoint on one of its messages.

email_mailboxes_compose

Creates a WhatsApp template. Supply `languages` to seed its first draft in the same call, or omit it to create the template alone and add content through `whatsapp_templates_versions_create` and `whatsapp_templates_versions_languages_set`. Nothing here reaches WhatsApp: what comes back is a `draft`, and a draft cannot be sent. Submitting it for review is a separate, explicit step. The slug can change until that first submission. The declared category is fixed at creation, but Meta applies its own category per language and may move one, and the price follows that. Read the language for what a send actually costs.

whatsapp_templates_create

Resubmit a rejected 10DLC brand with corrected details for registry review. The new details replace what the previous attempt submitted, and the brand returns to the pending state.

sms_10dlc_brands_submissions_create

Resubmit a rejected 10DLC campaign with corrected details for registry review. The new details replace what the previous attempt submitted, and the campaign returns to the pending state. A brand registered as a publicly-traded company must hold active Auth+ vetting.

sms_10dlc_campaigns_submissions_create

Buys a number and starts its monthly charge. Most orders settle inline; one waiting on a carrier comes back pending and is followed with `numbers_orders_get`. A setup fee already taken is not refunded if the order then fails.

numbers_orders_create