@messagebird/sdk 0.26.0 → 0.28.0

package/dist/index.d.mts

@@ -332,31 +332,31 @@ type VoiceMediaQuality = {
  *
  * Most of them you can fix yourself:
  *
- * - `source_not_allowed`: the call came from an IP address that is not in the
+ * - `source_not_allowed`: The call came from an IP address that is not in the
  * trunk's allowed-address list. Add the address your PBX sends from.
- * - `caller_id_not_verified`: the number in the `From` header is not a verified
+ * - `caller_id_not_verified`: The number in the `From` header is not a verified
  * caller ID for this workspace. Verify it, or present a number you have
  * already verified.
- * - `destination_not_enabled`: you have not turned on calling to this
+ * - `destination_not_enabled`: You have not turned on calling to this
  * destination country. Enable it in your voice destination settings.
- * - `insufficient_balance`: your wallet did not cover the call. Top up, or turn
+ * - `insufficient_balance`: Your wallet did not cover the call. Top up, or turn
  * on automatic top-ups.
- * - `daily_spend_exceeded`: the call would have passed your organization's daily
+ * - `daily_spend_exceeded`: The call would have passed your organization's daily
  * voice spend limit. The limit resets at the start of the next UTC day.
- * - `concurrent_calls_exceeded`: you already have as many calls in progress as
+ * - `concurrent_calls_exceeded`: You already have as many calls in progress as
  * your account allows. Wait for one to end, or ask support to raise the limit.
- * - `calls_per_second_exceeded`: you placed calls faster than your account
+ * - `calls_per_second_exceeded`: You placed calls faster than your account
  * allows. Slow the rate you dial at, then retry.
  *
  * The rest need Bird to act, so contact support and quote the call `id`:
  *
- * - `routing_not_configured`: no dial plan is attached to this trunk yet.
+ * - `routing_not_configured`: No dial plan is attached to this trunk yet.
  * Expected on a trunk that was just created.
- * - `no_route_found`: a dial plan is attached, but no rule in it covers this
+ * - `no_route_found`: A dial plan is attached, but no rule in it covers this
  * destination.
- * - `destination_blocked`: the destination is blocked by Bird's routing
+ * - `destination_blocked`: The destination is blocked by our routing
  * configuration.
- * - `call_not_permitted`: the call could not be priced for your account.
+ * - `call_not_permitted`: The call could not be priced for your account.
  *
  */
 type VoiceCallRejectionReason = "source_not_allowed" | "caller_id_not_verified" | "routing_not_configured" | "no_route_found" | "destination_blocked" | "destination_not_enabled" | "insufficient_balance" | "daily_spend_exceeded" | "concurrent_calls_exceeded" | "calls_per_second_exceeded" | "call_not_permitted";
@@ -788,14 +788,14 @@ type EventVerifyVerificationVerifiedData = EventVerifyBase & {
  */
 type VerificationChannel$1 = "email" | "sms" | "whatsapp" | (string & {});
 /**
- * The recipient to verify. Provide an `email_address`, 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.
+ * 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.
  *
  */
 type VerificationTo = {
   /**
    * The recipient's email address. Case does not matter; the address is lowercased before use.
    */
-  email_address?: string;
+  email?: string;
   /**
    * The recipient's phone number in E.164 format, with the leading `+` and country code (for example `+15551234567`). A number in any other format is rejected as an invalid recipient (`422`).
    */
@@ -1693,7 +1693,17 @@ type EventEmailScheduled = {
 };
 /**
  * Why an email was rejected before delivery.
- * `recipient_suppressed` means the recipient is on the workspace suppression list, so Bird did not attempt delivery. `transmission_failed` means the message could not be transmitted for delivery. `generation_failure` means the message could not be built for delivery (a template or content issue). `policy_rejection` means the message was refused by sending policy. `domain_unverified` means the sending domain was not verified. `quota_exceeded` means the organization's send quota was reached. `recipient_not_allowed` means a recipient was not permitted for this send (for shared onboarding-domain sends, recipients must be verified workspace members).
+ *
+ * - `recipient_suppressed`: The recipient is on the workspace suppression list, so
+ * delivery was never attempted.
+ * - `transmission_failed`: The message could not be transmitted for delivery.
+ * - `generation_failure`: The message could not be built for delivery (template or
+ * content issue).
+ * - `policy_rejection`: The message was refused by sending policy.
+ * - `domain_unverified`: The sending domain was not verified.
+ * - `quota_exceeded`: The organization's send quota was reached.
+ * - `recipient_not_allowed`: A recipient was not permitted for this send (for shared
+ * onboarding-domain sends, recipients must be verified workspace members).
  *
  */
 type EmailRejectionReason = "recipient_suppressed" | "transmission_failed" | "generation_failure" | "policy_rejection" | "domain_unverified" | "quota_exceeded" | "recipient_not_allowed";
@@ -1722,7 +1732,7 @@ type EventEmailRejected = {
  */
 type EventEmailReceivedData = {
   /**
-   * ID of the received email. Use it with GET /v1/email/inbound-messages/{id} to fetch the body, raw content, and attachments.
+   * ID of the received email. Fetch its parsed metadata with `GET /v1/email/inbound-messages/{id}`, and its content from that message's `/body`, `/raw`, and `/attachments` sub-resources.
    */
   inbound_message_id: InboundEmailMessageId;
   /**
@@ -1767,12 +1777,12 @@ type EventEmailReceivedData = {
    */
   dmarc_pass?: boolean | null;
   /**
-   * Spam score for the message. Always null at present; reserved for a future content-scoring capability.
+   * Spam score carried on the received message, or null when it carries no score.
    */
   spam_score?: number | null;
 };
 /**
- * Bird received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentication results — enough to route and triage without a fetch. Fetch the body, full headers, and attachments with GET /v1/email/inbound-messages/{id}.
+ * Bird received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentication results, which is enough to route and triage without a fetch. Content is fetched separately: the parsed body with `GET /v1/email/inbound-messages/{id}/body`, the original MIME with `GET /v1/email/inbound-messages/{id}/raw`, and attachment bytes with `GET /v1/email/inbound-messages/{id}/attachments/{attachment_id}`.
  */
 type EventEmailReceived = {
   /**
@@ -1827,7 +1837,13 @@ type EventEmailOutOfBandBounceData = EventEmailBase & {
   sending_ip: string | null;
 };
 /**
- * Bounce classification. `hard` is a permanent failure (invalid address or non-existent domain). `soft` is a transient failure (mailbox full, server temporarily unavailable). `block` indicates the receiving mail server blocked the sending IP for reputation reasons. `admin` indicates an administrative refusal (relaying denied, blocklisted domain). `undetermined` is used when the receiving server's response is ambiguous.
+ * Bounce classification.
+ *
+ * - `hard`: A permanent failure, such as an invalid address or a domain that does not exist.
+ * - `soft`: A transient failure, such as a full mailbox or a server that is temporarily unavailable.
+ * - `block`: The receiving mail server refused the sending IP on reputation grounds.
+ * - `admin`: An administrative refusal, such as relaying denied or a blocklisted domain.
+ * - `undetermined`: The receiving server's response was ambiguous.
  *
  */
 type EmailBounceType = "hard" | "soft" | "undetermined" | "admin" | "block";
@@ -2261,25 +2277,35 @@ type EmailMailboxLabel = {
    */
   readonly name: string;
   /**
-   * `system` labels are built in and carry state — the placements `inbox`, `archive`, `spam`, `blocked`, and `sent`, plus `trash` and `unread`. `custom` labels are the workspace's own tags.
+   * `system` labels are the built-in placements a message can be in:
+   *
+   * - Inbox.
+   * - Archive.
+   * - Spam.
+   * - Blocked.
+   * - Sent.
+   * - Trash.
+   * - Unread.
+   *
+   * `custom` labels are the workspace's own tags.
    */
   readonly type: "system" | "custom";
 };
 /**
- * A new message sent from a mailbox, starting a new conversation. Mirrors the plain send request minus `from` — the mailbox is the sender identity — and minus `scheduled_at` (mailbox sends are immediate). Bird mints the RFC 5322 Message-ID so replies thread back to this conversation. At least one of `html` or `text` must be provided.
+ * A new message sent from a mailbox, starting a new conversation. Mirrors the plain send request without `from`, because the mailbox is who the message comes from, and without `scheduled_at`, because a mailbox sends immediately. We set the RFC 5322 Message-ID so replies thread back into this conversation. At least one of `html` or `text` must be provided.
  *
  */
 type EmailMailboxComposeRequest = {
   /**
-   * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   to: Array<EmailAddressInput>;
   /**
-   * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   cc?: Array<EmailAddressInput>;
   /**
-   * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   bcc?: Array<EmailAddressInput>;
   /**
@@ -2300,7 +2326,7 @@ type EmailMailboxComposeRequest = {
    */
   reply_to?: Array<EmailAddressInput>;
   /**
-   * File attachments. The send is rejected when the estimated generated message size exceeds 20 MB (bodies plus all attachments after base64 encoding). Attachment metadata endures on the message's `attachment_manifest`; the bytes are downloadable for 30 days.
+   * 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 30 days.
    *
    */
   attachments?: Array<EmailAttachment>;
@@ -2319,41 +2345,40 @@ type EmailMailboxComposeRequest = {
   category?: EmailMessageCategory;
 };
 /**
- * Content classification. 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.
+ * 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.
  *
  */
 type EmailMessageCategory = "marketing" | "transactional";
 /**
- * File attached to an email send. The attachment bytes are passed as base64-encoded `content` directly in the request body (required). The `path` field (provide a URL and Bird fetches the attachment for you) is a preview feature and currently unavailable. Requests are rejected with 422 if `content` is missing — `path` alone does not satisfy the schema. When `path` becomes generally available, the schema will be relaxed so that exactly one of `content` or `path` is required.
- * Inline images for `<img src="cid:..."/>` references in the HTML body use the `content_id` field together with `content`.
- * Bird enforces a **20 MB estimated generated message size** cap. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. This is not a raw file-size cap. As a rule of thumb, keep total raw attachment content at or below **15 MB** so the generated message has enough room after encoding and MIME wrapping.
- * Recipient-side delivery reality: downstream limits vary by product and tenant/server policy. Gmail personal and Outlook.com document 25 MB attachment limits. Exchange Online defaults to 35 MB send / 36 MB receive, but admins can configure limits; on-prem Exchange Server organizational defaults are 10 MB. Sends close to Bird's 20 MB generated-message cap may be accepted by Bird but bounce at the recipient's mail server.
- * Batch sends can include attachments on individual message objects. Each message still has the 20 MB estimated generated-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap. Certain executable / script content types are rejected at validation time.
+ * A file attached to an email. Put the file's bytes in `content`, base64-encoded, and give it the `filename` the recipient will see.
+ *
+ * To show an image inline, so that `<img src="cid:..."/>` in your HTML body picks it up, set `content_id` alongside `content`.
+ *
+ * Each message can be at most **20 MB** once it has been generated. That figure covers the HTML body, the text body, and every attachment and inline image, all measured after base64 encoding rather than as raw files. Base64 and MIME wrapping add roughly a third, so keep the raw content of your attachments at or below **15 MB** to stay under the cap.
+ *
+ * A message we accept can still bounce at the other end, because every mail provider sets its own limit. Gmail and Outlook.com both publish a 25 MB limit. Exchange Online defaults to 35 MB for sending and 36 MB for receiving, though an administrator can change both, and on-premise Exchange Server defaults to 10 MB. So a message close to 20 MB is worth testing against the providers your recipients actually use.
+ *
+ * A batch send can attach files to each message in the batch. Every message is still held to the same 20 MB, and the whole request body is capped at 20 MB as well. Executable and script content types are refused when the request is validated.
  *
  */
 type EmailAttachment = {
   /**
-   * Filename shown to the recipient. Required.
+   * The name the recipient sees on the attachment.
    */
   filename: string;
   /**
-   * Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
-   *
+   * The file's bytes, base64-encoded. What you send here counts toward the message's 20 MB limit after encoding and MIME wrapping, not at its raw size.
    */
   content: string;
   /**
-   * Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use `content` instead. The schema currently requires `content`, so a request with only `path` is rejected with 422 for missing `content`; a request supplying both `content` and `path` is rejected with 422 `UnsupportedEmailFeature` until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
-   *
-   */
-  path?: string;
-  /**
-   * MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
-   *
+   * The file's MIME type. Leave it out and we work it out from the extension on `filename`. This is what we check against the list of executable and script types we refuse.
    */
   content_type?: string;
   /**
-   * RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as `<img src="cid:{content_id}"/>`. When omitted, the attachment is rendered as a regular file attachment.
-   *
+   * An RFC 2392 Content-ID for the file. Set it and the attachment is shown inline, so your HTML body can point at it with `<img src="cid:{content_id}"/>`. Leave it out and the file arrives as an ordinary attachment the recipient downloads.
    */
   content_id?: string;
 };
@@ -2371,7 +2396,7 @@ type EmailAddress = {
   name?: string;
 };
 /**
- * A sender or recipient address. Accepts a plain email string (`jane@example.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@example.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request; responses always return the object form.
+ * A sender or recipient address. Accepts a plain email string (`jane@acme.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@acme.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request. Responses always return the object form.
  *
  */
 type EmailAddressInput = string | EmailAddress;
@@ -2406,7 +2431,7 @@ type EmailThreadMessageReplyRequest = {
   };
   category?: EmailMessageCategory;
   /**
-   * 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 endures on the message's `attachment_manifest`; the bytes are downloadable for 30 days.
+   * 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 30 days.
    *
    */
   attachments?: Array<EmailAttachment>;
@@ -2418,7 +2443,7 @@ type EmailThreadMessageAttachmentList = {
   data: Array<EmailThreadMessageAttachment>;
 };
 /**
- * Attachment metadata on a conversation message. The metadata remains readable for the mailbox's retention period; the attachment bytes are downloadable for 30 days after the message occurred.
+ * Attachment metadata on a conversation message. The metadata stays readable for the mailbox's retention tier. The attachment bytes are downloadable for 30 days after the message occurred.
  *
  */
 type EmailThreadMessageAttachment = {
@@ -2440,7 +2465,7 @@ type EmailThreadMessageAttachment = {
   readonly size: number;
 };
 /**
- * The original rendered body of a conversation message. Available for 30 days after the message occurred; after that the endpoint returns `410 Gone` while the message's extracted text remains readable on the message itself.
+ * The original rendered body of a conversation message. Available for 30 days after the message occurred. After that, the endpoint returns `410 Gone`, but the message's extracted text stays readable on the message itself.
  *
  */
 type EmailThreadMessageBody = {
@@ -2455,7 +2480,7 @@ type EmailThreadMessageBody = {
 };
 type ContactId = string;
 /**
- * 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. System labels express state changes: on a conversation, adding `spam` files it as spam, adding `archive` files it away without deleting it, adding `inbox` (or removing `spam` or `archive`) returns it to the inbox, and removing `unread` marks all retained received messages as read in one call; on a message, adding or removing `unread` flips read state, and adding or removing `trash` moves it to or out of the trash. Changes that contradict this model are rejected: adding more than one placement label in one request, adding `blocked` (blocking a sender is a receive-rule decision), removing `inbox` without adding a destination, adding `trash` or `unread` to a conversation (removing `unread` is the mark-all-read shortcut; `trash` uses the DELETE verb), placement labels on a message (move its conversation instead), and `unread` on a sent message. Custom labels are 1-64 characters with no commas, control characters, or leading or trailing whitespace. System label names and a small reserved set (`all`, `archived`, `deleted`, `draft`, `drafts`, `flagged`, `important`, `junk`, `muted`, `none`, `outbox`, `pinned`, `read`, `scheduled`, `snoozed`, `starred`) cannot be used as custom labels, in any casing. A conversation or message carries at most 20 labels, system labels included.
+ * 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. System labels express state changes: on a conversation, adding `spam` files it as spam, adding `archive` files it away without deleting it, adding `inbox` (or removing `spam`, `blocked`, or `archive`) returns it to the inbox, and removing `unread` marks all retained received messages as read in one call; on a message, adding or removing `unread` flips read state, and adding or removing `trash` moves it to or out of the trash. Changes that contradict this model are rejected: adding more than one placement label in one request, adding `blocked` (blocking a sender is a receive-rule decision), removing `inbox` without adding a destination, adding `trash` or `unread` to a conversation (removing `unread` is the mark-all-read shortcut; `trash` uses the DELETE verb), placement labels on a message (move its conversation instead), and `unread` on a sent message. Custom labels are 1-64 characters with no commas, control characters, or leading or trailing whitespace. System label names and a small reserved set (`all`, `archived`, `deleted`, `draft`, `drafts`, `flagged`, `important`, `junk`, `muted`, `none`, `outbox`, `pinned`, `read`, `scheduled`, `snoozed`, `starred`) cannot be used as custom labels, in any casing. A conversation or message has at most 20 labels, system labels included.
  *
  */
 type EmailLabelsUpdate = {
@@ -2469,7 +2494,7 @@ type EmailLabelsUpdate = {
   remove?: Array<string>;
 };
 /**
- * Link to the message's entry in the received-message or sent-message log, which carries delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.
+ * Link to the message's entry in the received-message or sent-message log, which has delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.
  *
  */
 type EmailThreadMessageSource = {
@@ -2483,7 +2508,7 @@ type EmailThreadMessageSource = {
   readonly available_until: string;
 };
 /**
- * One recipient's terminal delivery outcome on a sent conversation message, folded into the message's durable memory when the outcome becomes known.
+ * One recipient's terminal delivery outcome on a sent conversation message, recorded once the outcome becomes known.
  *
  */
 type EmailThreadMessageRecipient = {
@@ -2497,21 +2522,21 @@ type EmailThreadMessageRecipient = {
   readonly status: "delivered" | "failed";
 };
 /**
- * A message in a mailbox conversation, either direction. Message metadata and extracted text remain readable for the mailbox's retention period; the original rendered source (HTML body, raw MIME, attachment bytes) is available through the body, raw, and attachment endpoints for 30 days after the message occurred.
+ * A message in a mailbox conversation, either direction. Message metadata and extracted text stay readable for the mailbox's retention tier. The original rendered source (HTML body, raw MIME, attachment bytes) is available through the body, raw, and attachment endpoints for 30 days after the message occurred.
  *
  */
 type EmailThreadMessage = {
   /**
-   * Message ID. Received messages carry a `rem_` ID, sent messages an `em_` ID — the same IDs used by the received-message and sent-message logs.
+   * Message ID. Received messages have a `rem_` ID, sent messages an `em_` ID: the same IDs used by the received-message and sent-message logs.
    *
    */
   readonly id: string;
   /**
-   * Direction of the message — `inbound` for a received message, `outbound` for a sent one.
+   * Which way the message went. `inbound` means you received it, `outbound` means you sent it.
    */
   readonly direction: "inbound" | "outbound";
   /**
-   * Channel this message was carried on. Always `email`.
+   * Channel this message lives on. Always `email`.
    */
   readonly channel: string;
   /**
@@ -2544,47 +2569,61 @@ type EmailThreadMessage = {
    */
   readonly preview: string | null;
   /**
-   * Plain-text content of the message with quoted history stripped — readable for the mailbox's full retention period, both directions. Always present when fetching a single message; on list endpoints it is included only when the request sets `include=extracted_text`. Null when no text could be extracted.
+   * Plain-text content of the message with quoted history stripped. Readable for the mailbox's full retention tier, in both directions. Always present when fetching a single message. On list endpoints it is included only when the request sets `include=extracted_text`. Null when no text could be extracted.
    *
    */
   readonly extracted_text?: string | null;
   /**
-   * Labels on this message. System labels carry its state: a received message holds exactly one placement label — `inbox` for accepted mail, `archive` when its conversation was filed away, `spam` (failed sender authentication), or `blocked` (rejected by the mailbox's receive policy or rules) — plus `unread` until it is read. `trash` marks a message in the trash, either direction. Custom labels share the same list; a message carries at most 20.
+   * Labels on this message. A received message always has exactly one placement label:
+   *
+   * - `inbox`: Accepted mail.
+   * - `archive`: The message's conversation was filed away.
+   * - `spam`: The message failed sender authentication.
+   * - `blocked`: The message was rejected by the mailbox's receive policy or rules.
+   *
+   * A received message also has `unread` until it is read. `trash` marks a message in the trash, in either direction. Custom labels share the same list, and a message has at most 20 labels in total.
    *
    */
   labels: Array<string>;
   /**
-   * Folded delivery status of a sent message: `accepted`, `sent` (provider handoff), `delivered` (all attempted recipients delivered), or `failed` (terminal failure). Null for received messages.
+   * Folded delivery status of a sent message:
+   *
+   * - `accepted`: Accepted for sending.
+   * - `sent`: Handed off to the provider.
+   * - `delivered`: All attempted recipients delivered.
+   * - `failed`: Terminal failure.
+   *
+   * Null for received messages.
    *
    */
   readonly status: string | null;
   /**
-   * Terminal per-recipient delivery outcomes of a sent message, folded in as they become known — part of the message's durable memory. Null for received messages and before any recipient reaches a terminal state. Per-recipient event detail lives on the sent-message log (`source`) for 30 days.
+   * Terminal per-recipient delivery outcomes of a sent message, filled in as each one becomes known and kept for the mailbox's full retention tier. Null for received messages and before any recipient reaches a terminal state. Per-recipient event detail lives on the sent-message log (`source`) for 30 days.
    *
    */
   readonly recipients: Array<EmailThreadMessageRecipient> | null;
   /**
-   * Whether the sender of a received message was authenticated. `pass` means the sender's identity was verified; `fail` means it was checked and did not verify; `unknown` means no verdict could be determined and the sender should not be treated as verified. Null for sent messages. Part of the message's durable memory — readable for the mailbox's full retention period, so the verdict survives after the 30-day inbound log has expired.
+   * Whether the sender of a received message was authenticated. `pass` means the sender's identity was verified. `fail` means it was checked and did not verify. `unknown` means no verdict could be determined, and the sender should not be treated as verified. Null for sent messages. This field is readable for the mailbox's full retention tier, so the verdict is still available after the 30-day received-message log has expired.
    *
    */
   readonly authentication: "pass" | "fail" | "unknown" | null;
   /**
-   * Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
+   * Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
    *
    */
   readonly spf_pass: boolean | null;
   /**
-   * Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
+   * Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
    *
    */
   readonly dkim_pass: boolean | null;
   /**
-   * Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
+   * Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
    *
    */
   readonly dmarc_pass: boolean | null;
   /**
-   * When the message will be permanently deleted: the end of the mailbox's retention period, pulled nearer (at most 30 days out) while the message is in the trash. Restore a trashed message before then with `PATCH {"labels": {"remove": ["trash"]}}`.
+   * When the message will be permanently deleted: the end of the mailbox's retention tier, pulled nearer (at most 30 days out) while the message is in the trash. Restore a trashed message before then with `PATCH {"labels": {"remove": ["trash"]}}`.
    *
    */
   readonly purge_at: string;
@@ -2593,7 +2632,7 @@ type EmailThreadMessage = {
    */
   readonly attachment_count: number;
   /**
-   * Attachment metadata (filename, content type, size). Remains readable for the mailbox's retention period even after the attachment bytes themselves have expired.
+   * Attachment metadata (filename, content type, size). Stays readable for the mailbox's retention tier even after the attachment bytes themselves have expired.
    *
    */
   readonly attachment_manifest: Array<EmailThreadMessageAttachment>;
@@ -2636,7 +2675,7 @@ type EmailThreadHighlights = {
   text?: Array<string>;
 };
 /**
- * A conversation in a mailbox. Threads group related messages both directions — mail the mailbox received and replies it sent — and carry the conversation-level read state, labels, and participant list. Message counts reflect the messages currently retained under the mailbox's retention period.
+ * A conversation in a mailbox. It groups every message in both directions, the mail the mailbox received and the replies it sent, and it holds the conversation's read state, labels, and participant list. A message is retained until it is trashed or ages past the mailbox's retention tier. Only retained messages count toward the totals below.
  *
  */
 type EmailThread = {
@@ -2677,11 +2716,18 @@ type EmailThread = {
    */
   readonly last_message_at: string;
   /**
-   * Direction of the most recent message — `inbound` for a received message, `outbound` for a sent one.
+   * Direction of the most recent message: `inbound` for a received message, `outbound` for a sent one.
    */
   readonly last_direction: "inbound" | "outbound";
   /**
-   * Labels on this conversation. Exactly one system placement label is always present — `inbox`, `archive` (filed away, done for now), `spam` (the opening message failed sender authentication), or `blocked` (rejected by the mailbox's receive policy or rules) — set by the message that started the conversation. Move a conversation by updating its labels: add `spam` to file it as spam, add `archive` to clean it out of the inbox, and add `inbox` — or remove `spam`, `blocked`, or `archive` — to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list; a conversation carries at most 20.
+   * Labels on this conversation. Exactly one system placement label is always present, set by the message that started the conversation:
+   *
+   * - `inbox`: The conversation is in the inbox.
+   * - `archive`: The conversation was filed away and is done for now.
+   * - `spam`: The conversation's opening message failed sender authentication.
+   * - `blocked`: The conversation's opening message was rejected by the mailbox's receive policy or rules.
+   *
+   * Move a conversation by updating its labels. Add `spam` to file it as spam, add `archive` to clean it out of the inbox, and add `inbox`, or remove `spam`, `blocked`, or `archive`, to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list, and a conversation has at most 20 labels in total.
    *
    */
   labels: Array<string>;
@@ -2694,7 +2740,7 @@ type EmailThread = {
    */
   readonly updated_at: string;
   /**
-   * Matched search fragments, keyed by the field that matched. Returned only by thread search; omitted when listing threads.
+   * Matched search fragments, keyed by the field that matched. Returned only by thread search. Omitted when listing threads.
    *
    */
   readonly highlights?: EmailThreadHighlights;
@@ -2752,7 +2798,7 @@ type ReceiveRule = {
   readonly created_at: string;
 };
 /**
- * A mailbox's sent and received email statistics: a period-wide summary plus a bucketed time series. `period` echoes the range and grain the server computed against; `data` is one row per bucket in chronological order.
+ * A mailbox's sent and received email statistics: a period-wide summary plus a bucketed time series. `period` echoes the range and grain actually used. `data` is one row per bucket in chronological order.
  *
  */
 type MailboxStatsResponse = {
@@ -2764,7 +2810,7 @@ type MailboxStatsResponse = {
   readonly data: Array<MailboxStatsPoint>;
 };
 /**
- * Per-mailbox email activity for one time bucket, bucketed by event time. Sent-mail metrics carry the same delivery, engagement, and latency breakdowns as the email stats endpoints; `received` counts mail that arrived at the mailbox. Buckets with no activity are included with zero counts and null latency percentiles.
+ * Per-mailbox email activity for one time bucket, bucketed by event time. Sent-mail metrics use the same delivery, engagement, and latency breakdowns as the email stats endpoints. `received` counts mail that arrived at the mailbox. Buckets with no activity are included with zero counts and null latency percentiles.
  *
  */
 type MailboxStatsPoint = {
@@ -2806,9 +2852,9 @@ type EmailLatencyQuantiles = {
 /**
  * Latency percentiles (p50, p95, p99) in milliseconds for the bucket. On the summary endpoint these are computed across the whole period rather than per bucket. Three families are reported:
  *
- * - `processing`: time from accepting the send to handing the message off for delivery, covering internal queue depth and handoff. Measured per processed recipient; null when no recipient in the bucket has reached the processed stage.
- * - `delivery`: time from handoff to the receiving mail server accepting the message, dominated by recipient-side delivery behaviour. Measured per delivered recipient; null when no deliveries occurred in the bucket.
- * - `total`: end-to-end time from accepting the send to delivery, the most useful tile for a customer SLO. Measured per delivered recipient; null when no deliveries occurred in the bucket.
+ * - `processing`: Time from accepting the send to handing the message off for delivery. Measured per processed recipient; null when no recipient in the bucket has reached the processed stage.
+ * - `delivery`: Time from handoff to the receiving mail server accepting the message, dominated by recipient-side delivery behavior. Measured per delivered recipient; null when no deliveries occurred in the bucket.
+ * - `total`: End-to-end time from accepting the send to delivery, and the number most worth watching against your own delivery targets. Measured per delivered recipient; null when no deliveries occurred in the bucket.
  *
  * Each family is reported independently and is omitted entirely when no qualifying event contributed a latency measurement in the bucket (including when latency for that stage has not yet been recorded for the workspace), so `processing` can be present while `delivery` and `total` are absent. A client must handle a missing family, and a null p50/p95/p99 within a present family, by rendering a placeholder rather than assuming a number.
  *
@@ -2819,7 +2865,7 @@ type EmailLatencyStats = {
   total?: EmailLatencyQuantiles;
 };
 /**
- * Engagement counts and rates for the scope of the containing row (a time bucket, a breakdown dimension, or the whole period). `opens`, `opens_non_prefetched` and `clicks` count distinct engagement events (deduplicated occurrences); the `unique_*` fields count distinct recipients; `unsubscribes` counts distinct unsubscribe events. Counts are attributed by event time (not send time), so an open recorded today for a message sent earlier counts in today's row. Counts are deduplicated with a scalable approximate counting method, so very large counts are close estimates rather than exact tallies. Each rate divides the counts in this scope and is null when its denominator is zero.
+ * Engagement counts and rates for the scope of the containing row (a time bucket, a breakdown dimension, or the whole period). `opens`, `opens_non_prefetched` and `clicks` count distinct engagement events (deduplicated occurrences). The `unique_*` fields count distinct recipients. `unsubscribes` counts distinct unsubscribe events. Counts are attributed by event time (not send time), so an open recorded today for a message sent earlier counts in today's row. Counts are deduplicated with a scalable approximate counting method, so very large counts are close estimates rather than exact tallies. Each rate divides the counts in this scope and is null when its denominator is zero.
  *
  */
 type EmailEngagementStats = {
@@ -2884,7 +2930,7 @@ type EmailBounceStatsWithRates = {
    */
   readonly soft: number;
   /**
-   * Distinct recipients bounced by an upstream policy block (relaying denied, blocklisted domain).
+   * Distinct recipients refused by a policy at the receiving end, such as relaying denied or a blocklisted domain.
    */
   readonly admin: number;
   /**
@@ -2922,12 +2968,21 @@ type EmailBounceStatsWithRates = {
   readonly undetermined_rate: number | null;
 };
 /**
- * Delivery pipeline counts and rates for the scope of the containing row (a time bucket, a breakdown dimension, or the whole period). Every count is the number of distinct recipients that reached the named lifecycle stage in scope (on the period summary, the sum of the per-bucket distinct counts), attributed by event time (not send time): a recipient delivered on Monday counts in Monday's row, and a recipient who bounced then succeeded on a retry can appear in both `bounced` and `delivered`. Counts are deduplicated with a scalable approximate counting method, so very large counts are close estimates rather than exact tallies. These counts are successive lifecycle stages, not interchangeable categories: `rejected` happens before any send attempt (suppression, policy, generation failure); `deferred` is a temporary in-flight delay still being retried; `bounced` (with its hard/soft/admin/block/undetermined sub-types) is a delivery failure; and `complained` is post-delivery spam feedback. Each rate is a fraction in the range 0 to 1 and is null when its denominator is zero. `accepted` is reported only where it can be attributed (time buckets and the period summary); breakdown rows omit it.
+ * Delivery counts and rates for the scope of the containing row (a time bucket, a breakdown dimension, or the whole period). Every count is the number of distinct recipients that reached the named lifecycle stage in scope (on the period summary, the sum of the per-bucket distinct counts), attributed by event time (not send time): a recipient delivered on Monday counts in Monday's row, and a recipient who bounced then succeeded on a retry can appear in both `bounced` and `delivered`. Very large counts are close estimates rather than exact tallies.
+ *
+ * These counts are successive lifecycle stages, so a recipient can appear in more than one:
+ *
+ * - `rejected`: Happens before any send attempt, from suppression, policy, or a generation failure.
+ * - `deferred`: A temporary in-flight delay that is still being retried.
+ * - `bounced`: A delivery failure, with its own hard, soft, admin, block, and undetermined sub-types.
+ * - `complained`: Post-delivery spam feedback.
+ *
+ * Each rate is a fraction in the range 0 to 1 and is null when its denominator is zero. `accepted` is reported only where it can be attributed (time buckets and the period summary). Breakdown rows omit it.
  *
  */
 type EmailDeliveryStats = {
   /**
-   * Distinct recipients accepted for delivery after suppression filtering. Reported on time buckets and the period summary; omitted on breakdown rows, whose rollups do not carry it.
+   * Distinct recipients accepted for delivery after suppression filtering. Reported on time buckets and the period summary. Breakdown rows leave it out, because their rollups do not have it.
    */
   readonly accepted?: number;
   /**
@@ -2939,7 +2994,7 @@ type EmailDeliveryStats = {
    */
   readonly delivered: number;
   /**
-   * Distinct recipients whose delivery failed. Approximately the sum of the five `bounces.*` sub-counts (hard, soft, admin, block, undetermined); the totals are computed independently so they may differ slightly at the approximation error.
+   * Distinct recipients whose delivery failed. This is approximately the sum of the five `bounces.*` sub-counts (hard, soft, admin, block, undetermined). The two totals are worked out independently, so they can differ slightly.
    *
    */
   readonly bounced: number;
@@ -2981,7 +3036,7 @@ type EmailDeliveryStats = {
    */
   readonly delivery_rate: number | null;
   /**
-   * Share of this scope's delivery attempts that ultimately failed (inband or out-of-band), computed as `all_bounces / (delivered + bounced)`. Because `oob_bounces` counts events rather than recipients, `all_bounces` can exceed the attempt count; the rate is clamped to 1. Null when there were no attempts.
+   * Share of this scope's delivery attempts that ultimately failed (inband or out-of-band), computed as `all_bounces / (delivered + bounced)`. Because `oob_bounces` counts events rather than recipients, `all_bounces` can exceed the attempt count. The rate is clamped to 1. Null when there were no attempts.
    *
    */
   readonly bounce_rate: number | null;
@@ -2992,7 +3047,7 @@ type EmailDeliveryStats = {
   readonly complaint_rate: number | null;
 };
 /**
- * Single-row aggregate of the mailbox's email activity across the full requested period. Counts are sums of per-bucket counts across the window; latency percentiles are computed across the whole period rather than summed per bucket. Rates are null when their denominator is zero.
+ * Single-row aggregate of the mailbox's email activity across the full requested period. Counts are sums of per-bucket counts across the window. Latency percentiles are computed across the whole period rather than summed per bucket. Rates are null when their denominator is zero.
  *
  */
 type MailboxStatsSummary = {
@@ -3018,22 +3073,22 @@ type StatsGrain = "day" | "hour";
  */
 type EmailStatsSeriesPeriod = {
   /**
-   * Inclusive start of the window. A calendar day (YYYY-MM-DD, in the requested `timezone`) on the day grain; on the hour grain, an RFC 3339 UTC instant marking the start of the first hour bucket, which falls on a local hour boundary when `timezone` is set.
+   * Inclusive start of the window. A calendar day (YYYY-MM-DD, in the requested `timezone`) on the day grain. On the hour grain, an RFC 3339 UTC instant marking the start of the first hour bucket, which falls on a local hour boundary when `timezone` is set.
    */
   readonly from: string;
   /**
-   * Inclusive end of the window. A calendar day (YYYY-MM-DD, in the requested `timezone`) on the day grain; on the hour grain, an RFC 3339 UTC instant marking the start of the last hour bucket, which falls on a local hour boundary when `timezone` is set.
+   * Inclusive end of the window. A calendar day (YYYY-MM-DD, in the requested `timezone`) on the day grain. On the hour grain, an RFC 3339 UTC instant marking the start of the last hour bucket, which falls on a local hour boundary when `timezone` is set.
    */
   readonly to: string;
   readonly grain: StatsGrain;
   /**
-   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
+   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response reflects data from up to a few seconds ago. Use this field to label data freshness rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
    *
    */
   readonly data_as_of?: string | null;
 };
 /**
- * Fields to update on a mailbox. Omitted fields are unchanged; fields set to null are cleared. The address and domain are immutable.
+ * Fields to update on a mailbox. Omitted fields are unchanged. Fields set to null are cleared. The address and domain are immutable.
  */
 type MailboxUpdate = {
   /**
@@ -3049,11 +3104,11 @@ type MailboxUpdate = {
    */
   receive_policy?: "open" | "replies_only" | "allowlist" | "drop";
   /**
-   * How long the mailbox remembers message metadata and extracted text. Lowering the tier deletes memory older than the new horizon and requires `confirm=true` when messages older than the new horizon would be deleted. Only `30d` is available today; additional tiers are planned.
+   * How long the mailbox remembers message metadata and extracted text. Lowering the tier deletes remembered messages older than the new horizon, and requires `confirm=true` when that would happen.
    */
   retention_tier?: "30d";
   /**
-   * Replaces the mailbox's key/value data. Up to 2 KB; keys starting with `__bird` are reserved.
+   * Replaces the mailbox's key/value data. Up to 2 KB. Keys starting with `__bird` are reserved.
    */
   metadata?: {
     [key: string]: unknown;
@@ -3064,11 +3119,11 @@ type MailboxUpdate = {
  */
 type MailboxCreate = {
   /**
-   * 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 (no leading, trailing, or repeated separators), reserved names such as `postmaster` or `abuse` are unavailable, and choosing your own local part uses one of your plan's custom-handle allowance slots (generated addresses are always available). Omit to have Bird generate a random local part.
+   * 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 (no leading, trailing, or repeated separators), reserved names such as `postmaster` or `abuse` are unavailable, and choosing your own local part uses one of your plan's custom-handle allowance slots (generated addresses are always available). Omit it and we generate a random local part.
    */
   local_part?: string;
   /**
-   * The domain the address lives under. Defaults to `inbox.ai`, Bird's shared mailbox domain, where creating the mailbox claims the address for your organization: first come, first served, and permanently reserved to your organization even after the mailbox is deleted. May instead name one of your own domains that is enabled for receiving email.
+   * The domain the address lives under. Defaults to `inbox.ai`, our shared mailbox domain, where creating the mailbox claims the address for your organization: first come, first served, and permanently reserved to your organization even after the mailbox is deleted. May instead name one of your own domains that is enabled for receiving email.
    */
   domain?: string;
   /**
@@ -3080,15 +3135,23 @@ type MailboxCreate = {
    */
   default_reply_to?: string;
   /**
-   * 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, not merely land in an existing thread); `allowlist` accepts only senders matching an allow rule; `drop` stores nothing.
+   * 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.
+   *
    */
   receive_policy?: "open" | "replies_only" | "allowlist" | "drop";
   /**
-   * How long the mailbox remembers message metadata and extracted text. Original rendered source is always available for 30 days regardless of tier. Only `30d` is available today; additional tiers are planned.
+   * How long the mailbox remembers message metadata and extracted text. Original rendered source is always available for 30 days regardless of tier.
    */
   retention_tier?: "30d";
   /**
-   * Your own key/value data to attach to the mailbox. Up to 2 KB; keys starting with `__bird` are reserved.
+   * Your own key/value data to attach to the mailbox. Up to 2 KB. Keys starting with `__bird` are reserved.
    */
   metadata?: {
     [key: string]: unknown;
@@ -3130,11 +3193,20 @@ type Mailbox = {
    */
   default_reply_to: string | null;
   /**
-   * 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, not merely land in an existing thread); `allowlist` accepts only senders matching an allow rule (replies to prior outbound are always admitted unless blocked); `drop` stores nothing.
+   * 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. Replies to
+   * prior outbound mail are always admitted unless blocked.
+   * - `drop`: Stores nothing.
+   *
    */
   receive_policy: "open" | "replies_only" | "allowlist" | "drop";
   /**
-   * Lifecycle state. Suspended mailboxes stop emitting events; inbound mail is retained as blocked.
+   * Lifecycle state. Suspended mailboxes stop emitting events. Inbound mail is retained as blocked.
    */
   readonly state: "active" | "suspended";
   /**
@@ -3147,7 +3219,7 @@ type Mailbox = {
    */
   readonly inbound_address_id: InboundAddressId;
   /**
-   * How long the mailbox remembers message metadata and extracted text. Original rendered source (HTML, raw message, attachments) is always available for 30 days regardless of tier. `3y` and `10y` are reserved future tiers.
+   * How long the mailbox remembers message metadata and extracted text. Original rendered source (HTML, raw message, attachments) is always available for 30 days regardless of tier.
    */
   retention_tier: "30d" | "90d" | "1y";
   /**
@@ -3164,13 +3236,13 @@ type Mailbox = {
    */
   readonly unread_thread_count?: number | null;
   /**
-   * Your own key/value data attached to the mailbox. Up to 2 KB; keys starting with `__bird` are reserved.
+   * Your own key/value data attached to the mailbox. Up to 2 KB. Keys starting with `__bird` are reserved.
    */
   metadata: {
     [key: string]: unknown;
   };
   /**
-   * Whether Bird generated the local part of the address. `false` means a custom handle was chosen at creation; on the shared `inbox.ai` domain a custom handle counts against your plan's custom-handle allowance.
+   * Whether we generated the local part of the address. `false` means a custom handle was chosen at creation. On the shared `inbox.ai` domain a custom handle counts against your plan's custom-handle allowance.
    */
   readonly local_part_generated?: boolean;
   /**
@@ -3512,17 +3584,17 @@ type EmailStatsByBroadcastResponse = {
    */
   readonly data: Array<EmailBroadcastStatsPoint>;
   /**
-   * Total number of distinct broadcasts with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct broadcasts with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Aggregate delivery, engagement, and latency stats for the messages of a single broadcast over the requested period.
+ * Delivery, engagement and latency figures for one broadcast's messages over the period you asked for.
  */
 type EmailBroadcastStatsPoint = {
   /**
-   * The broadcast this row aggregates, the same identifier returned by the broadcast endpoints. Only messages sent as part of a broadcast carry a broadcast identifier; one-off and transactional sends are not included in this breakdown.
+   * The broadcast this row covers, the same ID the broadcast endpoints return. Only mail sent as part of a broadcast has a broadcast ID, so one-off and transactional sends do not appear in this breakdown at all.
    */
   readonly broadcast_id: string;
   readonly delivery: EmailDeliveryStats;
@@ -3530,7 +3602,7 @@ type EmailBroadcastStatsPoint = {
   readonly latency: EmailLatencyStats;
 };
 /**
- * The date range the server actually computed against. Echoed back so clients can render the period without tracking it themselves and so cached responses can be keyed by what was queried.
+ * The date range this response was actually computed against. Echoed back so clients can render the period without tracking it themselves and so cached responses can be keyed by what was queried.
  *
  */
 type EmailStatsPeriod = {
@@ -3543,7 +3615,7 @@ type EmailStatsPeriod = {
    */
   readonly to: string;
   /**
-   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
+   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response reflects data from up to a few seconds ago. Use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
    *
    */
   readonly data_as_of?: string | null;
@@ -3561,13 +3633,13 @@ type EmailStatsByComplaintTypeResponse = {
    */
   readonly data: Array<EmailComplaintTypeStatsPoint>;
   /**
-   * Total number of distinct feedback types with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct feedback types with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Complaint counts for a single feedback-loop complaint type over the requested period. A complaint type is recorded only on spam-complaint events, so this breakdown reports the complained count for each type and nothing else (a complaint event carries no delivery or engagement context to aggregate).
+ * Complaint counts for a single feedback-loop complaint type over the requested period. A complaint type is recorded only on spam-complaint events, so this breakdown reports the complained count for each type and nothing else. A complaint event has no delivery or engagement information attached to it, so there is nothing else here to count.
  *
  */
 type EmailComplaintTypeStatsPoint = {
@@ -3593,7 +3665,7 @@ type EmailStatsByBounceCodeResponse = {
    */
   readonly data: Array<EmailBounceCodeStatsPoint>;
   /**
-   * Total number of distinct SMTP error codes with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct SMTP error codes with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -3614,7 +3686,7 @@ type EmailBounceStats = {
    */
   readonly soft: number;
   /**
-   * Distinct recipients bounced by an upstream policy block (relaying denied, blocklisted domain). Triage usually focuses on content or sender configuration rather than recipient cleanup.
+   * Distinct recipients refused by a policy at the receiving end, such as relaying denied or a blocklisted domain. Fixing these usually means changing your content or your sender configuration, not cleaning up the recipient list.
    *
    */
   readonly admin: number;
@@ -3630,7 +3702,7 @@ type EmailBounceStats = {
   readonly undetermined: number;
 };
 /**
- * Bounce counts for a single SMTP status code over the requested period, with the per-type breakdown. This is a deliverability-debugging view keyed on what the receiving server returned, so it reports the failure side only (bounced recipients and their hard/soft/admin/block/undetermined split) and carries no delivered, open, or rate fields.
+ * Bounce counts for a single SMTP status code over the requested period, with the per-type breakdown. This is a deliverability-debugging view keyed on what the receiving mail server returned, so it only reports the failure side: bounced recipients, and their `hard`, `soft`, `admin`, `block`, and `undetermined` split. It has no delivered, open, or rate fields.
  *
  */
 type EmailBounceCodeStatsPoint = {
@@ -3639,7 +3711,7 @@ type EmailBounceCodeStatsPoint = {
    */
   readonly smtp_error_code: string;
   /**
-   * Distinct recipients whose delivery failed with this SMTP status code. Approximately the sum of the five `bounces.*` sub-counts; the totals are computed independently so they may differ slightly at the approximation error.
+   * Distinct recipients whose delivery failed with this SMTP status code, approximately equal to the sum of the five `bounces.*` sub-counts. The two are computed independently, so they can differ slightly because of approximation.
    */
   readonly bounced: number;
   readonly bounces: EmailBounceStats;
@@ -3657,13 +3729,13 @@ type EmailStatsByClientResponse = {
    */
   readonly data: Array<EmailClientStatsPoint>;
   /**
-   * Total number of distinct values of the requested `group_by` facet with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct values of the requested `group_by` facet with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Open and click counts for a breakdown row whose dimension is resolved from engagement events only. `opens`, `opens_non_prefetched` and `clicks` count distinct engagement events (deduplicated occurrences); the `unique_*` fields count distinct recipients. Rates and unsubscribe counts are not included: there is no per-dimension delivered denominator for a rate, and unsubscribe events do not carry the engagement context this breakdown is keyed on.
+ * Open and click counts for a breakdown row whose dimension is resolved from engagement events only. `opens`, `opens_non_prefetched`, and `clicks` count events, not people: the same recipient opening or clicking more than once counts each time. The `unique_*` fields count distinct recipients instead, so a recipient who opened five times only counts once there. Rates and unsubscribe counts are not included here. There is no per-dimension delivered count to use as a rate's denominator, and an unsubscribe event has none of the information this breakdown is grouped by, so it cannot be placed on a row.
  *
  */
 type EmailEngagementCounts = {
@@ -3695,20 +3767,20 @@ type EmailEngagementCounts = {
   readonly unique_clicks: number;
 };
 /**
- * Engagement counts for messages opened or clicked from a single email client, operating system, or device type over the requested period. The reading environment is resolved from open and click events only, so this breakdown reports engagement activity (opens, clicks, and the recipients behind them); it carries no delivery counts and no open/click rates, because the receiving mail server reports delivery without a client or device, leaving no per-client delivered denominator to divide by. Exactly one of `email_client`, `os`, and `device_type` is populated, selected by the request's `group_by`; the other two are null. Engagement environment is detected from the opening client and is subject to the same inbox-privacy prefetch effects as the open counts (the `opens_non_prefetched` figure excludes auto-fetched opens).
+ * Engagement counts for messages opened or clicked from a single email client, operating system, or device type over the requested period. The reading environment is resolved from open and click events only, so this breakdown reports engagement activity: opens, clicks, and the recipients behind them. It has no delivery counts and no open or click rates, because the receiving mail server reports delivery without a client or device, so there is no per-client delivered denominator to divide by. Exactly one of `email_client`, `os`, and `device_type` is populated, selected by the request's `group_by`. The other two are null. The detected client is also affected by inbox-privacy prefetching, the same way open counts are: `opens_non_prefetched` excludes opens that were auto-fetched by an inbox privacy feature rather than by a person actually opening the message.
  *
  */
 type EmailClientStatsPoint = {
   /**
-   * The mail client this row aggregates (for example `Gmail`, `Apple Mail`, `Outlook`). Populated only when `group_by=email_client`; null otherwise.
+   * The mail client this row aggregates (for example `Gmail`, `Apple Mail`, `Outlook`). Populated only when `group_by=email_client`. Null otherwise.
    */
   readonly email_client: string | null;
   /**
-   * The operating system this row aggregates (for example `iOS`, `Android`, `Windows`, `macOS`). Populated only when `group_by=os`; null otherwise.
+   * The operating system this row aggregates (for example `iOS`, `Android`, `Windows`, `macOS`). Populated only when `group_by=os`. Null otherwise.
    */
   readonly os: string | null;
   /**
-   * The device type this row aggregates (for example `mobile`, `desktop`, `tablet`). Populated only when `group_by=device_type`; null otherwise.
+   * The device type this row aggregates (for example `mobile`, `desktop`, `tablet`). Populated only when `group_by=device_type`. Null otherwise.
    */
   readonly device_type: string | null;
   readonly engagement: EmailEngagementCounts;
@@ -3726,13 +3798,13 @@ type EmailStatsByLocationResponse = {
    */
   readonly data: Array<EmailLocationStatsPoint>;
   /**
-   * Total number of distinct locations at the requested `group_by` level with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct locations at the requested `group_by` level with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Open and click counts for messages engaged with from a single location over the requested period. Location is resolved from open and click events only, so this breakdown reports engagement activity (opens, clicks, and the recipients behind them); it carries no delivery counts and no open/click rates, because the receiving mail server reports delivery without a recipient location, leaving no per-location delivered denominator to divide by. Each row always includes all three of `country`, `region`, and `city`; the levels below the requested `group_by` are null.
+ * Open and click counts for messages engaged with from a single location over the requested period. Location is resolved from open and click events only, so this breakdown reports engagement activity: opens, clicks, and the recipients behind them. It has no delivery counts and no open or click rates, because the receiving mail server reports delivery without a recipient location, so there is no per-location delivered denominator to divide by. Each row always includes all three of `country`, `region`, and `city`; the levels below the requested `group_by` are null.
  *
  */
 type EmailLocationStatsPoint = {
@@ -3756,25 +3828,28 @@ type EmailLocationStatsPoint = {
  */
 type EmailEngagementSortMetric = "opens" | "opens_non_prefetched" | "unique_opens" | "unique_opens_non_prefetched" | "clicks" | "unique_clicks";
 /**
- * Per-template breakdown for the requested period, ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, max 200).
+ * A breakdown of stats per template for the requested period. Rows are ranked by the `sort` metric (`processed` by default) descending, and capped at the requested `limit` (50 by default, 200 at most).
+ *
  */
 type EmailStatsByTemplateResponse = {
   /**
-   * The date range the response covers (echoed back from the request), plus `data_as_of`, the freshness boundary the data is current to.
+   * The date range this response covers, echoed back from what you requested, plus `data_as_of`: how far the underlying data is currently up to date.
+   *
    */
   period: EmailStatsPeriod;
   /**
-   * Template breakdown rows, ranked by the `sort` metric (default `processed`) descending. Empty when no templated messages were active in the period.
+   * One row per template, ranked by the `sort` metric (`processed` by default) descending. Empty when no messages were sent with a template during the period.
+   *
    */
   readonly data: Array<EmailTemplateStatsPoint>;
   /**
-   * Total number of distinct templates with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * How many distinct templates had activity in the period, regardless of `limit`. When this is higher than the number of rows in `data`, the ranking got cut off. Raise `limit` (up to 200), or narrow the date range, to see the rest.
    *
    */
   readonly total: number;
 };
 /**
- * One point in a breakdown row's trend series: the headline delivery and engagement rates for that row's dimension value over a single day or hour. Returned only when `include_trend=true`; the bucket grain (day or hour) follows the `trend_grain` parameter. Counts and rates are approximate at scale.
+ * One point in a breakdown row's trend series: the headline delivery and engagement rates for that row's dimension value over a single day or hour. Returned only when `include_trend=true`. The bucket grain (day or hour) follows the `trend_grain` parameter. Counts and rates are approximate at scale.
  *
  */
 type EmailStatsSeriesPoint = {
@@ -3799,32 +3874,34 @@ type EmailStatsSeriesPoint = {
    */
   readonly bounce_rate: number | null;
   /**
-   * Complaint rate for this bucket, as a fraction; event-time attribution can push it above 1 when complaints outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row complaints are not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
+   * Complaint rate for this bucket, as a fraction. Event-time attribution can push it above 1 when complaints outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row complaints are not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
    */
   readonly complaint_rate: number | null;
   /**
-   * Open rate for this bucket, as a fraction; event-time attribution can push it above 1 when opens outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row engagement is not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
+   * Open rate for this bucket, as a fraction. Event-time attribution can push it above 1 when opens outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row engagement is not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
    */
   readonly open_rate: number | null;
   /**
-   * Click rate for this bucket, as a fraction; event-time attribution can push it above 1 when clicks outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row engagement is not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
+   * Click rate for this bucket, as a fraction. Event-time attribution can push it above 1 when clicks outrun the bucket's deliveries. Null when nothing was delivered in the bucket. On a sending-IP row engagement is not attributed to the IP, so this reads 0 in buckets that had deliveries and null in buckets that had none.
    */
   readonly click_rate: number | null;
 };
 type EmailTemplateId = string;
 /**
- * Aggregate delivery, engagement, and latency stats for the messages sent with a single template over the requested period.
+ * Delivery, engagement, and latency numbers for every message sent with one template over the requested period.
  */
 type EmailTemplateStatsPoint = {
   /**
-   * The template this row aggregates, the same identifier returned by the email-template endpoints. Only messages sent with a template appear in this breakdown; a template deleted after sending still appears by its ID.
+   * The template this row is about, using the same `id` the email template endpoints return. Only messages sent with a template appear in this breakdown at all. If the template was deleted after it was used to send, this row still appears, keyed by that same `id`.
+   *
    */
   readonly template_id: EmailTemplateId;
   readonly delivery: EmailDeliveryStats;
   readonly engagement: EmailEngagementStats;
   readonly latency: EmailLatencyStats;
   /**
-   * Per-bucket rate series for this template over the window. Present only when `include_trend=true`.
+   * A short series of this template's delivery and engagement rates, one point per time bucket over the window. Only present when you set `include_trend=true` on the request.
+   *
    */
   readonly trend?: Array<EmailStatsSeriesPoint>;
 };
@@ -3841,7 +3918,7 @@ type EmailStatsByRecipientDomainResponse = {
    */
   readonly data: Array<EmailRecipientDomainStatsPoint>;
   /**
-   * Total number of distinct recipient domains with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct recipient domains with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -3875,7 +3952,7 @@ type EmailStatsByMailboxProviderRegionResponse = {
    */
   readonly data: Array<EmailMailboxProviderRegionStatsPoint>;
   /**
-   * Total number of distinct mailbox provider and region pairs with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct mailbox provider and region pairs with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -3883,10 +3960,10 @@ type EmailStatsByMailboxProviderRegionResponse = {
 /**
  * Latency percentiles (p50, p95, p99) in milliseconds for the messages in this breakdown row, for breakdowns whose dimension is known only from delivery onward (sending IP, mailbox provider).
  *
- * - `delivery`: time from handing the message off to the receiving mail server accepting it. Null when no deliveries occurred for this row in the period.
- * - `total`: end-to-end time from accepting the send to delivery. Null when no deliveries occurred for this row in the period.
+ * - `delivery`: Time from handing the message off to the receiving mail server accepting it. Null when no deliveries occurred for this row in the period.
+ * - `total`: End-to-end time from accepting the send to delivery. Null when no deliveries occurred for this row in the period.
  *
- * These breakdowns have no `processing` latency family. Bird only learns a row's dimension (the sending IP or recipient mailbox provider) after the upstream mail-transfer system reports delivery, bounce, deferral, or late bounce; the accept-to-processed phase happens before that binding decision, so it cannot be attributed to the dimension. Use `GET /v1/email/stats/daily` for workspace-wide processing-latency percentiles.
+ * These breakdowns have no `processing` latency family. Which row a message belongs to, meaning which sending IP carried it or which mailbox provider received it, is only known once the receiving mail server has reported back with a delivery, a bounce, a deferral or a late bounce. The accept-to-processed phase is over before then, so there is no way to attribute it to a row. Use `GET /v1/email/stats/daily` for processing-latency percentiles across the whole workspace.
  *
  */
 type EmailDeliveryLatencyStats = {
@@ -3894,7 +3971,7 @@ type EmailDeliveryLatencyStats = {
   total: EmailLatencyQuantiles;
 };
 /**
- * Delivery counts and rates for messages attributed to a single recipient mailbox provider. Per-provider results do not include `accepted` or `processed` counts because Bird only learns the recipient's mailbox provider after the upstream mail transfer system reports delivery/bounce/deferral/late bounce. Earlier lifecycle states (accepted, processed) cannot be attributed to a specific provider.
+ * Delivery counts and rates for messages attributed to a single recipient mailbox provider. Per-provider results do not include `accepted` or `processed` counts, because we only learn the recipient's mailbox provider once the receiving mail server reports delivery, a bounce, a deferral, or a late bounce. Earlier lifecycle states (accepted, processed) cannot be attributed to a specific provider.
  *
  */
 type EmailMailboxProviderDeliveryStats = {
@@ -3965,18 +4042,18 @@ type EmailStatsByMailboxProviderResponse = {
    */
   readonly data: Array<EmailMailboxProviderStatsPoint>;
   /**
-   * Total number of distinct mailbox providers with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct mailbox providers with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Delivery, engagement, and deliverability stats for messages grouped by a single recipient mailbox provider (`gmail`, `microsoft`, `yahoo`, `apple`, ...) over the requested period. A recipient's mailbox provider is reported by the receiving mail system, so per-provider rows cover the delivery stage onward: they omit the `accepted` and `processed` counts and the `processing` latency family, which never appear (they are not returned as null). Engagement (opens, clicks, and their rates) is included because those events are post-delivery and carry the mailbox provider.
+ * Delivery, engagement, and deliverability stats for messages grouped by a single recipient mailbox provider (`gmail`, `microsoft`, `yahoo`, `apple`, ...) over the requested period. We learn a recipient's mailbox provider from the receiving mail server, so per-provider rows cover the delivery stage onward: they omit the `accepted` and `processed` counts and the `processing` latency family, which never appear at all rather than appearing as null. Engagement (opens and clicks, and their rates) is included because those events happen after delivery, once the mailbox provider is already known.
  *
  */
 type EmailMailboxProviderStatsPoint = {
   /**
-   * The recipient mailbox provider this row aggregates, as a lowercased classifier bucket (e.g. `gmail`, `yahoo`, `microsoft`, `apple`). The set is open and grows as new providers are categorised.
+   * The recipient mailbox provider this row aggregates, as a lowercased classifier bucket (e.g. `gmail`, `yahoo`, `microsoft`, `apple`). The set is open and grows as new providers are categorized.
    */
   readonly mailbox_provider: string;
   readonly delivery: EmailMailboxProviderDeliveryStats;
@@ -3988,7 +4065,7 @@ type EmailMailboxProviderStatsPoint = {
   readonly trend?: Array<EmailStatsSeriesPoint>;
 };
 /**
- * Metric to rank rows by, applied descending. Shared by the breakdowns whose attribution begins at delivery (mailbox providers, mailbox provider regions): `processed`, `rejected`, and `oob_bounces` are not part of those rows, so they are not sortable. Any count or rate the rows carry may be used; rows whose rate is undefined (zero denominator) sort last. Bounce sub-types are addressed by their nested location in each row, for example `bounces.hard` and `bounces.hard_rate`.
+ * Metric to rank rows by, applied descending. Shared by the breakdowns whose attribution begins at delivery (mailbox providers, mailbox provider regions): `processed`, `rejected`, and `oob_bounces` are not part of those rows, so they are not sortable. Any count or rate on the row can be used; rows whose rate is undefined (zero denominator) sort last. Bounce sub-types use their nested location in each row, for example `bounces.hard` and `bounces.hard_rate`.
  *
  */
 type EmailMailboxProviderSortMetric = "delivered" | "bounced" | "complained" | "deferred" | "bounces.hard" | "bounces.soft" | "bounces.admin" | "bounces.block" | "bounces.undetermined" | "opens" | "opens_non_prefetched" | "unique_opens" | "unique_opens_non_prefetched" | "clicks" | "unique_clicks" | "unsubscribes" | "delivery_rate" | "bounce_rate" | "complaint_rate" | "open_rate" | "click_rate" | "unsubscribe_rate" | "bounces.hard_rate" | "bounces.soft_rate" | "bounces.admin_rate" | "bounces.block_rate" | "bounces.undetermined_rate";
@@ -4005,7 +4082,7 @@ type EmailStatsByCategoryResponse = {
    */
   readonly data: Array<EmailCategoryStatsPoint>;
   /**
-   * Total number of distinct categories with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct categories with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -4015,7 +4092,7 @@ type EmailStatsByCategoryResponse = {
  */
 type EmailCategoryStatsPoint = {
   /**
-   * The category this row aggregates, as set at send time. `transactional` is one-to-one mail triggered by a user action; `marketing` is bulk sending. New categories may be added over time.
+   * The category this row aggregates, as set at send time. `transactional` is one-to-one mail triggered by a user action. `marketing` is bulk sending. New categories may be added over time.
    */
   readonly category: string;
   readonly delivery: EmailDeliveryStats;
@@ -4039,7 +4116,7 @@ type EmailStatsBySendingDomainResponse = {
    */
   readonly data: Array<EmailSendingDomainStatsPoint>;
   /**
-   * Total number of distinct sending domains with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct sending domains with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -4073,13 +4150,13 @@ type EmailStatsBySendingIpResponse = {
    */
   readonly data: Array<EmailSendingIpStatsPoint>;
   /**
-   * Total number of distinct sending IP addresses with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct sending IP addresses with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
 };
 /**
- * Delivery counts and rates for messages attributed to a single sending IP. Per-IP results do not include `accepted` or `processed` counts because Bird only learns which sending IP a message used after the upstream mail transfer system reports delivery/bounce/deferral/late bounce. Earlier lifecycle states (accepted, processed) cannot be attributed to a specific IP. Spam complaints and out-of-band bounce notifications are also not attributed per IP on this breakdown, so `complained` and `oob_bounces` read 0 (their rates read 0 where the denominator is non-zero, null where it is zero), `effective_delivered` equals `delivered`, and `all_bounces` equals `bounced`.
+ * Delivery counts and rates for messages attributed to a single sending IP. Per-IP results do not include `accepted` or `processed` counts: we only learn which sending IP a message used once it has been delivered, bounced, deferred, or bounced late, so those earlier lifecycle states cannot be attributed to a specific IP. Spam complaints and out-of-band bounce notifications are also not attributed per IP on this breakdown, so `complained` and `oob_bounces` read 0 (their rates read 0 where the denominator is non-zero, null where it is zero), `effective_delivered` equals `delivered`, and `all_bounces` equals `bounced`.
  *
  */
 type EmailSendingIpDeliveryStats = {
@@ -4088,11 +4165,11 @@ type EmailSendingIpDeliveryStats = {
    */
   readonly delivered: number;
   /**
-   * Distinct recipients whose delivery failed. Approximately the sum of the five `bounces.*` sub-counts (hard, soft, admin, block, undetermined); the totals are computed independently so they may differ slightly at the approximation error.
+   * Distinct recipients whose delivery failed. This is approximately the sum of the five `bounces.*` sub-counts (hard, soft, admin, block, undetermined). The two are computed independently, so they can differ slightly.
    */
   readonly bounced: number;
   /**
-   * Distinct recipients who reported the message as spam. Complaints are not attributed to a sending IP, so this reads 0 on this breakdown; read complaint counts from the summary or time-series statistics instead.
+   * Distinct recipients who reported the message as spam. Complaints are not attributed to a sending IP, so this reads 0 on this breakdown. Read complaint counts from the summary or time-series statistics instead.
    */
   readonly complained: number;
   /**
@@ -4100,7 +4177,7 @@ type EmailSendingIpDeliveryStats = {
    */
   readonly deferred: number;
   /**
-   * Out-of-band bounce events: failure notifications received after the receiving server had initially confirmed delivery. Not attributed to a sending IP on this breakdown, so this reads 0; workspace-wide out-of-band counts are on the summary and time-series statistics.
+   * Out-of-band bounce events: failure notifications received after the receiving server had initially confirmed delivery. Not attributed to a sending IP on this breakdown, so this reads 0. Workspace-wide out-of-band counts are on the summary and time-series statistics.
    *
    */
   readonly oob_bounces: number;
@@ -4135,7 +4212,7 @@ type EmailSendingIpDeliveryStats = {
 };
 type IpPoolId = string;
 /**
- * Delivery and latency stats for messages sent from a single IP address over the requested period. Per-IP attribution begins only after a message is processed: the upstream mail-transfer system reports the IP it used on delivery, bounce, deferral, and late-bounce events, but not at acceptance or processing time. As a result, per-IP rows omit the `accepted` and `processed` counts and the `processing` latency family, which never appear (they are not returned as null).
+ * Delivery and latency stats for messages sent from a single IP address over the requested period. Per-IP attribution begins only after a message is processed: we learn which IP a message used only from its delivery, bounce, deferral, and late-bounce events, not from its acceptance or processing. As a result, per-IP rows omit the `accepted` and `processed` counts and the `processing` latency family. Those fields never appear on a per-IP row. They are not returned as null.
  *
  */
 type EmailSendingIpStatsPoint = {
@@ -4156,9 +4233,21 @@ type EmailSendingIpStatsPoint = {
   readonly trend?: Array<EmailStatsSeriesPoint>;
 };
 /**
- * Single-row aggregate across the full requested period, including delivery and engagement counts plus derived rates. Use this endpoint for KPI tiles, campaign reporting, and any metric that needs a meaningful denominator; the daily and hourly endpoints carry the same rates per bucket, dividing each bucket's own counts.
+ * A single row that aggregates delivery and engagement counts, plus derived
+ * rates, across the whole requested period. Use this endpoint for KPI
+ * tiles, campaign reporting, and anywhere you need a rate with a meaningful
+ * denominator. The daily and hourly endpoints report the same rates, but
+ * per bucket, each one dividing that bucket's own counts.
  *
- * Every count is a sum of per-bucket counts across the window (per day for day windows, per hour for hour windows), so a recipient (or message) active in two buckets contributes one to each bucket and two to the period total. This matches common provider reporting and is not double-counting; it does not yield a period-distinct count. Latency percentiles, by contrast, are computed across the whole period rather than summed per bucket. Rates are null when their denominator is zero.
+ * Every count is a sum of per-bucket counts across the window (per day for
+ * day windows, per hour for hour windows). A recipient, or a message, that
+ * is active in two buckets contributes to each of them, so it is counted
+ * twice in the period total. This matches how most mailbox providers report
+ * their own numbers. The effect to plan for is that the total is a sum of
+ * per-bucket activity rather than a count of distinct recipients or messages
+ * across the whole period. Latency percentiles work differently: they are computed
+ * once across the whole period rather than summed from the buckets. A rate
+ * is null when its denominator is zero.
  *
  */
 type EmailStatsSummary = {
@@ -4176,7 +4265,7 @@ type EmailStatsSummary = {
   readonly comparison?: EmailStatsComparison;
 };
 /**
- * The change in each headline metric from the preceding period to the requested one. A `*_pct_change` is a signed relative change in a count, computed as `(current - previous) / previous` (so `0.5` means 50% higher, `-0.2` means 20% lower), and is null when the previous period's count was zero. A `*_rate_pp` is the signed arithmetic difference between the two periods' rate values, where each rate is a fraction in `[0,1]` (so `0.012` means the rate rose by 0.012, i.e. 1.2 percentage points; `-0.003` means it fell by 0.3 points), and is null when either period's rate is undefined (its denominator was zero). A `*_rate_pp` value ranges from `-1` to `1`: the most a rate can move between periods is from 0 to 1, or 1 to 0.
+ * The change in each headline metric from the preceding period to the requested one. A `*_pct_change` field is a signed relative change in a count, computed as `(current - previous) / previous`, so `0.5` means 50% higher and `-0.2` means 20% lower. It is null when the previous period's count was zero, because there is nothing to compute a relative change from. A `*_rate_pp` field is the signed difference between the two periods' rate values, each expressed as a fraction, so `0.012` means the rate rose by 1.2 percentage points and `-0.003` means it fell by 0.3 points. It is null when either period's rate is undefined, because its denominator was zero. `delivery_rate_pp` and `bounce_rate_pp` range from `-1` to `1`, because the rates behind them cannot exceed 1. The engagement deltas have no fixed bound, because events are counted when they arrive rather than when the message was sent, which can push their rate above 1.
  *
  */
 type EmailStatsComparisonDelta = {
@@ -4244,20 +4333,20 @@ type EmailStatsComparison = {
   readonly delta: EmailStatsComparisonDelta;
 };
 /**
- * The window the server actually computed against. The summary serves two window grains: calendar days (bounds are YYYY-MM-DD) and hours (bounds are RFC 3339 instants). The grain of `from` and `to` mirrors the grain of the request's bounds; days and hour boundaries follow the requested `timezone` (UTC when omitted).
+ * The window this response was actually computed against. The summary serves two window grains: calendar days (bounds are YYYY-MM-DD) and hours (bounds are RFC 3339 instants). The grain of `from` and `to` mirrors the grain of the request's bounds. Days and hour boundaries follow the requested `timezone` (UTC when omitted).
  *
  */
 type EmailStatsSummaryPeriod = {
   /**
-   * Inclusive start of the window the response covers. A calendar day (YYYY-MM-DD, in the requested `timezone`) for day windows; for hour windows, an RFC 3339 UTC instant marking the start of the first hour, which falls on a local hour boundary when `timezone` is set.
+   * Inclusive start of the window the response covers. A calendar day (YYYY-MM-DD, in the requested `timezone`) for day windows. For hour windows, an RFC 3339 UTC instant marking the start of the first hour, which falls on a local hour boundary when `timezone` is set.
    */
   readonly from: string;
   /**
-   * Inclusive end of the window the response covers. A calendar day (YYYY-MM-DD, in the requested `timezone`) for day windows; for hour windows, an RFC 3339 UTC instant marking the start of the last hour, which falls on a local hour boundary when `timezone` is set.
+   * Inclusive end of the window the response covers. A calendar day (YYYY-MM-DD, in the requested `timezone`) for day windows. For hour windows, an RFC 3339 UTC instant marking the start of the last hour, which falls on a local hour boundary when `timezone` is set.
    */
   readonly to: string;
   /**
-   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
+   * The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response reflects data from up to a few seconds ago. Use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
    *
    */
   readonly data_as_of?: string | null;
@@ -4275,7 +4364,7 @@ type EmailStatsTagsResponse = {
    */
   readonly data: Array<EmailTagStatsPoint>;
   /**
-   * Total number of distinct tags (name and value pairs) with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.
+   * Total number of distinct tags (name and value pairs) with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped. Raise `limit` (up to 200) or narrow the window to see more.
    *
    */
   readonly total: number;
@@ -4298,12 +4387,12 @@ type EmailTagStatsPoint = {
   readonly trend?: Array<EmailStatsSeriesPoint>;
 };
 /**
- * Metric to rank breakdown rows by, applied descending. Shared by the breakdowns whose rows carry the full delivery, engagement, and latency block (tags, sending domains, categories, recipient domains, templates, broadcasts). Any count or rate may be used; rows whose rate is undefined (zero denominator) sort last. Bounce sub-types are addressed by their nested location in each row, for example `bounces.hard` and `bounces.hard_rate`.
+ * Metric to rank breakdown rows by, applied descending. Shared by the breakdowns whose rows have the full delivery, engagement, and latency block: tags, sending domains, categories, recipient domains, templates, and broadcasts. Any count or rate can be used. A row whose rate is undefined, because its denominator was zero, sorts last. A bounce sub-type is nested under `bounces` in each row, so its sort name reflects that, for example `bounces.hard` and `bounces.hard_rate`.
  *
  */
 type EmailStatsSortMetric = "processed" | "delivered" | "bounced" | "complained" | "deferred" | "rejected" | "oob_bounces" | "bounces.hard" | "bounces.soft" | "bounces.admin" | "bounces.block" | "bounces.undetermined" | "opens" | "opens_non_prefetched" | "unique_opens" | "unique_opens_non_prefetched" | "clicks" | "unique_clicks" | "unsubscribes" | "delivery_rate" | "bounce_rate" | "complaint_rate" | "open_rate" | "click_rate" | "unsubscribe_rate" | "bounces.hard_rate" | "bounces.soft_rate" | "bounces.admin_rate" | "bounces.block_rate" | "bounces.undetermined_rate";
 /**
- * Time-series stats payload. `period` echoes the range and bucket grain the server computed against; `data` is one row per bucket in chronological order.
+ * Time-series stats payload. `period` echoes the range and bucket grain actually computed against. `data` is one row per bucket in chronological order.
  *
  */
 type EmailStatsResponse = {
@@ -4319,7 +4408,7 @@ type EmailStatsResponse = {
  */
 type EmailStatsPoint = {
   /**
-   * The day (YYYY-MM-DD, in the requested `timezone`) or hour this point covers, matching the period's grain. An hour bucket is an RFC 3339 UTC instant marking the start of the hour; it falls on a local hour boundary when `timezone` is set, which is on the UTC hour only for whole-hour offsets.
+   * The day (YYYY-MM-DD, in the requested `timezone`) or hour this point covers, matching the period's grain. An hour bucket is an RFC 3339 UTC instant marking the start of the hour. It falls on a local hour boundary when `timezone` is set, which is on the UTC hour only for whole-hour offsets.
    */
   readonly bucket: string;
   /**
@@ -4456,7 +4545,7 @@ type WhatsAppMessageTemplateComponent = {
  */
 type LanguageTag = string;
 /**
- * A template's slug: its permanent, workspace-unique handle and API address. Lowercase letters, numbers, hyphens, and underscores. Fixed at creation, so anything that references it never breaks; the display name is the label to change freely.
+ * A template's slug: what you send it by, for example `welcome-email`. You choose it when you create the template, and it cannot be changed afterwards. It can contain lowercase letters, numbers, hyphens, and underscores, has to start and end with a letter or a number, and can be up to 63 characters long.
  *
  */
 type TemplateSlug = string;
@@ -4661,6 +4750,316 @@ type VerificationOptions = {
    */
   channels?: Array<VerificationChannel$1>;
 };
+/**
+ * What we can tell you about an email address: whether it will accept mail, how confident that is, why not when it will not, and what the address looks like it was meant to be when it looks misspelled.
+ *
+ * `result` is the field to decide on; `delivery_confidence` grades it, and `flags` describes the address itself rather than its deliverability, so a perfectly valid address can still have `role` or `disposable`.
+ *
+ * Fields with nothing behind them are left out rather than sent as null, so anything you can read in the response is something we actually resolved.
+ *
+ */
+type EmailLookup = {
+  /**
+   * The address that was looked up, exactly as you sent it.
+   */
+  readonly email: string;
+  /**
+   * Whether the address is well-formed and its domain is set up to receive mail at all. It says nothing about the mailbox itself, so a `valid` domain with no such mailbox is `true` here and `undeliverable` in `result`.
+   */
+  readonly valid: boolean;
+  readonly result: EmailLookupResult$1;
+  /**
+   * How likely mail to this address is to be delivered, from 0 (certain not to be) to 100 (certain to be). Read it alongside `result` rather than instead of it, because the same score can sit under `neutral` or `risky` for different reasons.
+   */
+  readonly delivery_confidence: number;
+  /**
+   * Notable characteristics of the address. Empty when none apply.
+   */
+  readonly flags: Array<EmailLookupFlag$1>;
+  /**
+   * Why the address cannot receive mail. Absent unless `result` is `undeliverable`.
+   */
+  readonly reason?: EmailLookupReason$1;
+  /**
+   * The address this one looks like a misspelling of. Absent unless a correction was found, which in practice means `result` is `typo`. Offer it to whoever typed the original rather than sending to it unasked, because it is a guess and the address they meant may be neither one.
+   */
+  readonly did_you_mean?: string;
+};
+/**
+ * Why an address cannot receive mail. `invalid_syntax` means the address is not a well-formed address at all, `invalid_domain` means the domain does not accept mail anywhere, and `invalid_recipient` means the domain accepts mail but this mailbox does not exist.
+ *
+ * Open enum: further reasons may be added over time, so treat an unrecognized value as a future one rather than an error. `result` is what to branch on; this field explains it.
+ *
+ */
+type EmailLookupReason$1 = "invalid_syntax" | "invalid_domain" | "invalid_recipient" | (string & {});
+/**
+ * A notable characteristic of an email address. `role` means it addresses a function rather than a person (`support@`, `info@`), so replies and consent are ambiguous and complaints are more likely. `disposable` means it belongs to a throwaway-address provider and will stop existing. `free_provider` means it belongs to a consumer mailbox provider such as Gmail or Outlook.com, which is ordinary for consumer mail and a signal when you expected a business address.
+ *
+ * Open enum: more flags may be added over time, so treat an unrecognized value as a future flag rather than an error.
+ *
+ */
+type EmailLookupFlag$1 = "role" | "disposable" | "free_provider" | (string & {});
+/**
+ * The verdict on the address, and the one field to decide on.
+ *
+ * `valid` means the address exists and accepts mail. `neutral` means it could not be confirmed either way, usually because the receiving domain answers every recipient the same. `risky` means it will probably accept the mail but is likelier than most to bounce or complain (a role, disposable, or low-reputation address). `undeliverable` means it will not accept mail, and `reason` says why. `typo` means the address looks like a misspelling of a real one, and `did_you_mean` has the correction.
+ *
+ * Open enum: further verdicts may be added over time, so treat an unrecognized value as a future one rather than an error. Branch on the values you know and fall back on `delivery_confidence`, which is always present and always comparable.
+ *
+ */
+type EmailLookupResult$1 = "valid" | "neutral" | "risky" | "undeliverable" | "typo" | (string & {});
+type EmailLookupRequest = {
+  /**
+   * The email address to look up. Send it exactly as you hold it: the part before the `@` is case-sensitive, so nothing is lowercased for you, and a display-name form such as `Aisha <aisha@example.com>` is rejected rather than unwrapped.
+   *
+   */
+  email: string;
+};
+/**
+ * What Bird knows about a phone number.
+ *
+ * The number, its flags and its line type are the free baseline and are always present; the country and the two networks join them whenever they could be identified. Each property you request through `type` comes back as a block of the same name, carrying its own `status`. A property you did not request is absent altogether, and a property that could not be answered is present with its `status` alone. You are billed for exactly the properties whose status is `ok`.
+ *
+ * Fields with nothing behind them are left out rather than sent as null, so anything you can read in the response is something Bird actually resolved.
+ *
+ */
+type PhoneNumberLookup = {
+  /**
+   * The number that was looked up, in E.164 format.
+   */
+  readonly phone_number: string;
+  /**
+   * The ISO 3166-1 alpha-2 country of the number. Absent when the number belongs to no single country, as a non-geographic range does.
+   */
+  readonly country_code?: CountryCode | null;
+  /**
+   * The network that serves the number today. Absent when no network could be identified.
+   */
+  readonly network_info?: LookupNetworkInfo | null;
+  /**
+   * The network that issued the number's range. It differs from `network_info` when the number has been ported. Absent when the issuing network could not be identified.
+   */
+  readonly original_network_info?: LookupNetworkInfo | null;
+  /**
+   * Notable characteristics of the number. Empty when none apply.
+   */
+  readonly flags: Array<LookupFlag$1>;
+  readonly line_type: LookupLineType;
+  /**
+   * The allocated service of the number's range. Absent unless you requested the `classification` property.
+   */
+  readonly classification?: LookupClassification;
+  /**
+   * Whether the number is live on its network. Absent unless you requested the `presence` property.
+   */
+  readonly presence?: LookupPresence;
+  /**
+   * Whether the number is roaming. Absent unless you requested the `roaming` property.
+   */
+  readonly roaming?: LookupRoaming;
+  /**
+   * When the number's SIM last changed. Absent unless you requested the `sim_swap` property.
+   */
+  readonly sim_swap?: LookupSimSwap;
+  /**
+   * The number's porting record. Absent unless you requested the `porting` property.
+   */
+  readonly porting?: LookupPorting;
+  /**
+   * The number's credibility score. Absent unless you requested the `score` property.
+   */
+  readonly score?: LookupScore;
+};
+/**
+ * A credibility score for the number. Returned when you request the `score` property.
+ */
+type LookupScore = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * Credibility from 0 (low) to 100 (high). A low score means the number looks less credible than a typical subscriber line in the same range; it is a signal to weigh, not a verdict. It is a composite and is not derivable from the other properties. Present only when `status` is `ok`.
+   *
+   */
+  readonly value?: number;
+};
+/**
+ * How a requested property resolved.
+ *
+ * `ok` means the property was answered and its value is in the response.
+ *
+ * `unavailable` means no answer arrived, so the property adds nothing: its block is null, or for `classification`, `line_type` is left as the free baseline resolved it. The property is not billed.
+ *
+ * `inconclusive` means an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the answer is one we cannot yet place. It is a real answer rather than a missing one, and it is not billed either.
+ *
+ * Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
+ *
+ */
+type LookupPropertyStatus$1 = "ok" | "unavailable" | "inconclusive" | (string & {});
+/**
+ * One recorded move of a number between networks.
+ */
+type LookupPortingEvent = {
+  /**
+   * When the move was recorded, null when the record carries no date.
+   */
+  readonly occurred_at: string | null;
+  /**
+   * What the record describes, as the number's registry reports it. Registries use their own short codes rather than a shared vocabulary, so treat this as a label to display rather than a value to branch on.
+   */
+  readonly action: string | null;
+};
+/**
+ * Whether the number has ever moved network, when it last did, and its full porting record. Returned when you request the `porting` property; the baseline only reports whether a number has ever ported, through the `ported` flag.
+ *
+ */
+type LookupPorting = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * Whether the number has ever moved network. False is a positive finding rather than a lack of one: the registry was consulted and holds no move for this number. Present only when `status` is `ok`.
+   *
+   */
+  readonly ported?: boolean;
+  /**
+   * When the number last moved network. Absent when it has never ported or when no date is on record.
+   */
+  readonly last_ported_at?: string | null;
+  /**
+   * Whether `last_ported_at` is an approximation. Some registries record only the period a move happened in, not the day.
+   */
+  readonly last_ported_at_is_approximate?: boolean;
+  /**
+   * Every move on record, oldest first. Absent when the number has never ported or when its registry publishes no history.
+   */
+  readonly history?: Array<LookupPortingEvent>;
+};
+/**
+ * When the number's SIM last changed. Returned when you request the `sim_swap` property.
+ */
+type LookupSimSwap = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * When the SIM was last changed. Absent when only a recency band is known.
+   */
+  readonly last_swapped_at?: string | null;
+  /**
+   * The lower bound, in days, of how long ago the SIM was last changed. Networks that do not release an exact date report a band instead; absent when no lower bound is known.
+   */
+  readonly min_days?: number | null;
+  /**
+   * The upper bound, in days, of how long ago the SIM was last changed. Absent when no upper bound is known; with a lower bound present, that means the change was at least `min_days` ago.
+   */
+  readonly max_days?: number | null;
+};
+/**
+ * Whether the number is roaming, and on which network. Returned when you request the `roaming` property.
+ */
+type LookupRoaming = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * Whether the number is currently roaming outside its home network. Present only when `status` is `ok`.
+   */
+  readonly is_roaming?: boolean;
+  /**
+   * The mobile country code of the visited network. Absent when the number is not roaming or the visited network is not reported.
+   */
+  readonly mcc?: string | null;
+  /**
+   * The mobile network code of the visited network. Absent when the number is not roaming or the visited network is not reported.
+   */
+  readonly mnc?: string | null;
+};
+/**
+ * Whether the number is live on its network right now. Returned when you request the `presence` property.
+ *
+ * This is the one property no database can answer: it is a real-time query to the network the number is registered on.
+ *
+ */
+type LookupPresence = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * Whether the number is registered on a network and able to receive traffic. False means the network answered and reported the number as not currently reachable, which is different from us being unable to find out. Present only when `status` is `ok`.
+   *
+   */
+  readonly reachable?: boolean;
+};
+/**
+ * The allocated service of the number's range, at the precision the intelligence source publishes it.
+ *
+ * This is a finer vocabulary than `line_type`, which reports what the carrier platform alone can tell. Eleven of these values have no carrier equivalent at all: a number the carrier can only call `service` may be `premium_rate`, `shared_cost`, `universal_access` or a voicemail platform, and those carry very different cost and fraud implications. Where the two fields do overlap, they are two independent opinions rather than one refining the other.
+ *
+ */
+type LookupClassificationValue = "mobile" | "fixed_line" | "fixed_line_or_mobile" | "voip" | "toll_free" | "premium_rate" | "shared_cost" | "local_rate" | "national_rate" | "personal_number" | "universal_access" | "satellite" | "pager" | "payphone" | "m2m" | "isp" | "vpn" | "voice_mail" | "calling_cards" | "short_codes" | "service" | "other";
+/**
+ * The allocated service of the number's range. Returned when you request the `classification` property.
+ *
+ * This sits beside `line_type` rather than replacing it, so you can always see which source answered: `line_type` is what the carrier platform reports and costs nothing, `classification` is what the intelligence source reports and is what you paid for.
+ *
+ */
+type LookupClassification = {
+  readonly status: LookupPropertyStatus$1;
+  /**
+   * The allocated service of the range. Present only when `status` is `ok`.
+   */
+  readonly value?: LookupClassificationValue;
+};
+/**
+ * What kind of line the number is, as reported by the carrier platform.
+ *
+ * This is part of the free baseline and is returned on every lookup, whatever you request. It never changes with what you buy. `unknown` means the carrier platform holds no classification for the range, and `other` means it holds one that has no equivalent here.
+ *
+ * For the allocated service of the range at finer precision, request the `classification` property. That answers from a different source, with its own wider vocabulary, and is reported separately so you can always tell the two apart.
+ *
+ */
+type LookupLineType = "mobile" | "fixed_line" | "voip" | "toll_free" | "premium_rate" | "satellite" | "pager" | "payphone" | "m2m" | "service" | "other" | "unknown";
+/**
+ * A notable characteristic of a number. `ported` means the number has moved from the network that issued it to another one, so `network_info` and `original_network_info` name different carriers.
+ *
+ * Open enum: more flags may be added over time, so treat an unrecognized value as a future flag rather than an error.
+ *
+ */
+type LookupFlag$1 = "ported" | (string & {});
+/**
+ * The network a number belongs to.
+ */
+type LookupNetworkInfo = {
+  /**
+   * The carrier's name, absent when the carrier could not be identified.
+   */
+  readonly carrier_name?: string | null;
+  /**
+   * The mobile country code, absent for a network that has none or could not be identified.
+   */
+  readonly mcc?: string | null;
+  /**
+   * The mobile network code, absent for a network that has none or could not be identified.
+   */
+  readonly mnc?: string | null;
+};
+/**
+ * ISO 3166-1 alpha-2 country code.
+ */
+type CountryCode = string;
+type PhoneNumberLookupRequest = {
+  /**
+   * The phone number to look up, in E.164 format, which is a leading `+`, the country calling code, then the national number.
+   */
+  phone_number: string;
+  /**
+   * The paid properties to enrich the answer with. Omit it, or send an empty array, to get the free baseline and make no vendor call.
+   *
+   * Each delivered property is billed on top of the lookup itself. A property that could not be answered is reported in `properties` and is not billed.
+   *
+   */
+  type?: Array<LookupProperty>;
+};
+/**
+ * An intelligence property you can buy for a number, beyond the free baseline.
+ *
+ * `classification` resolves `line_type` to its precise allocated service (premium rate, satellite, machine-to-machine, payphone) where the baseline only distinguishes broad categories. `porting` returns when the number last moved network and its full porting record. `presence` reports whether the number is live on the network right now. `roaming` reports whether it is roaming and on which network. `sim_swap` returns when its SIM last changed. `score` returns a credibility score from 0 to 100.
+ *
+ * Each property you request is billed separately, and only when it is delivered.
+ *
+ */
+type LookupProperty = "classification" | "porting" | "presence" | "roaming" | "sim_swap" | "score";
 /**
  * Bucket grain for a stats trend series.
  */
@@ -4673,30 +5072,30 @@ type SmsTemplateList = {
 };
 type SmsTemplateVersionId = string;
 /**
- * A single variable slot a template fills in from the values supplied when sending. Shared across channels (SMS, email) so template introspection reads the same everywhere.
+ * One variable a template's content uses, filled in from the values you give when you send. Templates on every channel report their variables this way, so this reads the same whether you are looking at an SMS template or an email one.
  *
  */
 type TemplateVariable = {
   /**
-   * The parameter key this slot is filled with.
+   * The variable's name, the key you use for it in `parameters` when you send.
    */
   readonly key: string;
   /**
-   * The value type this slot accepts. Open enum — treat any unrecognized value as a future type rather than an error. SMS templates use the typed slots (`code`, `amount`, …); email templates use `text`.
+   * The value type this variable accepts. We can add new types to this list over time, so treat a value you do not recognize as a new type rather than as an error. SMS templates use the typed values, such as `code` and `amount`. Email templates only use `text`.
    *
    */
   readonly type: string;
   /**
-   * Whether the slot must be supplied when sending. A send that leaves a required slot unset is rejected.
+   * Whether a value has to be supplied when sending. A send that leaves a required variable unset is rejected.
    *
    */
   readonly required: boolean;
   /**
-   * A human-readable description of the accepted values.
+   * A plain-language description of what values this variable accepts.
    */
   readonly constraint: string;
   /**
-   * Whether this slot's value is redacted before it reaches storage. A sensitive slot's rendered value never appears in message content read back through the API: a stand-in placeholder is stored instead.
+   * Whether this variable's value gets redacted before it is stored. When it does, the rendered value never appears in message content you read back through the API: a placeholder is stored in its place instead.
    *
    */
   readonly sensitive?: boolean;
@@ -4706,11 +5105,11 @@ type TemplateVariable = {
  */
 type SmsMessageCategory = "transactional" | "marketing" | "authentication" | "service";
 /**
- * Whether the template is a built-in Bird template (`system`) or one your workspace authored (`workspace`).
+ * Whether the template is one of our built-in templates (`system`) or one your workspace created (`workspace`).
  */
 type TemplateScope = "system" | "workspace";
 /**
- * A template's send-by handle — the stable reference used in place of the template id when sending. Lowercase letters, numbers, hyphens, and underscores; starts and ends with a letter or number.
+ * A template's name: the stable handle you send it by, used in place of the template id. It can contain lowercase letters, numbers, hyphens, and underscores, has to start and end with a letter or a number, and can be up to 63 characters long.
  *
  */
 type TemplateName = string;
@@ -4792,6 +5191,17 @@ type SmsBatchSummary = {
    */
   accepted_count: number;
 };
+/**
+ * The settings Bird applied to this message. Every option is reported, whether you set it on the send or took the default that was in force at the time.
+ *
+ */
+type SmsMessageEffectiveOptions = {
+  /**
+   * Whether Bird replaced characters outside the GSM-7 alphabet in this message's body with their closest equivalent before sending it. When `true`, `text` is the body as sent and `segments` describes that body.
+   *
+   */
+  smart_encoding: boolean;
+};
 /**
  * Delivery status. `accepted` (the initial status of an outbound send) means Bird accepted the request and it is awaiting handoff to the carrier network. `sent` means it was handed to the carrier and is awaiting a delivery receipt. `delivered` is confirmed delivery. `undelivered` is a non-permanent non-delivery (handset off or unreachable). `failed` is a terminal permanent failure. `rejected` means Bird refused it before it reached the carrier (for example insufficient balance). `expired` means the validity period elapsed without a terminal receipt. `scheduled` means the message is queued to send at a future time and has not been dispatched yet, and `canceled` means a scheduled message was canceled before it was sent. `received` applies to inbound messages.
  *
@@ -4845,6 +5255,11 @@ type SmsMessage = {
   metadata?: {
     [key: string]: unknown;
   };
+  /**
+   * Settings Bird applied to this message, with any option you omitted filled in with the default that was in force when you sent it. Absent on inbound messages, and on outbound messages sent before Bird began recording these settings.
+   *
+   */
+  readonly options?: SmsMessageEffectiveOptions;
   /**
    * How long, in seconds, Bird keeps trying to deliver before the message transitions to `expired`.
    */
@@ -4901,6 +5316,29 @@ type SmsTemplateSend = unknown & {
     [key: string]: unknown;
   };
 };
+/**
+ * Settings that change how Bird processes this message. Each option applies to this send only; omit one to use its default.
+ *
+ */
+type SmsSendOptions = {
+  /**
+   * Replace characters outside the GSM-7 alphabet with their closest GSM-7 equivalent before sending: typically curly quotes, dashes, ellipses, fullwidth forms, and non-breaking spaces.
+   *
+   * One such character forces the whole body into `UCS2`, which more than halves the characters that fit in a segment, so replacing them often lowers the segment count and the cost.
+   *
+   * Disabled by default, because it alters the body you composed. The replacement is all-or-nothing: a body that still holds a character outside the alphabet afterwards, such as an emoji or a non-Latin script, is sent exactly as you supplied it. Read the message back to see what was applied: `text` is the body as sent.
+   *
+   */
+  smart_encoding?: boolean;
+  /**
+   * Preview feature: link click tracking. Defaults to `false`. Currently unavailable; setting this to `true` returns `422 SMSUnsupportedFeature`.
+   */
+  track_clicks?: boolean;
+  /**
+   * Preview feature: per-segment price ceiling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
+   */
+  max_price_per_segment?: number;
+};
 type SmsMessageSendRequest = unknown & {
   /**
    * Recipient phone number in E.164 format (for example `+15551234567`). One recipient per message.
@@ -4938,6 +5376,11 @@ type SmsMessageSendRequest = unknown & {
   metadata?: {
     [key: string]: unknown;
   };
+  /**
+   * 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.
+   *
+   */
+  options?: SmsSendOptions;
   /**
    * Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
    */
@@ -4975,20 +5418,12 @@ type SmsMessageSendRequest = unknown & {
    * Preview feature: topic-gated sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
    */
   topic_id?: string;
-  /**
-   * Preview feature: per-segment price ceiling. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
-   */
-  max_price_per_segment?: number;
   /**
    * Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
    */
   personalization?: {
     [key: string]: unknown;
   };
-  /**
-   * Preview feature: link click tracking. Defaults to `false`. Currently unavailable; setting this to `true` returns `422 SMSUnsupportedFeature`.
-   */
-  track_clicks?: boolean;
 };
 /**
  * Whether a message was sent from the workspace (`outbound`) or received by it (`inbound`).
@@ -4996,13 +5431,13 @@ type SmsMessageSendRequest = unknown & {
 type MessageDirection = "outbound" | "inbound";
 type AudienceContactsRemoveRequest = {
   /**
-   * 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.
+   * 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.
    */
   contact_ids: Array<ContactId>;
 };
 type AudienceContactsAddRequest = {
   /**
-   * 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.
+   * 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.
    */
   contact_ids: Array<ContactId>;
 };
@@ -5032,7 +5467,7 @@ type Contact = {
   /**
    * The contact's phone number in normalized international form (a leading `+` and four to 15 digits), which may differ from the form it was supplied in. Bird normalizes formatting but does not verify the number against numbering-plan metadata. Unique within the workspace. Carriers recycle disconnected numbers, so a long-stored number can come to belong to someone else; `external_id` is the durable key for your own records. Null when the contact has no phone number.
    */
-  phone: string | null;
+  phone_number: string | null;
   /**
    * The contact's first name. Available in broadcast templates as `bird.contact.first_name`.
    */
@@ -5070,7 +5505,7 @@ type AudienceMember = {
 };
 type AudienceUpdateRequest = {
   /**
-   * 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.
+   * 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.
    */
   name?: string;
   /**
@@ -5088,10 +5523,9 @@ type AudienceCreateRequest = {
    */
   description?: string;
   /**
-   * How the audience's recipients are determined. `static` (the default) is an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable; creating an audience with either returns a validation error.
-   *
+   * How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts.
    */
-  type?: "static" | "dynamic" | "external";
+  type?: "static";
 };
 type ContactPropertyUpdateRequest = {
   /**
@@ -5151,10 +5585,9 @@ type Audience = {
    */
   description?: string | null;
   /**
-   * How the audience's recipients are determined. `static` (the default) is an explicit member list you manage via the API. `dynamic` and `external` are preview values and currently unavailable; creating an audience with either returns a validation error.
-   *
+   * How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts.
    */
-  type: "static" | "dynamic" | "external";
+  type: "static";
 } & Timestamps;
 type ContactUpdateRequest = {
   /**
@@ -5164,7 +5597,7 @@ type ContactUpdateRequest = {
   /**
    * 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.
    */
-  phone?: string | null;
+  phone_number?: string | null;
   /**
    * The contact's first name. Set to null to clear.
    */
@@ -5208,7 +5641,7 @@ type ContactUpsertError = {
 /**
  * Which identifier matched a batch entry to an existing contact. Null when the entry created a new contact.
  */
-type ContactMatchedOn = "email" | "phone" | "external_id" | null;
+type ContactMatchedOn = "email" | "phone_number" | "external_id" | null;
 /**
  * The identifiers a batch entry supplied, in the normalized form they were matched with, null where the entry carried none. An echo of the request row for correlation, never the contact's current state.
  */
@@ -5220,7 +5653,7 @@ type ContactUpsertEntry = {
   /**
    * Phone number this entry carried, in its normalized international form. Null when the entry carried none. A row rejected for an invalid phone echoes the value as sent, trimmed, since no normalized form exists.
    */
-  phone: string | null;
+  phone_number: string | null;
   /**
    * Your own identifier for this entry, when the entry supplied one.
    */
@@ -5268,7 +5701,7 @@ type ContactUpsertRequest = {
 /**
  * A contact identifier a batch entry can be matched on.
  */
-type ContactMatchKey = "email" | "phone" | "external_id";
+type ContactMatchKey = "email" | "phone_number" | "external_id";
 type ContactCreateRequest = {
   /**
    * 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.
@@ -5277,7 +5710,7 @@ type ContactCreateRequest = {
   /**
    * 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.
    */
-  phone?: string;
+  phone_number?: string;
   /**
    * The contact's first name.
    */
@@ -5299,9 +5732,9 @@ type ContactCreateRequest = {
   };
 };
 /**
- * Which identifier a contact has on file, `email` for an email address or `phone` for a phone number.
+ * Which identifier a contact has on file, `email` for an email address or `phone_number` for a phone number.
  */
-type ContactIdentifierFilter = "email" | "phone";
+type ContactIdentifierFilter = "email" | "phone_number";
 type EmailMessageBatchResponse = {
   /**
    * One entry per message in the batch, in submission order.
@@ -5328,7 +5761,7 @@ type EmailMessageBatchItem = {
    */
   readonly requested_language?: LanguageTag | null;
   /**
-   * The template language this item was actually delivered in, in canonical form. Null when the item used no template. A value here differing from `requested_language` means the template did not carry the language asked for and its `on_missing_language` policy chose this one.
+   * The template language this item was actually delivered in, in canonical form. Null when the item used no template. A value here differing from `requested_language` means the template did not have the language asked for and its `on_missing_language` policy chose this one.
    *
    */
   readonly resolved_language?: LanguageTag | null;
@@ -5358,12 +5791,16 @@ type EmailTemplateSend = unknown & {
    */
   slug?: TemplateSlug;
   /**
-   * Which of the template's languages to send. Omit it to send the template's default language, unless the template sets `language_source_required`, in which case a send naming no language is rejected. When the template does not carry the language you ask for, its own `on_missing_language` setting decides whether the closest available language is sent instead or the send is rejected.
+   * Which of the template's languages to send. Omit it to send the template's default language, unless the template sets `language_source_required`, in which case a send naming no language is rejected. When the template does not have the language you ask for, its own `on_missing_language` setting decides whether the closest available language is sent instead or the send is rejected.
    *
    */
   language?: LanguageTag;
   /**
-   * Values for the template's parameters, keyed by parameter name. A parameter name is a single word, and every parameter the template's `variables` lists needs a value here: a send that omits one is rejected rather than delivered with a blank. Send everything `variables` lists rather than only what you expect the chosen language to use, since languages need not reference the same parameters and a value no language uses is ignored. Cap: 16 KB serialized.
+   * Values for the template's variables, keyed by the variable name. A variable name is a single word.
+   *
+   * Every variable the template's `variables` lists needs a value here. A send that leaves one out is rejected rather than delivered with a blank in it. Send values for everything in that list rather than only what you expect the language you are sending to use, because languages do not have to use the same variables and a value no language uses is simply ignored.
+   *
+   * `bird` is reserved for the values we fill in ourselves, so a send that sets it is rejected. `parameters` is capped at 16 KB once serialized.
    *
    */
   parameters?: {
@@ -5372,23 +5809,23 @@ type EmailTemplateSend = unknown & {
 };
 type EmailMessageSendRequest = {
   /**
-   * Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name. Must be from a verified domain in this workspace.
+   * Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name. Must be from a verified domain in this workspace.
    */
   from: EmailAddressInput;
   /**
-   * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   to: Array<EmailAddressInput>;
   /**
-   * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   cc?: Array<EmailAddressInput>;
   /**
-   * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+   * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@acme.com>`), or an object with an optional display name.
    */
   bcc?: Array<EmailAddressInput>;
   /**
-   * Message subject line. Required for inline sends; omit it when sending a `template` (the template supplies the subject).
+   * Message subject line. Required for inline sends. Omit it when sending a `template` (the template supplies the subject).
    */
   subject?: string;
   /**
@@ -5400,24 +5837,30 @@ type EmailMessageSendRequest = {
    */
   text?: string;
   /**
-   * 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 runaway header sizes that some MTAs reject.
+   * 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.
    *
    */
   reply_to?: Array<EmailAddressInput>;
   /**
-   * Custom email headers as key-value pairs (for example `References`, `In-Reply-To`, or your own `X-*` headers). Reserved headers are rejected with a `422`: set the message's addressing and subject through the dedicated fields (`from`, `to`, `cc`, `bcc`, `reply_to`, `subject`) rather than here, and headers the platform generates for you — `Content-Type`, `Content-Transfer-Encoding`, `DKIM-Signature`, `Received`, and `Return-Path` — cannot be overridden. `List-Unsubscribe` and `List-Unsubscribe-Post` are honored as-is on `transactional` sends; on `marketing` sends the platform sets a compliant unsubscribe header for you, so supplying them there is rejected with a `422`. Header values may not contain carriage-return or line-feed characters.
+   * Custom email headers as key-value pairs (for example `References`, `In-Reply-To`, or your own `X-*` headers). Reserved headers are rejected with a `422`. Set the message's addressing and subject through the dedicated fields (`from`, `to`, `cc`, `bcc`, `reply_to`, `subject`) rather than here, and the headers generated for you automatically (`Content-Type`, `Content-Transfer-Encoding`, `DKIM-Signature`, `Received`, and `Return-Path`) cannot be overridden. `List-Unsubscribe` and `List-Unsubscribe-Post` are honored as-is on `transactional` sends. On a `marketing` send a compliant unsubscribe header is set for you, so supplying either one there is rejected with a `422`. Header values may not contain carriage-return or line-feed characters. Up to 25 headers per send, each value up to 998 characters.
    *
    */
   headers?: {
     [key: string]: string;
   };
   /**
-   * Structured `{name, value}` labels for **filtering and analytics**. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics rollups by tag, and surface in webhook payloads. Cap: 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`, `template_id`). For arbitrary structured context that you do not need as a filter dimension, use `metadata` instead.
+   * Structured `{name, value}` labels for **filtering and analytics**. Tags become first-class query dimensions:
+   *
+   * - Filter the list endpoint by tag name.
+   * - Slice analytics rollups by tag.
+   * - Surface in webhook payloads.
+   *
+   * Cap: 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`, `template_id`). For arbitrary structured context that you do not need as a filter dimension, use `metadata` instead.
    *
    */
   tags?: Array<Tag>;
   /**
-   * Arbitrary JSON object **stored, returned on API reads, and echoed in webhook payloads**. Path-queryable in analytics (e.g. filter on `metadata.order_id`) but not surfaced as a first-class dashboard filter dimension. Cap: 2 KB serialized. Use metadata for per-send context like internal IDs, foreign keys, and structured payloads you want round-tripped through events. For low-cardinality filterable labels, use `tags` instead.
+   * Arbitrary JSON object **stored, returned on API reads, and echoed in webhook payloads**. Path-queryable in analytics (for example, filter on `metadata.order_id`) but not surfaced as a first-class dashboard filter dimension. Cap: 2 KB serialized. Use metadata for per-send context like internal IDs, foreign keys, and structured payloads you want round-tripped through events. For low-cardinality filterable labels, use `tags` instead.
    *
    */
   metadata?: {
@@ -5431,7 +5874,7 @@ type EmailMessageSendRequest = {
     [key: string]: unknown;
   };
   /**
-   * Send a stored template instead of inline content. When set, omit `subject`/`html`/`text` — the template supplies them; personalize with `template.parameters`.
+   * Send a stored template instead of inline content. When set, omit `subject`, `html` and `text`, because the template supplies them. Personalize with `template.parameters`. A template send goes out immediately: `template` and `scheduled_at` are mutually exclusive, and combining them is rejected with a `422`.
    *
    */
   template?: EmailTemplateSend;
@@ -5449,37 +5892,29 @@ type EmailMessageSendRequest = {
    */
   ip_pool_id?: string;
   /**
-   * Content classification. 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. When you send with `template` and omit this field, the message takes the template's own classification, so a template created as `transactional` sends as transactional. Set this field to classify a single send differently from its template; it always takes precedence. Sends that carry no template and no category are `marketing`.
+   * 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.
+   *
+   * When you send with `template` and omit this field, the message takes the template's own classification, so a template created as `transactional` sends as transactional. Set this field to classify a single send differently from its template. It always takes precedence. A send with no template and no category defaults to `marketing`.
    *
    */
   category?: EmailMessageCategory;
   /**
-   * Preview feature — threaded replies. Currently unavailable; supplying this field returns `422 UnsupportedEmailFeature`. When generally available, sets In-Reply-To and References headers automatically.
-   */
-  in_reply_to_message_id?: EmailId;
-  /**
-   * File attachments. Bird rejects sends whose estimated generated message size exceeds 20 MB. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. Keep total raw attachment content at or below 15 MB for reliable headroom. In batch sends, this per-message cap still applies and the serialized JSON request body for the whole batch has a hard 20 MB cap. See the EmailAttachment schema for the full field contract.
+   * Files to attach, up to 20 per message. A message can be at most 20 MB once it has been generated, and we refuse a send that would go over. That figure covers the HTML body, the text body and every attachment and inline image, all measured after base64 encoding, which adds roughly a third. So 15 MB of raw files already accounts for most of the budget, and the body competes for the same space. A batch send is held to the same 20 MB per message, and the whole request body is capped at 20 MB as well.
    *
    */
   attachments?: Array<EmailAttachment>;
   /**
-   * Schedule the message to send at a future time instead of immediately. Must be at least 30 seconds and at most 30 days ahead — outside that range the request is rejected with `422`. The message returns with status `accepted` and shows as `scheduled` on reads until it sends; cancel it before then with the message cancel endpoint. Scheduled sends count against your plan's monthly scheduled-email allowance; exceeding it is rejected with a `422`.
+   * Schedule the message to send at a future time instead of immediately. Must be at least 30 seconds and at most 30 days ahead. Outside that range the request is rejected with `422`. The message returns with status `accepted` and shows as `scheduled` on reads until it sends. Cancel it before then with the message cancel endpoint. Scheduled sends count against your plan's monthly scheduled-email allowance. Exceeding it is rejected with a `422`. A scheduled message has inline content: `scheduled_at` and `template` are mutually exclusive, and combining them is rejected with a `422`. This field is only accepted on a single send, not on a batch item.
    *
    */
   scheduled_at?: string;
-  /**
-   * Preview feature — contact-targeted sends. Currently unavailable; supplying this field returns `422 UnsupportedEmailFeature`.
-   */
-  contact_id?: string;
-  /**
-   * Preview feature — topic-gated sends. Currently unavailable; supplying this field returns `422 UnsupportedEmailFeature`. When generally available, a non-empty `topic_id` gates delivery on the recipient's opt-in state for that topic — if the recipient is opt_out, the send is silently suppressed and an `email.suppressed` event fires with `reason: topic_opt_out`.
-   *
-   */
-  topic_id?: string;
 };
 type EmailAttachmentId = string;
 /**
- * Attachment metadata returned on API reads. The original content is not echoed back inline — only the metadata needed for display and audit. To download the raw attachment bytes (while content storage is enabled and within the retention window), use `GET /v1/email/messages/{message_id}/attachments/{attachment_id}`, which returns the file with its own content type and a Content-Disposition filename.
+ * Attachment metadata returned on API reads. The original content is not sent back inline, only the metadata you need to display and audit it. To download the raw attachment bytes (while content storage is enabled and within the retention window), use `GET /v1/email/messages/{message_id}/attachments/{attachment_id}`, which returns the file with its own content type and a Content-Disposition filename.
  *
  */
 type EmailAttachmentRef = {
@@ -5512,19 +5947,20 @@ type EmailAttachmentRef = {
 /**
  * Aggregate delivery status of an email, derived from its recipients' states.
  *
- * In flight: `scheduled` means the message is queued to send at a future time and has
- * not been dispatched yet; `accepted` (the initial status of an immediate send) means
- * Bird has queued the message for its recipients; `processed` means delivery is underway
- * (at least one recipient has been handed to the delivery pipeline and none has failed);
- * `deferred` means at least one recipient's mailbox provider asked Bird to retry and
- * delivery attempts continue.
+ * In flight:
  *
- * Final: `delivered` means every recipient's mail server accepted the message; `bounced`
- * means every recipient permanently failed (bounced or was rejected); `rejected` means
- * every recipient was rejected before a delivery attempt (for example, all recipients
- * suppressed); `partial_failure` means some recipients permanently failed while others
- * were delivered or are still in flight; `canceled` means a scheduled message was
- * canceled before it was sent.
+ * - `scheduled`: The message is queued to send at a future time and has not been dispatched yet.
+ * - `accepted`: The initial status of an immediate send. The message is queued for its recipients.
+ * - `processed`: Delivery is underway, so at least one recipient's message is on its way out and none has failed.
+ * - `deferred`: At least one recipient's mailbox provider asked for a retry, and delivery attempts continue.
+ *
+ * Final:
+ *
+ * - `delivered`: Every recipient's mail server accepted the message.
+ * - `bounced`: Every recipient permanently failed (bounced or was rejected).
+ * - `rejected`: Every recipient was rejected before a delivery attempt (for example, all recipients were suppressed).
+ * - `partial_failure`: Some recipients permanently failed while others were delivered or are still in flight.
+ * - `canceled`: A scheduled message was canceled before it was sent.
  *
  * `complained` takes precedence over every other status: at least one recipient reported
  * the message as spam, regardless of what happened to the rest.
@@ -5541,7 +5977,7 @@ type EmailMessage = {
    */
   from: EmailAddress;
   /**
-   * Primary recipients. Length is the recipient count; use the broadcasts endpoint for audience-targeted sends. Each entry's `name` is present when a display name was provided on the send.
+   * Primary recipients. Length is the recipient count. Use the broadcasts endpoint for audience-targeted sends. Each entry's `name` is present when a display name was provided on the send.
    */
   to: Array<EmailAddress>;
   /**
@@ -5562,21 +5998,17 @@ type EmailMessage = {
    * Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
    */
   reply_to?: Array<EmailAddress> | null;
-  /**
-   * Aggregate delivery status derived from recipient states. `scheduled` means the message is queued to send at a future time and has not been dispatched yet. `accepted` means Bird has the send and is preparing to deliver. `processed` means Bird has processed the message and queued it for delivery to the recipient's mail server. `canceled` means a scheduled message was canceled before it was sent.
-   *
-   */
   readonly status: EmailMessageStatus;
   /**
-   * Number of recipients currently in the `accepted` state — Bird has the send and is preparing to deliver.
+   * How many recipients are in the `accepted` state, meaning we have the message and are getting ready to deliver it.
    */
   readonly accepted_count: number;
   /**
-   * Number of recipients for whom Bird has processed the message and queued it for delivery.
+   * How many recipients the message has been prepared for and queued for delivery.
    */
   readonly processed_count: number;
   /**
-   * Number of recipients whose messages were accepted by the remote MTA.
+   * How many recipients' messages were accepted by their mail server.
    */
   readonly delivered_count: number;
   /**
@@ -5588,16 +6020,16 @@ type EmailMessage = {
    */
   readonly complained_count: number;
   /**
-   * Number of recipients in transient delivery deferral; the provider is retrying.
+   * Number of recipients in transient delivery deferral. Their mail server asked for a retry, and delivery attempts continue.
    */
   readonly deferred_count: number;
   /**
-   * Number of recipients rejected before delivery. See the per-recipient `rejection_reason` field on `GET /v1/email/messages/{message_id}/recipients` for the specific cause (suppression match, transmission failure, generation failure, or policy refusal).
+   * Number of recipients rejected before delivery. Read the per-recipient `rejection_reason` field on `GET /v1/email/messages/{message_id}/recipients` for the specific cause.
    *
    */
   readonly rejected_count: number;
   /**
-   * Time between Bird accepting the send and the message being processed for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches `processed`.
+   * Time between the send being accepted and the message being prepared for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches `processed`.
    *
    */
   readonly processing_latency_ms?: number | null;
@@ -5640,11 +6072,11 @@ type EmailMessage = {
    */
   readonly template_version_id?: EmailTemplateVersionId | null;
   /**
-   * Structured `{name, value}` filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.
+   * Labels on this message, each one a `name` and a `value`, that you can filter and search messages by. Use tags for anything you want to find messages by later, and `metadata` for data you only want handed back to you.
    */
   tags?: Array<Tag>;
   /**
-   * Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.
+   * Any JSON you kept on the message. We store it and hand it back in webhook payloads, and that is all it does. If you want to search or filter by it, use `tags` instead.
    */
   metadata?: {
     [key: string]: unknown;
@@ -5657,7 +6089,7 @@ type EmailMessage = {
     [key: string]: unknown;
   } | null;
   /**
-   * Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed; when content storage is enabled, download an attachment by its `id` via the message's attachment endpoint.
+   * Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed. When content storage is enabled, download an attachment by its `id` via the message's attachment endpoint.
    */
   attachments?: Array<EmailAttachmentRef>;
   /**
@@ -5673,7 +6105,7 @@ type EmailMessage = {
    */
   readonly created_at: string;
   /**
-   * Thread this message belongs to. Null until threading is enabled.
+   * Thread this message belongs to, or null when the message is not part of one.
    */
   readonly thread_id?: string | null;
   /**
@@ -5835,15 +6267,16 @@ type PublishRealtimeAppEventData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -5865,15 +6298,16 @@ type PublishRealtimeAppBatchData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -5947,15 +6381,16 @@ type SendRealtimeAppMemberEventData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6002,7 +6437,7 @@ type ListEmailMessagesData = {
      */
     status?: EmailMessageStatus;
     /**
-     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
+     * Filter by tag. Accepts `name` to match any message 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 message must match every tag listed to be returned.
      *
      */
     tag?: Array<string>;
@@ -6011,12 +6446,12 @@ type ListEmailMessagesData = {
      */
     category?: EmailMessageCategory;
     /**
-     * Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message; normalised to lowercase before comparison.
+     * Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message. The address is normalized to lowercase before comparison.
      *
      */
     to?: string;
     /**
-     * Filter by sender address. Exact match against the message `from` field; normalised to lowercase before comparison.
+     * Filter by sender address. Exact match against the message `from` field. The address is normalized to lowercase before comparison.
      *
      */
     from?: string;
@@ -6034,7 +6469,7 @@ type ListContactsData = {
     /**
      * Return the contact with exactly this phone number in international E.164 form. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so this 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.
      */
-    phone?: string;
+    phone_number?: string;
     /**
      * 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.
      */
@@ -6070,15 +6505,16 @@ type CreateContactData = {
   body: ContactCreateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6091,15 +6527,16 @@ type CreateContactBatchData = {
   body: ContactUpsertRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6112,15 +6549,16 @@ type UpdateContactData = {
   body: ContactUpdateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6157,15 +6595,16 @@ type CreateContactPropertyData = {
   body: ContactPropertyCreateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6178,15 +6617,16 @@ type UpdateContactPropertyData = {
   body: ContactPropertyUpdateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6227,15 +6667,16 @@ type CreateAudienceData = {
   body: AudienceCreateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6248,15 +6689,16 @@ type UpdateAudienceData = {
   body: AudienceUpdateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6302,15 +6744,16 @@ type AssignAudienceContactsData = {
   body: AudienceContactsAddRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6328,15 +6771,16 @@ type UnassignAudienceContactsData = {
   body: AudienceContactsRemoveRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6401,7 +6845,7 @@ type ListSmsMessagesData = {
      */
     from?: string;
     /**
-     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
+     * Filter by tag. Accepts `name` to match any message 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 message must match every tag listed to be returned.
      *
      */
     tag?: Array<string>;
@@ -6429,6 +6873,58 @@ type ListSmsTemplatesData = {
   };
   url: "/v1/sms/templates";
 };
+type CreatePhoneNumberLookupData = {
+  body: PhoneNumberLookupRequest;
+  headers?: {
+    /**
+     * Workspace context. Required for session auth; derived from API key otherwise.
+     */
+    "X-Workspace-Id"?: string;
+    /**
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
+     * Two distinct 409 errors signal misuse:
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
+     * against a different request body or method. Generate a new key.
+     *
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
+     *
+     */
+    "Idempotency-Key"?: string;
+  };
+  path?: never;
+  query?: never;
+  url: "/v1/lookup/phone-number";
+};
+type CreateEmailLookupData = {
+  body: EmailLookupRequest;
+  headers?: {
+    /**
+     * Workspace context. Required for session auth; derived from API key otherwise.
+     */
+    "X-Workspace-Id"?: string;
+    /**
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
+     * Two distinct 409 errors signal misuse:
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
+     * against a different request body or method. Generate a new key.
+     *
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
+     *
+     */
+    "Idempotency-Key"?: string;
+  };
+  path?: never;
+  query?: never;
+  url: "/v1/lookup/email";
+};
 type CreateVerificationData = {
   body: VerificationCreateRequest;
   headers?: {
@@ -6437,15 +6933,16 @@ type CreateVerificationData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6462,15 +6959,16 @@ type CreateVerificationCheckData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6487,15 +6985,16 @@ type CreateVerificationNextChannelData = {
      */
     "X-Workspace-Id"?: string;
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -6550,7 +7049,7 @@ type ListWhatsAppMessagesData = {
      */
     category?: WhatsAppTemplateCategory$1;
     /**
-     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
+     * Filter by tag. Accepts `name` to match any message 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 message must match every tag listed to be returned.
      *
      */
     tag?: Array<string>;
@@ -6677,7 +7176,7 @@ type GetEmailStatsByTagData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6690,11 +7189,11 @@ type GetEmailStatsByTagData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * 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`.
+     * 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`.
      *
      */
     sort?: EmailStatsSortMetric;
@@ -6703,7 +7202,7 @@ type GetEmailStatsByTagData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that row's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * 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.
      *
      */
     include_trend?: boolean;
@@ -6775,7 +7274,7 @@ type GetEmailStatsBySendingIpData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6788,11 +7287,11 @@ type GetEmailStatsBySendingIpData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * Metric to rank IPs by, applied descending. `bounces.block` surfaces the IPs whose reputation is most likely degraded. Rows whose rate is undefined (zero denominator) sort last. Defaults to `delivered`. Engagement metrics (a sending IP carries no engagement), `processed`, `rejected`, and `oob_bounces` are not sortable here.
+     * 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`.
      *
      */
     sort?: "delivered" | "bounced" | "complained" | "deferred" | "bounces.hard" | "bounces.soft" | "bounces.admin" | "bounces.block" | "bounces.undetermined" | "delivery_rate" | "bounce_rate" | "complaint_rate" | "bounces.hard_rate" | "bounces.soft_rate" | "bounces.admin_rate" | "bounces.block_rate" | "bounces.undetermined_rate";
@@ -6801,7 +7300,7 @@ type GetEmailStatsBySendingIpData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that IP's delivery rates over the window (per-IP rows have no engagement, so each trend point's open and click rates read 0 in buckets that had deliveries and null in buckets that had none). 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * 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.
      *
      */
     include_trend?: boolean;
@@ -6817,7 +7316,7 @@ type GetEmailStatsBySendingDomainData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6830,11 +7329,11 @@ type GetEmailStatsBySendingDomainData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * 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`.
+     * 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`.
      *
      */
     sort?: EmailStatsSortMetric;
@@ -6843,7 +7342,7 @@ type GetEmailStatsBySendingDomainData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that row's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * When true, each row also gets a `trend` array: a short per-bucket series showing that domain'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.
      *
      */
     include_trend?: boolean;
@@ -6859,7 +7358,7 @@ type GetEmailStatsByCategoryData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6872,7 +7371,7 @@ type GetEmailStatsByCategoryData = {
      */
     timezone?: string;
     /**
-     * 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`.
+     * 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`.
      *
      */
     sort?: EmailStatsSortMetric;
@@ -6881,7 +7380,7 @@ type GetEmailStatsByCategoryData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that category's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * 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.
      *
      */
     include_trend?: boolean;
@@ -6897,7 +7396,7 @@ type GetEmailStatsByMailboxProviderData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6914,7 +7413,7 @@ type GetEmailStatsByMailboxProviderData = {
      */
     category?: string;
     /**
-     * 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 `delivered`. `processed`, `rejected`, and `oob_bounces` are not part of this breakdown's rows, so they are not sortable here.
+     * 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 `delivered`. `processed`, `rejected`, and `oob_bounces` are not part of this breakdown's rows, so they are not sortable here.
      *
      */
     sort?: EmailMailboxProviderSortMetric;
@@ -6923,7 +7422,7 @@ type GetEmailStatsByMailboxProviderData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that provider's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * When true, each row also gets a `trend` array: a short per-bucket series showing that provider'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.
      *
      */
     include_trend?: boolean;
@@ -6939,7 +7438,7 @@ type GetEmailStatsByMailboxProviderRegionData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6952,11 +7451,11 @@ type GetEmailStatsByMailboxProviderRegionData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * 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 `delivered`. `processed`, `rejected`, and `oob_bounces` are not part of this breakdown's rows, so they are not sortable here.
+     * 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 `delivered`. `processed`, `rejected`, and `oob_bounces` are not part of this breakdown's rows, so they are not sortable here.
      *
      */
     sort?: EmailMailboxProviderSortMetric;
@@ -6965,7 +7464,7 @@ type GetEmailStatsByMailboxProviderRegionData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that provider region's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * When true, each row also gets a `trend` array: a short per-bucket series showing that provider region'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.
      *
      */
     include_trend?: boolean;
@@ -6981,7 +7480,7 @@ type GetEmailStatsByRecipientDomainData = {
   path?: never;
   query?: {
     /**
-     * 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 29 days before `to`, keeping the defaulted window within the 720-hour trend cap.
+     * 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.
      */
     from?: string;
     /**
@@ -6994,11 +7493,11 @@ type GetEmailStatsByRecipientDomainData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * 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`.
+     * 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`.
      *
      */
     sort?: EmailStatsSortMetric;
@@ -7007,7 +7506,7 @@ type GetEmailStatsByRecipientDomainData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that recipient domain's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * When true, each row also gets a `trend` array: a short per-bucket series showing that recipient domain'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.
      *
      */
     include_trend?: boolean;
@@ -7049,7 +7548,7 @@ type GetEmailStatsByTemplateData = {
      */
     limit?: number;
     /**
-     * When true, each row also carries a `trend` array: a short per-bucket series of that template's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default window is 30 days (720 hours), so a request built entirely from defaults always fits the cap.
+     * When true, each row also has a `trend` array: a short per-bucket series of that template's delivery and engagement rates 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. When `from` is omitted and `trend_grain=hourly`, the default start tightens to 29 days before `to`, keeping the window inside 720 hours, so a request built entirely from defaults always fits the cap.
      *
      */
     include_trend?: boolean;
@@ -7087,7 +7586,7 @@ type GetEmailStatsByLocationData = {
      */
     group_by?: "country" | "region" | "city";
     /**
-     * Metric to rank rows by, applied descending. Defaults to `unique_opens`. Only engagement counts are sortable; this breakdown has no rates.
+     * Metric to rank rows by, applied descending. It defaults to `unique_opens`. Only engagement counts are sortable. This breakdown has no rates.
      *
      */
     sort?: EmailEngagementSortMetric;
@@ -7125,7 +7624,7 @@ type GetEmailStatsByClientData = {
      */
     group_by?: "email_client" | "os" | "device_type";
     /**
-     * Metric to rank rows by, applied descending. Defaults to `unique_opens`. Only engagement counts are sortable; this breakdown has no rates.
+     * Metric to rank rows by, applied descending. It defaults to `unique_opens`. Only engagement counts are sortable. This breakdown has no rates.
      *
      */
     sort?: EmailEngagementSortMetric;
@@ -7154,11 +7653,11 @@ type GetEmailStatsByBounceCodeData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * Metric to rank rows by, applied descending. Defaults to `bounced`. Only bounce counts are sortable; this breakdown has no rates.
+     * 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.
      *
      */
     sort?: "bounced" | "bounces.hard" | "bounces.soft" | "bounces.admin" | "bounces.block" | "bounces.undetermined";
@@ -7187,11 +7686,11 @@ type GetEmailStatsByComplaintTypeData = {
      */
     timezone?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
-     * Metric to rank rows by, applied descending. Defaults to `complained`, the only sortable metric for this breakdown.
+     * Metric to rank rows by, applied descending. It defaults to `complained`, the only sortable metric for this breakdown.
      *
      */
     sort?: "complained";
@@ -7215,7 +7714,7 @@ type GetEmailStatsByBroadcastData = {
      */
     to?: string;
     /**
-     * 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.
+     * 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.
      */
     category?: string;
     /**
@@ -7270,15 +7769,16 @@ type CreateDomainData = {
   body: DomainCreate;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7291,15 +7791,16 @@ type UpdateDomainData = {
   body: DomainUpdate;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7334,7 +7835,7 @@ type ListMailboxesData = {
      */
     domain?: string;
     /**
-     * Include mailboxes deleted within their 30-day restore window. Defaults to false, so only active and suspended mailboxes are returned. Deleted mailboxes carry a non-null `deleted_at`.
+     * Include mailboxes deleted within their 30-day restore window. Defaults to false, so only active and suspended mailboxes are returned. A deleted mailbox has a non-null `deleted_at`.
      */
     include_deleted?: boolean;
     /**
@@ -7356,15 +7857,16 @@ type CreateMailboxData = {
   body: MailboxCreate;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7377,15 +7879,16 @@ type UpdateMailboxData = {
   body: MailboxUpdate;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7398,7 +7901,7 @@ type UpdateMailboxData = {
   };
   query?: {
     /**
-     * Required as `true` when lowering `retention_tier`, acknowledging that remembered messages older than the new horizon are deleted.
+     * Set to `true` when lowering `retention_tier` would delete remembered messages older than the new cutoff. The request is rejected without it in that case.
      */
     confirm?: boolean;
   };
@@ -7429,7 +7932,7 @@ type GetMailboxStatsData = {
      */
     timezone?: string;
     /**
-     * Bucket grain of the series: `day` (default) or `hour`. Echoed back as `period.grain`.
+     * Granularity of the series: `day` (default) or `hour`. Echoed back as `period.grain`.
      *
      */
     granularity?: "day" | "hour";
@@ -7468,15 +7971,16 @@ type CreateMailboxReceiveRuleData = {
   body: ReceiveRuleCreate;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7503,15 +8007,17 @@ type ListEmailThreadsData = {
      */
     contact_id?: ContactId;
     /**
-     * Filter to conversations carrying this label. Repeat the parameter to require several — only conversations carrying every listed label match. A placement label selects a folder (`inbox`, `archive`, `spam`, `blocked`); a custom label matches conversations in any folder. Defaults to `inbox` when omitted.
+     * Filter to conversations that have this label. Repeat the parameter to ask for more than one: only conversations that have every label you list are returned.
+     *
+     * A placement label picks a folder: `inbox`, `archive`, `spam`, or `blocked`. A custom label matches a conversation in any folder. Leave this out and you get the inbox.
      */
     label?: Array<string>;
     /**
-     * When `true`, only conversations with unread messages are returned. This filters on the conversation's unread state, so it combines with `label` — for example, unread conversations in the archive. (The `unread` label itself lives on messages, not conversations.)
+     * When `true`, only conversations with unread messages are returned. This filters on the conversation's unread state, so you can combine it with `label`, for example to get unread conversations in the archive. The `unread` label itself lives on messages, not conversations.
      */
     has_unread?: boolean;
     /**
-     * Conversations involving this address — matches the sender or any recipient, as a case-insensitive contains-match, so a full address or any fragment of one works.
+     * 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.
      */
     participant?: string;
     /**
@@ -7545,15 +8051,16 @@ type DeleteEmailThreadData = {
   body?: never;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7576,15 +8083,16 @@ type UpdateEmailThreadData = {
   body: EmailThreadUpdateRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -7612,7 +8120,7 @@ type ListEmailThreadMessagesData = {
      */
     direction?: MessageDirection;
     /**
-     * Filter to messages carrying this label. `trash` lists trashed messages; any other label — `archive`, `spam`, `blocked`, `unread`, or a custom label — lists its non-trashed carriers. When omitted, received messages in the inbox and all sent messages are returned.
+     * 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.
      *
      */
     label?: string;
@@ -7639,15 +8147,16 @@ type ReplyEmailThreadMessageData = {
   body: EmailThreadMessageReplyRequest;
   headers?: {
     /**
-     * Client-supplied deduplication key. When present, the server replays the original response for any duplicate request with the same key within the idempotency TTL window (3 hours by default).
+     * Client-supplied deduplication key. When present, the original response is replayed for any duplicate request with the same key, within the idempotency window (3 hours by default).
+     *
      * Two distinct 409 errors signal misuse:
-     * - `request_in_progress` (E01004): the same key is currently being
-     * processed by a concurrent request. Wait briefly and retry; the lock
-     * expires within 30 seconds.
-     * - `idempotency_key_reuse` (E01005): the same key has already completed
+     *
+     * - `request_in_progress` (E01004): The same key is currently being
+     * processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
+     * - `idempotency_key_reuse` (E01005): The same key has already completed
      * against a different request body or method. Generate a new key.
      *
-     * Recommended key format is `<event-type>/<entity-id>` (e.g. `welcome-user/usr_abc123`).
+     * Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
      *
      */
     "Idempotency-Key"?: string;
@@ -8060,7 +8569,7 @@ declare abstract class Resource {
 type EmailListQuery$1 = NonNullable<ListEmailMessagesData["query"]>;
 declare class EmailResourceBase extends Resource {
   /**
-   * Fetch one email message by id, with aggregate delivery status and per-state recipient counts. The message body (html, text) is not returned. Per-recipient delivery statuses and the event log are separate sub-resources: GET /v1/email/messages/{message_id}/recipients and GET /v1/email/messages/{message_id}/events.
+   * Fetch one email message by `id`, with aggregate delivery status and per-state recipient counts. The message body (`html`, `text`) is not returned. Per-recipient delivery statuses and the event log are separate sub-resources: `GET /v1/email/messages/{message_id}/recipients` and `GET /v1/email/messages/{message_id}/events`.
    *
    * @example
    * const msg = await bird.email.get("em_abc123");
@@ -8070,7 +8579,7 @@ declare class EmailResourceBase extends Resource {
    */
   get(messageId: string, options?: RequestOptions): APIPromise<EmailMessage>;
   /**
-   * List sent email messages, newest first, as a cursor page ({data, next_cursor, …}). Pass next_cursor back as starting_after to fetch the next page. Filter by creation time with the half-open range created_after (inclusive) / created_before (exclusive). For a single UTC day, created_after is that day at 00:00:00Z and created_before is the next day at 00:00:00Z.
+   * List sent email messages, newest first, as a cursor page (`{data, next_cursor, …}`). Pass `next_cursor` back as `starting_after` to fetch the next page. Filter by creation time with the half-open range `created_after` (inclusive) and `created_before` (exclusive). For a single UTC day, `created_after` is that day at 00:00:00Z and `created_before` is the next day at 00:00:00Z.
    *
    * @example
    * for await (const message of bird.email.list({ status: "bounced" })) {
@@ -8079,7 +8588,7 @@ declare class EmailResourceBase extends Resource {
    */
   list(query?: EmailListQuery$1, options?: RequestOptions): PaginatedPromise<EmailMessage>;
   /**
-   * Cancel a scheduled email before it sends. Only works while the message is still scheduled (status `scheduled`); once it starts sending, or was already canceled, the call returns a conflict error. Canceling does not return consumed scheduled-send quota.
+   * 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.
    *
    * @example
    * await bird.email.cancel("em_abc123");
@@ -8106,7 +8615,7 @@ type EmailStatsByComplaintTypeQuery = NonNullable<GetEmailStatsByComplaintTypeDa
 type EmailStatsByBroadcastQuery = NonNullable<GetEmailStatsByBroadcastData["query"]>;
 declare class EmailStatsResource extends Resource {
   /**
-   * Aggregate email KPIs for one period: sends, delivered, bounces, complaints, opens, clicks, their rates, and latency percentiles. `from`/`to` are both YYYY-MM-DD days or both RFC 3339 instants (hour grain); add `compare=previous_period` for deltas versus the prior window. For a per-day or per-hour series use email_stats_daily or email_stats_hourly.
+   * Aggregate email KPIs for one period: sends, delivered, bounces, complaints, opens, clicks, their rates, and latency percentiles. `from`/`to` are both YYYY-MM-DD days or both RFC 3339 instants (hour grain); add `compare=previous_period` for deltas versus the prior window. For a per-day or per-hour series use `email.stats.daily` or `email.stats.hourly`.
    *
    * @example Summary for a month
    * const s = await bird.email.stats.summary({ from: "2026-05-01", to: "2026-05-31" });
@@ -8114,7 +8623,7 @@ declare class EmailStatsResource extends Resource {
    */
   summary(query?: EmailStatsSummaryQuery, options?: RequestOptions): APIPromise<EmailStatsSummary>;
   /**
-   * Per-day email stats series (counts, rates, latency percentiles), gap-filled with zero rows, max 365 days. At most one filter of `category`, `sending_domain`, `tag`, `sending_ip`, `recipient_domain`, `template`. For hour resolution use email_stats_hourly; for one aggregate row use email_stats_summary.
+   * Per-day email stats series (counts, rates, latency percentiles), gap-filled with zero rows, max 365 days. At most one filter of `category`, `sending_domain`, `tag`, `sending_ip`, `recipient_domain`, `template`. For hour resolution use `email.stats.hourly`; for one aggregate row use `email.stats.summary`.
    *
    * @example
    * const series = await bird.email.stats.daily({ from: "2026-05-01", to: "2026-05-31" });
@@ -8122,7 +8631,7 @@ declare class EmailStatsResource extends Resource {
    */
   daily(query?: EmailStatsDailyQuery, options?: RequestOptions): APIPromise<EmailStatsResponse>;
   /**
-   * Per-hour email stats series, gap-filled with zero rows, max 720 hours (30 days). Takes the same single-dimension filters as email_stats_daily; for longer ranges use email_stats_daily, for one aggregate row use email_stats_summary.
+   * Per-hour email stats series, gap-filled with zero rows, max 720 hours (30 days). Takes the same single-dimension filters as `email.stats.daily`; for longer ranges use `email.stats.daily`, for one aggregate row use `email.stats.summary`.
    *
    * @example
    * const series = await bird.email.stats.hourly({ from: "2026-05-01", to: "2026-05-02" });
@@ -8130,7 +8639,7 @@ declare class EmailStatsResource extends Resource {
    */
   hourly(query?: EmailStatsHourlyQuery, options?: RequestOptions): APIPromise<EmailStatsResponse>;
   /**
-   * Email delivery and engagement stats grouped by tag, one row per `name:value` pair set at send time; ranked by `sort` (default `processed`). `include_trend=true` adds a per-bucket rate series to each row.
+   * Email delivery and engagement stats grouped by tag, one row per `name:value` pair set at send time. Rows are ranked by `sort`, `processed` by default. Set `include_trend=true` to add a per-bucket rate series to each row.
    *
    * @example Top 10 tags by delivered
    * const { data } = await bird.email.stats.byTag({
@@ -8143,7 +8652,7 @@ declare class EmailStatsResource extends Resource {
    */
   byTag(query?: EmailStatsByTagQuery, options?: RequestOptions): APIPromise<EmailStatsTagsResponse>;
   /**
-   * Email delivery and engagement stats grouped by category (`transactional` versus `marketing`), ranked by `sort` (default `processed`). `include_trend=true` adds a per-bucket rate series to each row.
+   * Email delivery and engagement stats grouped by category, meaning `transactional` compared with `marketing`. Rows are ranked by `sort`, `processed` by default. Set `include_trend=true` to add a per-bucket rate series to each row.
    *
    * @example
    * const { data } = await bird.email.stats.byCategory({ from: "2026-05-01", to: "2026-05-31" });
@@ -8151,7 +8660,7 @@ declare class EmailStatsResource extends Resource {
    */
   byCategory(query?: EmailStatsByCategoryQuery, options?: RequestOptions): APIPromise<EmailStatsByCategoryResponse>;
   /**
-   * Delivery and bounce stats grouped by sending IP; `sort=bounces.block` surfaces reputation-damaged IPs first. No engagement, complaint, or accepted/processed counts per IP; use email_stats_daily for workspace-wide figures.
+   * Delivery and bounce stats grouped by sending IP, with deferral counts alongside them. `sort=bounces.block` surfaces reputation-damaged IPs first. Engagement, accepted, and processed counts aren't available per IP, and complaint and out-of-band bounce counts always read 0 here. For workspace-wide figures, use `email.stats.daily`.
    *
    * @example
    * const { data } = await bird.email.stats.bySendingIp({
@@ -8164,7 +8673,7 @@ declare class EmailStatsResource extends Resource {
    */
   bySendingIp(query?: EmailStatsBySendingIpQuery, options?: RequestOptions): APIPromise<EmailStatsBySendingIpResponse>;
   /**
-   * Email delivery and engagement stats grouped by sending (`From`) domain; compare deliverability across the workspace's verified domains. For per-IP reputation use email_stats_by_sending_ip.
+   * Email delivery and engagement stats grouped by sending (`From`) domain, so you can compare deliverability across your workspace's verified domains. For per-IP reputation instead, use `email.stats.by_sending_ip`.
    *
    * @example
    * const { data } = await bird.email.stats.bySendingDomain({
@@ -8177,7 +8686,7 @@ declare class EmailStatsResource extends Resource {
    */
   bySendingDomain(query?: EmailStatsBySendingDomainQuery, options?: RequestOptions): APIPromise<EmailStatsBySendingDomainResponse>;
   /**
-   * Email delivery and engagement stats grouped by exact recipient mailbox domain (for example `gmail.com`). Finer-grained than email_stats_by_mailbox_provider, which buckets domains into providers.
+   * Email delivery and engagement stats grouped by exact recipient mailbox domain, for example `gmail.com`. Finer-grained than `email.stats.by_mailbox_provider`, which buckets domains into providers.
    *
    * @example
    * const { data } = await bird.email.stats.byRecipientDomain({
@@ -8190,7 +8699,7 @@ declare class EmailStatsResource extends Resource {
    */
   byRecipientDomain(query?: EmailStatsByRecipientDomainQuery, options?: RequestOptions): APIPromise<EmailStatsByRecipientDomainResponse>;
   /**
-   * Email delivery and engagement stats grouped by recipient mailbox provider (`gmail`, `microsoft`, `yahoo`, ...); covers the delivery stage onward, no accepted/processed counts. For a per-region split use email_stats_by_mailbox_provider_region; for exact destination domains use email_stats_by_recipient_domain.
+   * Email delivery and engagement stats grouped by recipient mailbox provider, for example `gmail`, `microsoft`, or `yahoo`. It covers the delivery stage onward, so there are no accepted or processed counts. For a per-region split within a provider, use `email.stats.by_mailbox_provider_region`; for exact destination domains instead, use `email.stats.by_recipient_domain`.
    *
    * @example
    * const { data } = await bird.email.stats.byMailboxProvider({
@@ -8202,7 +8711,7 @@ declare class EmailStatsResource extends Resource {
    */
   byMailboxProvider(query?: EmailStatsByMailboxProviderQuery, options?: RequestOptions): APIPromise<EmailStatsByMailboxProviderResponse>;
   /**
-   * Email delivery and engagement stats grouped by mailbox provider and provider region pair (for example `gmail` in `NA`); covers the delivery stage onward, no accepted/processed counts. For the provider-level view use email_stats_by_mailbox_provider.
+   * Email delivery and engagement stats grouped by a mailbox provider and provider region pair, for example `gmail` in `NA`. It covers the delivery stage onward, so there are no accepted or processed counts. For the provider-level view without the region split, use `email.stats.by_mailbox_provider`.
    *
    * @example
    * const { data } = await bird.email.stats.byMailboxProviderRegion({
@@ -8214,7 +8723,7 @@ declare class EmailStatsResource extends Resource {
    */
   byMailboxProviderRegion(query?: EmailStatsByMailboxProviderRegionQuery, options?: RequestOptions): APIPromise<EmailStatsByMailboxProviderRegionResponse>;
   /**
-   * Email delivery and engagement stats grouped by the template used at send time, keyed by template id (`emt_…`); only templated sends appear. A single template's trend over time comes from email_stats_daily with its `template` filter.
+   * Email delivery and engagement stats grouped by the template used at send time, keyed by template id (`emt_…`); only templated sends appear. A single template's trend over time comes from `email.stats.daily` with its `template` filter.
    *
    * @example
    * const { data } = await bird.email.stats.byTemplate({
@@ -8227,7 +8736,7 @@ declare class EmailStatsResource extends Resource {
    */
   byTemplate(query?: EmailStatsByTemplateQuery, options?: RequestOptions): APIPromise<EmailStatsByTemplateResponse>;
   /**
-   * Opens and clicks grouped by country, region, or city (`group_by`); engagement counts only, no delivery counts or rates. For engagement by mail client or device use email_stats_by_client.
+   * Opens and clicks grouped by country, region, or city, whichever you choose with `group_by`. It only has engagement counts, no delivery counts or rates. For engagement grouped by mail client or device instead, use `email.stats.by_client`.
    *
    * @example
    * const { data } = await bird.email.stats.byLocation({
@@ -8239,7 +8748,7 @@ declare class EmailStatsResource extends Resource {
    */
   byLocation(query?: EmailStatsByLocationQuery, options?: RequestOptions): APIPromise<EmailStatsByLocationResponse>;
   /**
-   * Opens and clicks grouped by mail client, OS, or device type (`group_by`); engagement counts only, no delivery counts or rates. For engagement by geography use email_stats_by_location.
+   * Opens and clicks grouped by mail client, operating system, or device type, whichever you choose with `group_by`. It only has engagement counts, no delivery counts or rates. For engagement grouped by geography instead, use `email.stats.by_location`.
    *
    * @example
    * const { data } = await bird.email.stats.byClient({
@@ -8251,7 +8760,7 @@ declare class EmailStatsResource extends Resource {
    */
   byClient(query?: EmailStatsByClientQuery, options?: RequestOptions): APIPromise<EmailStatsByClientResponse>;
   /**
-   * Bounce counts grouped by the SMTP error code the receiving server returned, with the hard/soft/admin/block/undetermined split; failure side only. It shows what is driving bounces, while bounces by destination come from email_stats_by_recipient_domain or email_stats_by_mailbox_provider.
+   * Bounce counts grouped by the SMTP error code the receiving mail server returned. Each row also breaks the bounce down into its hard, soft, admin, block, and undetermined split. There are no delivered, open, or click counts here, because a bounce code only appears on a bounce event. For bounces broken down by destination instead, use `email.stats.by_recipient_domain` or `email.stats.by_mailbox_provider`.
    *
    * @example
    * const { data } = await bird.email.stats.byBounceCode({
@@ -8264,7 +8773,7 @@ declare class EmailStatsResource extends Resource {
    */
   byBounceCode(query?: EmailStatsByBounceCodeQuery, options?: RequestOptions): APIPromise<EmailStatsByBounceCodeResponse>;
   /**
-   * Spam-complaint counts grouped by the feedback-loop complaint type (for example `abuse`, `fraud`, `virus`); complaint side only. For complaints by destination use email_stats_by_mailbox_provider or email_stats_by_recipient_domain.
+   * Spam-complaint counts grouped by the feedback-loop complaint type, for example `abuse`, `fraud`, or `virus`. Complaint side only, so there are no delivery or engagement counts. For complaints broken down by destination instead, use `email.stats.by_mailbox_provider` or `email.stats.by_recipient_domain`.
    *
    * @example
    * const { data } = await bird.email.stats.byComplaintType({ from: "2026-05-01", to: "2026-05-31" });
@@ -8272,7 +8781,7 @@ declare class EmailStatsResource extends Resource {
    */
   byComplaintType(query?: EmailStatsByComplaintTypeQuery, options?: RequestOptions): APIPromise<EmailStatsByComplaintTypeResponse>;
   /**
-   * Email delivery and engagement stats grouped by broadcast; only broadcast sends appear. Reflects roughly the last 30 days of activity.
+   * Email delivery and engagement stats grouped by broadcast. Only broadcast sends appear. Reflects roughly the last 30 days of activity.
    *
    * @example
    * const { data } = await bird.email.stats.byBroadcast({
@@ -8303,7 +8812,7 @@ declare class EmailMailboxesResourceBase extends Resource {
    */
   list(query?: EmailMailboxesListQuery, options?: RequestOptions): PaginatedPromise<Mailbox>;
   /**
-   * Create a mailbox: a durable agent identity that owns an email address, groups mail into threads, and remembers conversations for its retention tier.
+   * Create a mailbox: a durable agent identity that owns an email address, groups mail into conversations, and remembers conversations for its retention tier.
    *
    * @example Create a mailbox
    * const mailbox = await bird.email.mailboxes.create({ display_name: "Support" });
@@ -8311,7 +8820,7 @@ declare class EmailMailboxesResourceBase extends Resource {
    */
   create(params?: EmailMailboxesCreateParams, options?: RequestOptions): APIPromise<Mailbox>;
   /**
-   * Read one mailbox by id. A mailbox deleted within its 30-day restore window is still returned, carrying a non-null `deleted_at`; once that window closes it is gone and this returns 404.
+   * Read one mailbox by ID. A mailbox deleted within its 30-day restore window is still returned, with a non-null `deleted_at`. Once that window closes it is gone and this returns 404.
    *
    * @example Get a mailbox
    * const mailbox = await bird.email.mailboxes.get("mbx_01abc");
@@ -8319,7 +8828,7 @@ declare class EmailMailboxesResourceBase extends Resource {
    */
   get(mailboxId: string, options?: RequestOptions): APIPromise<Mailbox>;
   /**
-   * Update a mailbox's display name, reply-to, receive policy, retention tier, IP pool, or metadata. Lowering the retention tier onto remembered messages older than the new horizon requires confirm=true.
+   * Update a mailbox's display name, reply-to, receive policy, retention tier, IP pool, or metadata. Lowering the retention tier requires `confirm=true` when it would delete remembered messages older than the new cutoff.
    *
    * @example Change a mailbox's receive policy
    * const mailbox = await bird.email.mailboxes.update("mbx_01abc", {
@@ -8329,14 +8838,14 @@ declare class EmailMailboxesResourceBase extends Resource {
    */
   update(mailboxId: string, params?: EmailMailboxesUpdateParams, query?: EmailMailboxesUpdateQuery, options?: RequestOptions): APIPromise<Mailbox>;
   /**
-   * Delete a mailbox. The address stops receiving immediately and is quarantined; the mailbox and its remembered messages stay restorable for 30 days via the restore endpoint, then are permanently deleted.
+   * Delete a mailbox. The address stops receiving immediately and is quarantined. The mailbox and its remembered messages stay restorable for 30 days through the restore endpoint, then are permanently deleted.
    *
    * @example Delete a mailbox
    * await bird.email.mailboxes.delete("mbx_01abc");
    */
   delete(mailboxId: string, options?: RequestOptions): APIPromise<void>;
   /**
-   * Restore a mailbox deleted less than 30 days ago: the address starts receiving again and the remembered messages are back. Past the window the mailbox is permanently deleted and returns 404; a mailbox that is not deleted returns 409.
+   * Restore a mailbox deleted less than 30 days ago: the address starts receiving again and the remembered messages are back. Past the window the mailbox is permanently deleted and returns 404. A mailbox that is not deleted returns 409.
    *
    * @example Restore a deleted mailbox
    * const mailbox = await bird.email.mailboxes.restore("mbx_01abc");
@@ -8344,7 +8853,7 @@ declare class EmailMailboxesResourceBase extends Resource {
    */
   restore(mailboxId: string, options?: RequestOptions): APIPromise<Mailbox>;
   /**
-   * Reactivate a suspended mailbox so it can send and receive again and its threads become visible. Fails if your plan does not have room for another active mailbox (or another custom inbox.ai handle); delete an active mailbox or upgrade first. A mailbox that is not suspended returns 409.
+   * Resume a suspended mailbox so it can send and receive again and its conversations become visible. Fails if your plan does not have room for another active mailbox (or another custom inbox.ai handle). Delete an active mailbox or upgrade first. A mailbox that is not suspended returns 409.
    *
    * @example Resume a suspended mailbox
    * const mailbox = await bird.email.mailboxes.resume("mbx_01abc");
@@ -8400,7 +8909,7 @@ declare class EmailMailboxesReceiveRulesResource extends Resource {
    */
   list(mailboxId: string, query?: EmailMailboxesReceiveRulesListQuery, options?: RequestOptions): PaginatedPromise<ReceiveRule>;
   /**
-   * Add an allow or block rule for a sender address or domain to a mailbox. Block always wins; up to 200 rules per mailbox.
+   * Add an allow or block rule for a sender address or domain to a mailbox. Block always wins. Up to 200 rules per mailbox.
    *
    * @example Block a domain
    * const rule = await bird.email.mailboxes.receiveRules.create("mbx_01abc", {
@@ -8474,7 +8983,7 @@ type EmailThreadsMessagesListQuery = NonNullable<ListEmailThreadMessagesData["qu
 type EmailThreadsMessagesReplyParams = NonNullable<ReplyEmailThreadMessageData["body"]>;
 declare class EmailThreadsMessagesResource extends Resource {
   /**
-   * List the messages in a conversation newest first, both directions. Page older messages with starting_after, and pass include=extracted_text to inline each message's durable plain text.
+   * List the messages in a conversation newest first, both directions. Page older messages with starting_after, and pass include=extracted_text to inline each message's extracted plain text.
    *
    * @example List a thread's messages
    * for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
@@ -8483,7 +8992,7 @@ declare class EmailThreadsMessagesResource extends Resource {
    */
   list(threadId: string, query?: EmailThreadsMessagesListQuery, options?: RequestOptions): PaginatedPromise<EmailThreadMessage>;
   /**
-   * Get one conversation message with its extracted plain text, readable for the mailbox's full retention period without MIME parsing.
+   * Get one conversation message with its extracted plain text, readable for the mailbox's full retention tier without MIME parsing.
    *
    * @example Get a message
    * const msg = await bird.email.threads.messages.get("thr_01abc", "rem_01xyz");
@@ -8491,7 +9000,7 @@ declare class EmailThreadsMessagesResource extends Resource {
    */
   get(threadId: string, messageId: string, options?: RequestOptions): APIPromise<EmailThreadMessage>;
   /**
-   * Get the original rendered HTML and plain-text body of a conversation message. Available 30 days; after that use the message's extracted_text.
+   * Get the original rendered HTML and plain-text body of a conversation message. Available for 30 days. After that, use the message's extracted_text.
    *
    * @example Get a message body
    * const body = await bird.email.threads.messages.body("thr_01abc", "rem_01xyz");
@@ -8509,7 +9018,7 @@ declare class EmailThreadsMessagesResource extends Resource {
    */
   reply(threadId: string, messageId: string, params?: EmailThreadsMessagesReplyParams, options?: RequestOptions): APIPromise<EmailThreadMessage>;
   /**
-   * List the attachments on a conversation message. Bytes are downloadable for 30 days; the metadata also rides the message's attachment_manifest durably.
+   * List the attachments on a conversation message. Bytes are downloadable for 30 days, and the metadata stays readable afterward on the message's attachment_manifest.
    *
    * @example List a message's attachments
    * const atts = await bird.email.threads.messages.attachments("thr_01abc", "rem_01xyz");
@@ -8700,7 +9209,7 @@ declare class AudiencesResource extends Resource {
    */
   listContacts(audienceId: string, query?: AudienceListContactsQuery, options?: RequestOptions): PaginatedPromise<AudienceMember>;
   /**
-   * Add up to 1,000 existing contacts to a static audience by ID. Fails entirely if any contact ID does not exist.
+   * 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.
    *
    * @example Add contacts to an audience
    * await bird.audiences.addContacts("adn_01krdgeqcxet5s7t44vh8rt9mg", {
@@ -8768,7 +9277,7 @@ declare class DomainsResource extends Resource {
    */
   verify(domainId: string, options?: RequestOptions): APIPromise<Domain>;
   /**
-   * Update a sending domain's tracking and inbound configuration. Tracking: click_tracking and open_tracking apply immediately to new sends, and the tracking domain can be set, changed, or removed (the name part only; Bird appends the sending domain). Enabling either toggle with no tracking domain configured returns 409, and removing the tracking domain while either toggle is still on also returns 409. Tracking-domain changes on a verified domain are staged behind DNS verification, so the current config keeps serving until the new records verify. Inbound receiving: inbound.enabled starts or stops receiving mail for the domain. Enabling requires the domain's DKIM to be verified first (a fresh enable on an unverified domain returns 422), and a domain already receiving inbound for another organization returns 422. The MX records to publish are always listed in dns_records regardless, so receiving starts only once inbound.enabled is set, even when those records are already published.
+   * Update a sending domain's tracking and inbound configuration. Tracking: click_tracking and open_tracking apply immediately to new sends, and the tracking domain can be set, changed, or removed (the name part only, and the sending domain is appended for you). Enabling either toggle with no tracking domain configured returns 409, and removing the tracking domain while either toggle is still on also returns 409. Tracking-domain changes on a verified domain are staged behind DNS verification, so the current config keeps serving until the new records verify. Inbound receiving: inbound.enabled starts or stops receiving mail for the domain. Enabling requires the domain's DKIM to be verified first (a fresh enable on an unverified domain returns 422), and a domain already receiving inbound for another organization returns 422. The MX records to publish are always listed in dns_records regardless, so receiving starts only once inbound.enabled is set, even when those records are already published.
    *
    * @example Enable tracking on a domain
    * await bird.domains.update("dom_01krdgeqcxet5s7t44vh8rt9mg", {
@@ -8848,7 +9357,7 @@ type ContactUpdateParams = NonNullable<UpdateContactData["body"]>;
 type ContactBatchParams = NonNullable<CreateContactBatchData["body"]>;
 declare class ContactsResource extends Resource {
   /**
-   * List the workspace's contacts as a cursor page, newest first. Look one up by exact email, phone, or external_id, or search by email, name, or phone substring. Pass include_total for a total count.
+   * List the workspace's contacts as a cursor page, newest first. Look one up by exact email, phone_number, or external_id, or search by email, name, or phone substring. Pass include_total for a total count.
    *
    * @example Iterate every contact, or take one page
    * for await (const contact of bird.contacts.list({ q: "acme.com" })) {
@@ -8858,7 +9367,7 @@ declare class ContactsResource extends Resource {
    */
   list(query?: ContactListQuery, options?: RequestOptions): PaginatedPromise<Contact>;
   /**
-   * Get a single contact by ID (`con_`-prefixed). Look up an ID by exact email, phone, or external_id with `contacts.list`.
+   * Get a single contact by ID (`con_`-prefixed). Look up an ID by exact email, phone_number, or external_id with `contacts.list`.
    *
    * @example Fetch a contact by id
    * const contact = await bird.contacts.get("con_01krdgeqcxet5s7t44vh8rt9mg");
@@ -8866,7 +9375,7 @@ declare class ContactsResource extends Resource {
    */
   get(contactId: string, options?: RequestOptions): APIPromise<Contact>;
   /**
-   * Create a contact identified by an email address, an E.164 phone number, or both. Fails with a conflict if the email, phone, or external_id is already used by another contact. For bulk import or create-or-update semantics use `contacts.batch`.
+   * 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`.
    *
    * @example Create a contact
    * const contact = await bird.contacts.create({
@@ -8877,7 +9386,7 @@ declare class ContactsResource extends Resource {
    */
   create(params?: ContactCreateParams, options?: RequestOptions): APIPromise<Contact>;
   /**
-   * Update a contact's name, external_id, email, phone, or custom data. Only supplied fields change; custom data keys are merged, with null removing a key. A contact keeps at least one identifier: clearing both email and phone is rejected.
+   * Update a contact's name, external_id, email, phone_number, or custom data. Only supplied fields change; custom data keys are merged, with null removing a key. A contact keeps at least one identifier: clearing both email and phone_number is rejected.
    *
    * @example Change a contact's fields
    * const contact = await bird.contacts.update("con_01krdgeqcxet5s7t44vh8rt9mg", {
@@ -8894,7 +9403,7 @@ declare class ContactsResource extends Resource {
    */
   delete(contactId: string, options?: RequestOptions): APIPromise<void>;
   /**
-   * Create or update up to 1,000 contacts in one request, each entry matched automatically against every identifier it supplies (email, phone, external_id) or, with match_on, by that one field only, and optionally add them all to one or more audiences. Per-contact results are returned in submission order.
+   * Create or update up to 1,000 contacts in one request, each entry matched automatically against every identifier it supplies (email, phone_number, external_id) or, with match_on, by that one field only, and optionally add them all to one or more audiences. Per-contact results are returned in submission order.
    *
    * @example Create or update many contacts at once, matched by the identifiers each entry carries
    * const result = await bird.contacts.batch({
@@ -9268,6 +9777,34 @@ declare class RealtimeResource extends RealtimeResourceBase {
   constructor(core: ConstructorParameters<typeof Resource>[0], client: ConstructorParameters<typeof Resource>[1]);
 }
 //#endregion
+//#region src/resources/lookup.gen.d.ts
+type LookupPhoneNumberParams = NonNullable<CreatePhoneNumberLookupData["body"]>;
+type LookupEmailParams = NonNullable<CreateEmailLookupData["body"]>;
+declare class LookupResource extends Resource {
+  /**
+   * Look up what a phone number is. Returns the serving network, the issuing network, whether the number was ported, its country, and its line type, free with every call. Pass `type` to buy extra blocks: `classification` (the allocated service of the range, from an intelligence source, reported beside the free `line_type` rather than replacing it), `porting` (whether the number ever moved network, when, and its full history), `presence` (reachable on the network right now), `roaming`, `sim_swap` (when the SIM last changed), and `score` (0-100 credibility). Every requested block reports its own status, and only the ones reading `ok` are billed on top of the lookup. Nothing is sent to the number.
+   *
+   * @example Look up a number, buying two extra blocks
+   * const answer = await bird.lookup.phoneNumber({
+   *   phone_number: "+31612345678",
+   *   type: ["classification", "score"],
+   * });
+   * console.log(answer.country_code, answer.line_type);
+   * // Only a block whose status is ok carries a value, and only that one is billed.
+   * if (answer.score?.status === "ok") console.log(answer.score.value);
+   */
+  phoneNumber(params: LookupPhoneNumberParams, options?: RequestOptions): APIPromise<PhoneNumberLookup>;
+  /**
+   * Look up whether an email address is worth sending to. Returns `result` (the verdict: `valid`; `neutral`, meaning it could not be confirmed either way; `risky`, meaning it will probably accept mail but is likelier than most to bounce or complain; `undeliverable`; or `typo`), `delivery_confidence` (0-100), `flags` (`role`, `disposable`, `free_provider`), `reason` on an undeliverable address (`invalid_syntax`, `invalid_domain`, `invalid_recipient`), and `did_you_mean` when the address looks like a misspelling of a real one. `result` and `reason` are OPEN vocabularies: the values listed here are today's and more may be added, so treat an unrecognized value as a future one rather than an error, falling back on `delivery_confidence`. One address per call. Every answered lookup is billed the same flat amount whatever the verdict, so treat it as a paid call rather than a free check, and use an `Idempotency-Key` so a retry does not buy a second answer. Nothing is sent to the address.
+   *
+   * @example Check whether an address is worth sending to
+   * const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
+   * // result is an open vocabulary; delivery_confidence is always comparable.
+   * console.log(answer.result, answer.delivery_confidence);
+   */
+  email(params: LookupEmailParams, options?: RequestOptions): APIPromise<EmailLookup>;
+}
+//#endregion
 //#region src/client.d.ts
 interface BirdClientOptions {
   apiKey: string;
@@ -9366,6 +9903,8 @@ declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions>
   readonly contactProperties: ContactPropertiesResource;
   /** Sending domains — `bird.domains.create(...)`, `.list(...)`, `.verify(...)`, … */
   readonly domains: DomainsResource;
+  /** Recipient intelligence — `bird.lookup.email(...)`, `.phoneNumber(...)`. Every answer is billed. */
+  readonly lookup: LookupResource;
   /** Webhooks — `bird.webhooks.unwrap(payload, headers)` verifies an inbound delivery. */
   readonly webhooks: WebhooksResource;
   /** Realtime — `bird.realtime.publish(...)`, `.channels.list(...)`, `.members.disconnect(...)`, … */
@@ -9473,6 +10012,66 @@ declare const EmailEventType: {
 };
 /** A known EmailEventType value. */
 type EmailEventTypeValue = (typeof EmailEventType)[keyof typeof EmailEventType];
+/**
+ * Values of EmailLookupFlag known at this SDK version. The wire value is an open
+ * string: a value added by a newer server deserializes unchanged, so switch on
+ * these with a `default` branch rather than treating the set as closed.
+ */
+declare const EmailLookupFlag: {
+  readonly Disposable: "disposable";
+  readonly FreeProvider: "free_provider";
+  readonly Role: "role";
+};
+/** A known EmailLookupFlag value. */
+type EmailLookupFlagValue = (typeof EmailLookupFlag)[keyof typeof EmailLookupFlag];
+/**
+ * Values of EmailLookupReason known at this SDK version. The wire value is an open
+ * string: a value added by a newer server deserializes unchanged, so switch on
+ * these with a `default` branch rather than treating the set as closed.
+ */
+declare const EmailLookupReason: {
+  readonly InvalidDomain: "invalid_domain";
+  readonly InvalidRecipient: "invalid_recipient";
+  readonly InvalidSyntax: "invalid_syntax";
+};
+/** A known EmailLookupReason value. */
+type EmailLookupReasonValue = (typeof EmailLookupReason)[keyof typeof EmailLookupReason];
+/**
+ * Values of EmailLookupResult known at this SDK version. The wire value is an open
+ * string: a value added by a newer server deserializes unchanged, so switch on
+ * these with a `default` branch rather than treating the set as closed.
+ */
+declare const EmailLookupResult: {
+  readonly Neutral: "neutral";
+  readonly Risky: "risky";
+  readonly Typo: "typo";
+  readonly Undeliverable: "undeliverable";
+  readonly Valid: "valid";
+};
+/** A known EmailLookupResult value. */
+type EmailLookupResultValue = (typeof EmailLookupResult)[keyof typeof EmailLookupResult];
+/**
+ * Values of LookupFlag known at this SDK version. The wire value is an open
+ * string: a value added by a newer server deserializes unchanged, so switch on
+ * these with a `default` branch rather than treating the set as closed.
+ */
+declare const LookupFlag: {
+  readonly Ported: "ported";
+};
+/** A known LookupFlag value. */
+type LookupFlagValue = (typeof LookupFlag)[keyof typeof LookupFlag];
+/**
+ * Values of LookupPropertyStatus known at this SDK version. The wire value is an open
+ * string: a value added by a newer server deserializes unchanged, so switch on
+ * these with a `default` branch rather than treating the set as closed.
+ */
+declare const LookupPropertyStatus: {
+  readonly Inconclusive: "inconclusive";
+  readonly Ok: "ok";
+  readonly Unavailable: "unavailable";
+};
+/** A known LookupPropertyStatus value. */
+type LookupPropertyStatusValue = (typeof LookupPropertyStatus)[keyof typeof LookupPropertyStatus];
 /**
  * Values of SMSErrorCode known at this SDK version. The wire value is an open
  * string: a value added by a newer server deserializes unchanged, so switch on
@@ -9576,5 +10175,5 @@ declare const WhatsAppTemplateParameterType: {
 /** A known WhatsAppTemplateParameterType value. */
 type WhatsAppTemplateParameterTypeValue = (typeof WhatsAppTemplateParameterType)[keyof typeof WhatsAppTemplateParameterType];
 //#endregion
-export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceCreateParams, type AudienceListContactsQuery, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type DnsRecord, type Domain, type DomainCapabilities, type DomainCreateParams, type DomainDkim, type DomainListQuery, type DomainUpdateParams, type EmailChannelDefaults, EmailEventType, type EmailEventTypeValue, type EmailListQuery, type EmailMailboxLabelList, type EmailMailboxesCreateParams, type EmailMailboxesListQuery, type EmailMailboxesMessagesCreateParams, type EmailMailboxesReceiveRulesCreateParams, type EmailMailboxesReceiveRulesListQuery, type EmailMailboxesStatsQuery, type EmailMailboxesUpdateParams, type EmailMailboxesUpdateQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type EmailStatsByBounceCodeQuery, type EmailStatsByBounceCodeResponse, type EmailStatsByBroadcastQuery, type EmailStatsByBroadcastResponse, type EmailStatsByCategoryQuery, type EmailStatsByCategoryResponse, type EmailStatsByClientQuery, type EmailStatsByClientResponse, type EmailStatsByComplaintTypeQuery, type EmailStatsByComplaintTypeResponse, type EmailStatsByLocationQuery, type EmailStatsByLocationResponse, type EmailStatsByMailboxProviderQuery, type EmailStatsByMailboxProviderRegionQuery, type EmailStatsByMailboxProviderRegionResponse, type EmailStatsByMailboxProviderResponse, type EmailStatsByRecipientDomainQuery, type EmailStatsByRecipientDomainResponse, type EmailStatsBySendingDomainQuery, type EmailStatsBySendingDomainResponse, type EmailStatsBySendingIpQuery, type EmailStatsBySendingIpResponse, type EmailStatsByTagQuery, type EmailStatsByTemplateQuery, type EmailStatsByTemplateResponse, type EmailStatsDailyQuery, type EmailStatsHourlyQuery, type EmailStatsResponse, type EmailStatsSummary, type EmailStatsSummaryQuery, type EmailStatsTagsResponse, type EmailThread, type EmailThreadMessage, type EmailThreadMessageAttachmentList, type EmailThreadMessageBody, type EmailThreadsDeleteQuery, type EmailThreadsListQuery, type EmailThreadsMessagesListQuery, type EmailThreadsMessagesReplyParams, type EmailThreadsUpdateParams, type ErrorDetail, type ErrorNextAction, type Mailbox, type MailboxStatsResponse, type PaginatedPromise, type RealtimeBatchPublishResult, type RealtimeChannelGetQuery, type RealtimeChannelInclude, type RealtimeChannelInfo, type RealtimeChannelListItem, type RealtimeChannelListQuery, type RealtimeChannelMember, type RealtimeChannelMembers, type RealtimeChannelsList, type RealtimeOptions, type RealtimePublishBatchParams, type RealtimePublishParams, type RealtimePublishResult, type ReceiveRule, type RequestOptions, SMSErrorCode, type SMSErrorCodeValue, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, type UnmetGate, type Verification, VerificationAttemptFailureReason, type VerificationAttemptFailureReasonValue, VerificationChannel, type VerificationChannelValue, type VerificationCheckResult, VerificationTerminalReason, type VerificationTerminalReasonValue, type VerifyVerificationsCheckParams, type VerifyVerificationsCreateParams, type VerifyVerificationsNextChannelParams, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, WhatsAppErrorCode, type WhatsAppErrorCodeValue, type WhatsAppEventList, type WhatsAppMessage, WhatsAppTemplateCategory, type WhatsAppTemplateCategoryValue, WhatsAppTemplateParameterType, type WhatsAppTemplateParameterTypeValue, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, baseUrlForRegion, regionFromApiKey };
+export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceCreateParams, type AudienceListContactsQuery, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type DnsRecord, type Domain, type DomainCapabilities, type DomainCreateParams, type DomainDkim, type DomainListQuery, type DomainUpdateParams, type EmailChannelDefaults, EmailEventType, type EmailEventTypeValue, type EmailListQuery, type EmailLookup, EmailLookupFlag, type EmailLookupFlagValue, EmailLookupReason, type EmailLookupReasonValue, EmailLookupResult, type EmailLookupResultValue, type EmailMailboxLabelList, type EmailMailboxesCreateParams, type EmailMailboxesListQuery, type EmailMailboxesMessagesCreateParams, type EmailMailboxesReceiveRulesCreateParams, type EmailMailboxesReceiveRulesListQuery, type EmailMailboxesStatsQuery, type EmailMailboxesUpdateParams, type EmailMailboxesUpdateQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type EmailStatsByBounceCodeQuery, type EmailStatsByBounceCodeResponse, type EmailStatsByBroadcastQuery, type EmailStatsByBroadcastResponse, type EmailStatsByCategoryQuery, type EmailStatsByCategoryResponse, type EmailStatsByClientQuery, type EmailStatsByClientResponse, type EmailStatsByComplaintTypeQuery, type EmailStatsByComplaintTypeResponse, type EmailStatsByLocationQuery, type EmailStatsByLocationResponse, type EmailStatsByMailboxProviderQuery, type EmailStatsByMailboxProviderRegionQuery, type EmailStatsByMailboxProviderRegionResponse, type EmailStatsByMailboxProviderResponse, type EmailStatsByRecipientDomainQuery, type EmailStatsByRecipientDomainResponse, type EmailStatsBySendingDomainQuery, type EmailStatsBySendingDomainResponse, type EmailStatsBySendingIpQuery, type EmailStatsBySendingIpResponse, type EmailStatsByTagQuery, type EmailStatsByTemplateQuery, type EmailStatsByTemplateResponse, type EmailStatsDailyQuery, type EmailStatsHourlyQuery, type EmailStatsResponse, type EmailStatsSummary, type EmailStatsSummaryQuery, type EmailStatsTagsResponse, type EmailThread, type EmailThreadMessage, type EmailThreadMessageAttachmentList, type EmailThreadMessageBody, type EmailThreadsDeleteQuery, type EmailThreadsListQuery, type EmailThreadsMessagesListQuery, type EmailThreadsMessagesReplyParams, type EmailThreadsUpdateParams, type ErrorDetail, type ErrorNextAction, type LookupEmailParams, LookupFlag, type LookupFlagValue, type LookupPhoneNumberParams, LookupPropertyStatus, type LookupPropertyStatusValue, type Mailbox, type MailboxStatsResponse, type PaginatedPromise, type PhoneNumberLookup, type RealtimeBatchPublishResult, type RealtimeChannelGetQuery, type RealtimeChannelInclude, type RealtimeChannelInfo, type RealtimeChannelListItem, type RealtimeChannelListQuery, type RealtimeChannelMember, type RealtimeChannelMembers, type RealtimeChannelsList, type RealtimeOptions, type RealtimePublishBatchParams, type RealtimePublishParams, type RealtimePublishResult, type ReceiveRule, type RequestOptions, SMSErrorCode, type SMSErrorCodeValue, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, type UnmetGate, type Verification, VerificationAttemptFailureReason, type VerificationAttemptFailureReasonValue, VerificationChannel, type VerificationChannelValue, type VerificationCheckResult, VerificationTerminalReason, type VerificationTerminalReasonValue, type VerifyVerificationsCheckParams, type VerifyVerificationsCreateParams, type VerifyVerificationsNextChannelParams, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, WhatsAppErrorCode, type WhatsAppErrorCodeValue, type WhatsAppEventList, type WhatsAppMessage, WhatsAppTemplateCategory, type WhatsAppTemplateCategoryValue, WhatsAppTemplateParameterType, type WhatsAppTemplateParameterTypeValue, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, baseUrlForRegion, regionFromApiKey };
 //# sourceMappingURL=index.d.mts.map