@messagebird/sdk 0.27.0 → 0.29.0

package/dist/index.mjs

@@ -1411,7 +1411,15 @@ const sendRealtimeAppMemberEvent = (options) => (options.client ?? client).post(
 /**
 * List messages
 *
-* Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item carries the aggregate delivery `status` and per-state recipient counts, not the message body. Combine filters to narrow the page: `status`, `category`, `tag`, exact `to`/`from` address, and a `created_after`/`created_before` time window.
+* Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item has the aggregate delivery `status` and per-state recipient counts, not the message body.
+*
+* Combine filters to narrow the page:
+*
+* - Delivery status.
+* - Category.
+* - Tag.
+* - An exact `to` or `from` address.
+* - A `created_after` or `created_before` time window.
 *
 */
 const listEmailMessages = (options) => (options?.client ?? client).get({
@@ -1431,7 +1439,7 @@ const listEmailMessages = (options) => (options?.client ?? client).get({
 *
 * Sends an email to the recipients you list explicitly in `to`/`cc`/`bcc`. Use it for
 * transactional sends (receipts, password resets, alerts) and for marketing sends where
-* you have the recipient addresses on hand; to submit many independent messages in one
+* you have the recipient addresses on hand. To submit many independent messages in one
 * request, use [Send a batch of messages](/docs/api/reference/create-email-message-batch)
 * instead. The `category` field controls suppression policy independently of content:
 * set it to `marketing` when sending marketing content from this endpoint.
@@ -1440,10 +1448,10 @@ const listEmailMessages = (options) => (options?.client ?? client).get({
 * delivered. Fetch it by `id` or subscribe to webhook events to follow delivery. The
 * request never half-succeeds: an unverified sender domain or any field-level
 * validation failure rejects it immediately with a `422` naming the reason.
-* Suppression is evaluated per recipient after acceptance: suppressed recipients
-* surface as `rejected` on the message's recipient list, never as a synchronous
+* Suppression is evaluated per recipient after acceptance, so a suppressed recipient
+* appears as `rejected` on the message's recipient list rather than as a synchronous
 * error. New workspaces can send from the shared onboarding domain before verifying
-* their own; the [quickstart](/docs/get-started/send-your-first-email) covers its
+* their own. The [quickstart](/docs/get-started/send-your-first-email) covers its
 * recipient and volume limits.
 *
 */
@@ -1466,7 +1474,7 @@ const createEmailMessage = (options) => (options.client ?? client).post({
 /**
 * Send a batch of messages
 *
-* Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures (such as `domain_not_verified`) both return `422`. Suppression is evaluated per recipient after acceptance, never as a synchronous error. The `202` response returns one entry per message in submission order, each with its own `id` to fetch or correlate webhook events against. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.
+* Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures (such as `domain_not_verified`) both return `422`. Suppression is evaluated per recipient after acceptance, never as a synchronous error. The `202` response returns one entry per message in submission order, each with its own `id` you can use to fetch that message or match it against webhook events. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.
 *
 */
 const createEmailMessageBatch = (options) => (options.client ?? client).post({
@@ -1488,7 +1496,7 @@ const createEmailMessageBatch = (options) => (options.client ?? client).post({
 /**
 * Get a message
 *
-* Returns a single message with its aggregate delivery `status` and per-state recipient counts. The response never includes the `html`/`text` bodies; when content storage is enabled for the send, fetch the stored bodies with [Get stored message content](/docs/api/reference/get-email-message-content). Per-recipient statuses and the event timeline are separate sub-resources.
+* Returns a single message with its aggregate delivery `status` and per-state recipient counts. The response never includes the `html`/`text` bodies. When content storage is enabled for the send, fetch the stored bodies with [Get stored message content](/docs/api/reference/get-email-message-content). Per-recipient statuses and the event timeline are separate sub-resources.
 *
 */
 const getEmailMessage = (options) => (options.client ?? client).get({
@@ -1506,7 +1514,7 @@ const getEmailMessage = (options) => (options.client ?? client).get({
 /**
 * Cancel a scheduled message
 *
-* Cancels a message that was scheduled with `scheduled_at` before it sends. Only a message that is still scheduled can be canceled; a message that already started sending, was delivered, or was previously canceled returns a conflict error. The message's status becomes `canceled` and an `email.canceled` webhook event fires. Canceling does not return consumed scheduled-send quota.
+* Cancels a message that was scheduled with `scheduled_at` before it sends. Only a message that is still scheduled can be canceled. A message that already started sending, was delivered, or was previously canceled returns a conflict error. The message's status becomes `canceled` and an `email.canceled` webhook event fires. Canceling does not return consumed scheduled-send quota.
 *
 */
 const cancelEmailMessage = (options) => (options.client ?? client).post({
@@ -1524,7 +1532,7 @@ const cancelEmailMessage = (options) => (options.client ?? client).post({
 /**
 * List contacts
 *
-* Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact `email`, `phone`, or `external_id`, or search by email, first name, last name, or phone substring with `q`. Pass `include_total=true` to add the total number of matching contacts to the response.
+* Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact `email`, `phone_number`, or `external_id`, or search by email, first name, last name, or phone substring with `q`. Repeat `phone_number` to resolve up to 50 numbers to their contacts in one request, raising `limit` to at least the number of values you pass. Pass `include_total=true` to add the total number of matching contacts to the response.
 *
 */
 const listContacts = (options) => (options?.client ?? client).get({
@@ -2088,6 +2096,72 @@ const getSmsTemplate = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Look up a phone number
+*
+* Returns what we know about a phone number: which network serves it, which network issued it, whether it has been ported, its country, and what kind of line it is. That baseline is included with every lookup.
+*
+* Use `type` to buy more. Each value adds a block to the answer: how the number is classified, whether it is live on the network right now, whether it is roaming, when its SIM last changed, its porting record, or a credibility score. Omit `type` and the response is the baseline alone, and no intelligence provider is contacted.
+*
+* Every block you request comes back carrying a `status`, so a partial answer is visible rather than silent, and **you are billed for exactly the blocks whose status is `ok`**.
+*
+* Send the number in the body rather than the URL when you would rather it did not appear in request logs or browser history. [Look up a phone number by URL](/docs/api/reference/get-phone-number-lookup) is the same lookup with the number in the path.
+*
+* Send an `Idempotency-Key` and a retried request returns the stored answer instead of looking the number up and charging again. Without one, every attempt is a new lookup and is billed.
+*
+*/
+const createPhoneNumberLookup = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/lookup/phone-number",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* Look up an email address
+*
+* Returns whether an email address is worth sending to:
+*
+* - Whether it will accept mail.
+* - How confident that is.
+* - Why not, when it will not.
+* - Whether it is a role, disposable, or free-provider address.
+* - What it looks like it was meant to be, when it looks misspelled.
+*
+* One address per call, and one answer: `result` is the field to decide on. Every answer costs the same, including `undeliverable`, which is usually the most valuable one you can get.
+*
+* `result` and `reason` are open vocabularies: the values below are the ones in use today, and further ones may be added. Branch on the values you know and treat anything else as a future value rather than an error. `delivery_confidence` is always present and always comparable, so it is the safe fallback.
+*
+* Send the address in the body rather than the URL when you would rather it did not appear in request logs or browser history. [Look up an email address by URL](/docs/api/reference/get-email-lookup) is the same lookup with the address in the path.
+*
+* Send an `Idempotency-Key` and a retried request returns the stored answer instead of validating the address and charging again. Without one, every attempt is a new lookup and is billed.
+*
+*/
+const createEmailLookup = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/lookup/email",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * Create a verification
 *
 * Creates a verification for a recipient and sends them a one-time passcode. Provide the recipient in `to`: an email address (verified over email), a phone number (verified over the phone channels enabled for its destination country), or both. The passcode is sent over one channel at a time and delivery falls over to the next channel in the plan if one fails; it is never sent over two channels at once.
@@ -2168,9 +2242,18 @@ const createVerificationNextChannel = (options) => (options.client ?? client).po
 /**
 * List WhatsApp messages
 *
-* Returns the workspace's WhatsApp messages as a cursor-paginated list, newest first. Filter by direction, status, contact phone number, business-scoped user ID, template category, tag, or creation time; pass the response's `next_cursor` back as `starting_after` to fetch the next page. To follow a single message's delivery, use [Get a WhatsApp message](/docs/api/reference/get-whats-app-message) instead.
+* Returns the workspace's WhatsApp messages as a cursor-paginated list,
+* newest first. Filter by direction, status, contact phone number,
+* business-scoped user ID, template category, tag, or creation time; pass the response's `next_cursor` back as
+* `starting_after` to fetch the next page. To follow a single message's
+* delivery, use
+* [Get a WhatsApp message](/docs/api/reference/get-whats-app-message)
+* instead.
 *
-* Messages are retained for **30 days**. A `created_after` earlier than that is accepted and raised to the retention bound rather than rejected, so a wider window returns what is still retained instead of failing. There is no way to read messages older than the window.
+* Messages are retained for **30 days**. A `created_after` earlier than that
+* is accepted and raised to the retention bound rather than rejected, so a
+* wider window returns what is still retained instead of failing. There is no
+* way to read messages older than the window.
 *
 */
 const listWhatsAppMessages = (options) => (options?.client ?? client).get({
@@ -2307,11 +2390,11 @@ const getEmailStatsHourly = (options) => (options?.client ?? client).get({
 /**
 * Stats by tag
 *
-* Returns aggregate delivery and engagement counts grouped by tag for the requested period. Rows are ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, hard maximum 200). Use this to compare campaign performance across tags you set at send time.
+* Returns delivery and engagement counts for the requested period, grouped by tag. Use it to compare performance across the tags you set at send time. Rows are ranked by the `sort` metric, `processed` by default, and capped at the requested `limit` (50 by default, 200 at most).
 *
-* Rows are computed against event time (not send time), so engagement received during the period for messages sent earlier is included.
+* Rows are computed against event time rather than send time, so engagement received during the period counts even for messages that were sent earlier.
 *
-* The maximum window is 365 days; requesting a longer range returns 422.
+* The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByTag = (options) => (options?.client ?? client).get({
@@ -2329,7 +2412,7 @@ const getEmailStatsByTag = (options) => (options?.client ?? client).get({
 /**
 * Aggregate stats summary
 *
-* Returns a single-row aggregate across the requested period covering delivery, bounce, complaint, open, and click counts plus the derived rates, along with processing, delivery, and total latency percentiles (p50/p95/p99). Suitable for KPI tiles, campaign reports, and email digests; the daily and hourly endpoints carry the same metrics per time bucket.
+* Returns a single-row aggregate across the requested period covering delivery, bounce, complaint, open, and click counts plus the derived rates, along with processing, delivery, and total latency percentiles (p50/p95/p99). Suitable for KPI tiles, campaign reports, and email digests; the daily and hourly endpoints have the same metrics per time bucket.
 *
 * The aggregate is computed against event time (not send time), so engagement received during the period for messages sent earlier is included. Rate fields are null when their denominator is zero.
 *
@@ -2351,11 +2434,11 @@ const getEmailStatsSummary = (options) => (options?.client ?? client).get({
 /**
 * Stats by sending IP
 *
-* Returns delivery and deliverability counts grouped by the specific IP address used to send each message. Use this to identify per-IP reputation issues: block bounces concentrated on a single IP usually indicate a reputation problem on that IP, and `sort=bounces.block` surfaces those IPs first.
+* Returns delivery and deliverability counts for the requested period, grouped by the specific IP address used to send each message. Use it to spot a reputation problem on one IP. Block bounces concentrated on a single IP usually mean that IP's reputation has taken a hit, and sorting by `bounces.block` puts those IPs first.
 *
-* A sending IP is known only once the upstream mail system reports delivery, bounce, deferral, or a late bounce, so rows cover the delivery stage onward: `accepted` and `processed` counts, processing latency, engagement, and complaint attribution are not available per IP. For workspace-wide figures use `GET /v1/email/stats/daily`. Rows are computed against event time (not send time).
+* A sending IP is only known once the receiving mail server reports an outcome: a delivery, a bounce, a deferral, or a late bounce. So this breakdown starts from the delivery stage onward. Accepted, processed, and rejected counts aren't included at all, and neither are engagement counts or processing latency. Complaints and out-of-band bounces aren't attributed to a sending IP either, so `complained` and `oob_bounces` are included but always read 0 here. Bounced, deferred, delivery latency, and total latency are the ones that have real numbers. For workspace-wide figures, use `GET /v1/email/stats/daily`. Rows are computed against event time rather than send time.
 *
-* Rows are ranked by the `sort` field (default `delivered`) descending and capped at the requested `limit` (default 50, hard maximum 200). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by the `sort` field, `delivered` by default, and capped at the requested `limit` (50 by default, 200 at most). The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsBySendingIp = (options) => (options?.client ?? client).get({
@@ -2373,11 +2456,11 @@ const getEmailStatsBySendingIp = (options) => (options?.client ?? client).get({
 /**
 * Stats by sending domain
 *
-* Returns delivery, engagement, and deliverability counts grouped by sending domain (the portion of the `From` address after the `@`). Use this to compare deliverability across multiple verified domains in your workspace, for example transactional versus marketing domains, or sub-domain segregation during IP warming.
+* Returns delivery, engagement, and deliverability counts for the requested period, grouped by sending domain: the portion of the `From` address after the `@`. Use it to compare deliverability across multiple verified domains in your workspace, for example transactional versus marketing domains, or sub-domain segregation during IP warming.
 *
-* Rows are computed against event time (not send time), so engagement and bounces received during the period for messages sent earlier are included.
+* Rows are computed against event time rather than send time, so engagement and bounces received during the period count even for messages that were sent earlier.
 *
-* Rows are ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, hard maximum 200). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by the `sort` metric, `processed` by default, and capped at the requested `limit` (50 by default, 200 at most). The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsBySendingDomain = (options) => (options?.client ?? client).get({
@@ -2395,11 +2478,11 @@ const getEmailStatsBySendingDomain = (options) => (options?.client ?? client).ge
 /**
 * Stats by category
 *
-* Returns aggregate delivery and engagement counts grouped by category for the requested period. Rows are ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, hard maximum 200). Use this to compare deliverability and engagement between your transactional and marketing traffic.
+* Returns delivery and engagement counts for the requested period, grouped by category, so you can compare deliverability and engagement between your transactional and marketing traffic. Rows are ranked by the `sort` metric, `processed` by default, and capped at the requested `limit` (50 by default, 200 at most).
 *
-* Rows are computed against event time (not send time), so engagement received during the period for messages sent earlier is included.
+* Rows are computed against event time rather than send time, so engagement received during the period counts even for messages that were sent earlier.
 *
-* The maximum window is 365 days; requesting a longer range returns 422.
+* The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByCategory = (options) => (options?.client ?? client).get({
@@ -2417,11 +2500,11 @@ const getEmailStatsByCategory = (options) => (options?.client ?? client).get({
 /**
 * Stats by mailbox provider
 *
-* Returns delivery, engagement, and deliverability counts grouped by recipient mailbox provider (for example `gmail`, `yahoo`, `microsoft`, `apple`): the deliverability-by-inbox-provider view. Use this to compare how each major inbox provider treats your mail, for example to spot a delivered-rate dip or complaint spike at one provider before it spreads; for a per-region split within a provider, use the mailbox-provider-region breakdown.
+* Returns delivery, engagement, and deliverability counts for the requested period, grouped by recipient mailbox provider, for example `gmail`, `yahoo`, `microsoft`, or `apple`. Use it to compare how each major inbox provider treats your mail, for example to spot a delivered-rate dip or a complaint spike at one provider before it spreads. For a per-region split within a provider, use the mailbox-provider-region breakdown.
 *
-* A recipient's mailbox provider is known only once the receiving mail system reports an outcome, so rows cover the delivery stage onward: `accepted`, `processed`, and `rejected` counts and processing latency are not included. Rows are computed against event time (not send time).
+* A recipient's mailbox provider is only known once the receiving mail system reports an outcome, so this breakdown covers the delivery stage onward. Accepted, processed, and rejected counts and processing latency are not included. Rows are computed against event time rather than send time.
 *
-* Rows are ranked by the `sort` metric (default `delivered`) descending and capped at the requested `limit` (default 50, hard maximum 200). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by the `sort` metric, `delivered` by default, and capped at the requested `limit` (50 by default, 200 at most). The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByMailboxProvider = (options) => (options?.client ?? client).get({
@@ -2439,11 +2522,11 @@ const getEmailStatsByMailboxProvider = (options) => (options?.client ?? client).
 /**
 * Stats by mailbox provider region
 *
-* Returns delivery, engagement, and deliverability counts grouped by mailbox provider and provider region pair, for example `gmail` in `NA` or `microsoft` in `EU`. The provider region is the regional pod the receiving mail system reports for the recipient's provider; pairing it with the provider disambiguates a region label that several providers share. Use this to spot a deliverability problem isolated to one provider in one region; for a per-provider view without the region split, use the mailbox-provider breakdown.
+* Returns delivery, engagement, and deliverability counts for the requested period, grouped by mailbox provider and provider region pair, for example `gmail` in `NA` or `microsoft` in `EU`. The provider region is the regional grouping the receiving mail system reports for the recipient's provider. Pairing it with the provider tells apart a region label that several providers share. Use it to spot a deliverability problem isolated to one provider in one region. For a per-provider view without the region split, use the mailbox-provider breakdown.
 *
-* A provider region is known only once the receiving mail system reports an outcome, so rows cover the delivery stage onward: `accepted`, `processed`, and `rejected` counts and processing latency are not included. Rows are computed against event time (not send time).
+* A provider region is only known once the receiving mail system reports an outcome, so this breakdown covers the delivery stage onward. Accepted, processed, and rejected counts and processing latency are not included. Rows are computed against event time rather than send time.
 *
-* Rows are ranked by the `sort` metric (default `delivered`) descending and capped at the requested `limit` (default 50, hard maximum 200). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by the `sort` metric, `delivered` by default, and capped at the requested `limit` (50 by default, 200 at most). The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByMailboxProviderRegion = (options) => (options?.client ?? client).get({
@@ -2461,11 +2544,11 @@ const getEmailStatsByMailboxProviderRegion = (options) => (options?.client ?? cl
 /**
 * Stats by recipient domain
 *
-* Returns aggregate delivery and engagement counts grouped by recipient mailbox domain (the part of each recipient address after the `@`, for example `gmail.com`, `yahoo.com`, `outlook.com`) for the requested period. This is the finest-grained deliverability view: where the mailbox-provider breakdown groups recipients into provider buckets such as `gmail` or `microsoft`, this keys on the exact destination domain. Use it to spot a delivery-rate dip or complaint spike at a specific domain.
+* Returns delivery and engagement counts for the requested period, grouped by recipient mailbox domain: the part of each recipient address after the `@`, for example `gmail.com`, `yahoo.com`, or `outlook.com`. This is the finest-grained deliverability view. Where the mailbox-provider breakdown groups recipients into provider buckets such as `gmail` or `microsoft`, this keys on the exact destination domain. Use it to spot a delivery-rate dip or a complaint spike at a specific domain.
 *
-* Rows are ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, hard maximum 200). Rows are computed against event time (not send time), so engagement received during the period for messages sent earlier is included.
+* Rows are ranked by the `sort` metric, `processed` by default, and capped at the requested `limit` (50 by default, 200 at most). Rows are computed against event time rather than send time, so engagement received during the period counts even for messages that were sent earlier.
 *
-* The maximum window is 365 days; requesting a longer range returns 422.
+* The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByRecipientDomain = (options) => (options?.client ?? client).get({
@@ -2505,11 +2588,11 @@ const getEmailStatsByTemplate = (options) => (options?.client ?? client).get({
 /**
 * Engagement by location
 *
-* Returns engagement counts (opens and clicks) grouped by the location they were recorded from, for the requested period. Use it to see where your audience engages, for example the top countries by unique opens. Location is known from open and click events only, so rows carry engagement counts but no delivery counts or rates.
+* Returns engagement counts (opens and clicks) for the requested period, grouped by the location they were recorded from. Use it to see where your audience engages, for example the top countries by unique opens. The reading location is only known from open and click events, so rows have engagement counts but no delivery counts or rates.
 *
-* Use `group_by` to choose the granularity: `country` (default), `region`, or `city`. Each row carries the location hierarchy down to the requested level (a `city` grouping also reports the row's region and country). Rows are ranked by the `sort` metric (default `unique_opens`) descending and capped at the requested `limit` (default 50, hard maximum 200).
+* Use `group_by` to choose the granularity: `country` (the default), `region`, or `city`. Each row has the location hierarchy down to the requested level, so a `city` grouping also reports that row's region and country. Rows are ranked by the `sort` metric, `unique_opens` by default, and capped at the requested `limit` (50 by default, 200 at most).
 *
-* Rows are computed against event time (not send time). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are computed against event time rather than send time. The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByLocation = (options) => (options?.client ?? client).get({
@@ -2527,11 +2610,11 @@ const getEmailStatsByLocation = (options) => (options?.client ?? client).get({
 /**
 * Engagement by email client
 *
-* Returns engagement counts (opens and clicks) grouped by the email client, operating system, or device type they were recorded from, for the requested period. Use it for the classic "opens by mail client" view, for example the share of opens from Apple Mail versus Gmail versus Outlook. The reading environment is known from open and click events only, so rows carry engagement counts but no delivery counts or rates.
+* Returns engagement counts (opens and clicks) for the requested period, grouped by the email client, operating system, or device type they were recorded from. Use it for the classic view of opens by mail client, for example the share of opens from Apple Mail compared with Gmail and Outlook. The reading environment is only known from open and click events, so rows have engagement counts but no delivery counts or rates.
 *
-* Use `group_by` to choose the facet: `email_client` (default), `os`, or `device_type`. Each row populates the chosen facet and leaves the other two null. Rows are ranked by the `sort` metric (default `unique_opens`) descending and capped at the requested `limit` (default 50, hard maximum 200).
+* Use `group_by` to choose the facet: `email_client` (the default), `os`, or `device_type`. Each row fills in the facet you chose and leaves the other two null. Rows are ranked by the `sort` metric, `unique_opens` by default, and capped at the requested `limit` (50 by default, 200 at most).
 *
-* Rows are computed against event time (not send time). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are computed against event time rather than send time. The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByClient = (options) => (options?.client ?? client).get({
@@ -2549,11 +2632,11 @@ const getEmailStatsByClient = (options) => (options?.client ?? client).get({
 /**
 * Bounces by SMTP error code
 *
-* Returns bounce counts grouped by the SMTP error code the receiving mail server returned, for the requested period: the deliverability-debugging view that answers "which SMTP responses are driving my bounces". Each row reports the bounced recipients for one code plus the hard/soft/admin/block/undetermined split.
+* Returns bounce counts for the requested period, grouped by the SMTP error code the receiving mail server returned. It answers the question of which SMTP responses are driving your bounces. Each row reports how many recipients bounced with that code, plus the hard, soft, admin, block, and undetermined split for that code.
 *
-* This breakdown reports the failure side only: it has no delivered, open, click, or rate fields, because a bounce code is recorded only on bounce events.
+* This breakdown only covers the failure side. There are no delivered, open, click, or rate fields, because a bounce code is only ever recorded on a bounce event.
 *
-* Rows are ranked by the `sort` metric (default `bounced`) descending, capped at the requested `limit` (default 50, hard maximum 200), and computed against event time (not send time). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by the `sort` metric, `bounced` by default, and capped at the requested `limit` (50 by default, 200 at most). They are computed against event time rather than send time. The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByBounceCode = (options) => (options?.client ?? client).get({
@@ -2571,11 +2654,11 @@ const getEmailStatsByBounceCode = (options) => (options?.client ?? client).get({
 /**
 * Complaints by type
 *
-* Returns spam-complaint counts grouped by the feedback-loop complaint type reported by the mailbox provider (for example `abuse`, `fraud`, `virus`), for the requested period. Use it to understand what kind of complaints your mail attracts.
+* Returns spam-complaint counts for the requested period, grouped by the feedback-loop complaint type the mailbox provider reported, for example `abuse`, `fraud`, or `virus`. Use it to see what kind of complaints your mail attracts.
 *
-* This breakdown reports the complaint side only: each row carries the complained count for one type and nothing else, because a complaint type is recorded only on spam-complaint events.
+* This breakdown only covers the complaint side. Each row has the complained count for one type and nothing else, because a complaint type is only ever recorded on a spam-complaint event.
 *
-* Rows are ranked by `complained` descending, capped at the requested `limit` (default 50, hard maximum 200), and computed against event time (not send time). The maximum window is 365 days; requesting a longer range returns 422.
+* Rows are ranked by `complained` descending, and capped at the requested `limit` (default 50, hard maximum 200). They are computed against event time rather than send time. The window can span at most 365 days. Ask for more and you get a 422.
 *
 */
 const getEmailStatsByComplaintType = (options) => (options?.client ?? client).get({
@@ -2593,11 +2676,11 @@ const getEmailStatsByComplaintType = (options) => (options?.client ?? client).ge
 /**
 * Stats by broadcast
 *
-* Returns aggregate delivery and engagement counts grouped by broadcast for the requested period, so each broadcast's deliverability and engagement can be compared side by side. Only messages sent as part of a broadcast appear here; one-off and transactional sends are not included, so a workspace that has not sent broadcasts returns an empty list rather than an error.
+* Returns aggregate delivery and engagement counts grouped by broadcast for the requested period, so each broadcast's deliverability and engagement can be compared side by side. Only messages sent as part of a broadcast appear here. One-off and transactional sends are not included, so a workspace that has not sent broadcasts returns an empty list rather than an error.
 *
 * Rows are ranked by the `sort` metric (default `processed`) descending and capped at the requested `limit` (default 50, hard maximum 200). Rows are computed against event time (not send time), so engagement received during the period for messages sent earlier is included.
 *
-* The maximum window is 365 days; requesting a longer range returns 422. This breakdown is computed from per-message activity retained for 30 days, so it reflects roughly the last 30 days of activity even when the requested window reaches further back.
+* The maximum window is 365 days. Requesting a longer range returns a 422. This breakdown is computed from per-message activity retained for 30 days, so it reflects roughly the last 30 days of activity even when the requested window reaches further back.
 *
 */
 const getEmailStatsByBroadcast = (options) => (options?.client ?? client).get({
@@ -2635,12 +2718,12 @@ const listDomains = (options) => (options?.client ?? client).get({
 *
 * Registers a new sending domain and returns the DNS records to publish
 * for it. The DKIM TXT record proves ownership, and together with the
-* return-path CNAME (which also covers SPF; no separate SPF record is
+* return-path CNAME (which also covers SPF, so no separate SPF record is
 * needed) and a DMARC policy it gates sending. The tracking CNAME is
 * optional and gates branded link tracking only. Publish the records at
 * your DNS provider, then check progress with
-* [Trigger domain verification](/docs/api/reference/verify-domain); Bird
-* also re-checks published records automatically. Setup walkthrough:
+* [Trigger domain verification](/docs/api/reference/verify-domain). Published
+* records are also re-checked for you automatically. Setup walkthrough:
 * [Sending domains](/docs/guides/email/sending-domains).
 *
 * The domain starts in `pending` status. A domain already registered in
@@ -2686,7 +2769,7 @@ const deleteDomain = (options) => (options.client ?? client).delete({
 /**
 * Get a sending domain
 *
-* Returns the domain with its capability statuses and every DNS record's current verification state. This read reports the stored result of the last check; to run a fresh DNS check, use [Trigger domain verification](/docs/api/reference/verify-domain).
+* Returns the domain with its capability statuses and every DNS record's current verification state. This read reports the stored result of the last check. To run a fresh DNS check, use [Trigger domain verification](/docs/api/reference/verify-domain).
 *
 */
 const getDomain = (options) => (options.client ?? client).get({
@@ -2709,12 +2792,12 @@ const getDomain = (options) => (options.client ?? client).get({
 * `dkim` on a verified capability are staged: the current configuration
 * keeps serving until the new one's DNS records verify, then the change
 * is promoted automatically. Staged values are visible under
-* `capabilities.*.pending`; the records to publish appear in
+* `capabilities.*.pending`. The records to publish appear in
 * `dns_records` with `state: pending`.
 *
-* Invalid combinations are rejected: enabling tracking toggles without a
+* Invalid combinations are rejected. Enabling tracking toggles without a
 * tracking domain, or removing the tracking domain while a toggle is on,
-* returns `409`; enabling inbound receiving has verification
+* returns `409`. Enabling inbound receiving has verification
 * prerequisites that return `422`. Each rule is detailed on its field.
 *
 */
@@ -2740,9 +2823,9 @@ const updateDomain = (options) => (options.client ?? client).patch({
 * Runs a fresh DNS check across the domain's records (DKIM, return path,
 * DMARC, tracking, inbound MX, and any staged changes) and returns the
 * updated domain. Use it for an immediate result after publishing or
-* correcting records; [Get a sending domain](/docs/api/reference/get-domain)
-* only reports the last stored result, and Bird re-checks published
-* records automatically in the background.
+* correcting records. [Get a sending domain](/docs/api/reference/get-domain)
+* only reports the last stored result. Published records are also re-checked
+* for you automatically in the background.
 *
 * A `200` with records still `pending` is not a failure: the records were
 * not found yet, which is normal while DNS propagates (minutes to hours).
@@ -2783,7 +2866,7 @@ const listMailboxes = (options) => (options?.client ?? client).get({
 /**
 * Create a mailbox
 *
-* Creates a mailbox. The address is `local_part@domain`. The domain defaults to `inbox.ai`, Bird's shared mailbox domain, where creating the mailbox claims the address for your organization — first come, first served, and reserved to your organization even after the mailbox is deleted. You may instead name one of your own domains that is enabled for receiving email. An omitted local part is generated. On a custom domain, addresses of deleted mailboxes are quarantined: the same workspace can rebind one 30 days after deletion, other workspaces never can.
+* Creates a mailbox. The address is `local_part@domain`. The domain defaults to `inbox.ai`, our shared mailbox domain, where creating the mailbox claims the address for your organization. It is first come, first served, and reserved to your organization even after the mailbox is deleted. You may instead name one of your own domains that is enabled for receiving email. An omitted local part is generated. On a custom domain, addresses of deleted mailboxes are quarantined. The same workspace can rebind one 30 days after deletion, but other workspaces never can.
 *
 */
 const createMailbox = (options) => (options.client ?? client).post({
@@ -2805,7 +2888,7 @@ const createMailbox = (options) => (options.client ?? client).post({
 /**
 * Delete a mailbox
 *
-* Deletes a mailbox. The address stops receiving mail immediately and enters quarantine: the same workspace can bind it to a new mailbox after 30 days, other workspaces never can. The mailbox and its remembered messages are kept for a 30-day restore window — restore it with `POST /email/mailboxes/{mailbox_id}/restore` — and are permanently deleted once the window closes.
+* Deletes a mailbox. The address stops receiving mail immediately and enters quarantine. The same workspace can bind it to a new mailbox after 30 days, but other workspaces never can. The mailbox and its remembered messages are kept for 30 days, so you can bring it back with `POST /email/mailboxes/{mailbox_id}/restore`. Once those 30 days are up they are deleted for good.
 *
 */
 const deleteMailbox = (options) => (options.client ?? client).delete({
@@ -2823,7 +2906,7 @@ const deleteMailbox = (options) => (options.client ?? client).delete({
 /**
 * Get a mailbox
 *
-* Returns a single mailbox by ID. A mailbox deleted within its 30-day restore window is still returned, with a non-null `deleted_at`; once the window closes it is permanently removed and returns 404.
+* Returns a single mailbox by ID. A mailbox deleted within its 30-day restore window is still returned, with a non-null `deleted_at`. Once the window closes it is permanently removed and returns 404.
 *
 */
 const getMailbox = (options) => (options.client ?? client).get({
@@ -2841,7 +2924,7 @@ const getMailbox = (options) => (options.client ?? client).get({
 /**
 * Update a mailbox
 *
-* Updates a mailbox. The address and domain are immutable. Lowering the retention tier deletes remembered messages older than the new horizon — pass `confirm=true` to acknowledge.
+* Updates a mailbox. The address and domain are immutable. Lowering the retention tier deletes any remembered message older than the new cutoff, so that request needs `confirm=true` before it will run.
 *
 */
 const updateMailbox = (options) => (options.client ?? client).patch({
@@ -2881,8 +2964,10 @@ const restoreMailbox = (options) => (options.client ?? client).post({
 /**
 * Mailbox email statistics
 *
-* Returns the mailbox's sent and received email statistics over a time window: a period-wide summary plus a bucketed series. Sent-mail metrics carry the same delivery, engagement, and latency breakdowns as the email stats endpoints; `received` counts mail that arrived at the mailbox.
-* Rows are bucketed by event time, not send time — engagement received during the period for messages sent earlier is included. Statistics start when the mailbox starts sending and receiving; the mailbox's all-time `message_count` and `thread_count` live on the mailbox resource itself.
+* Returns the mailbox's sent and received email statistics over a time window: a period-wide summary plus a bucketed series. Sent-mail metrics have the same delivery, engagement, and latency breakdowns as the email stats endpoints. `received` counts mail that arrived at the mailbox.
+*
+* Rows are bucketed by the time the event happened rather than the time the message was sent, so engagement that arrived during the period for a message sent earlier is counted here. Statistics start when the mailbox starts sending and receiving; the mailbox's all-time `message_count` and `thread_count` live on the mailbox resource itself.
+*
 * `from` and `to` accept either calendar days (YYYY-MM-DD, `day` granularity only) or RFC 3339 instants (`hour` granularity only). Both bounds must use the same form. Window caps depend on `granularity`: 365 days at `day`, 30 days at `hour`. Set `timezone` to report in a local zone instead of UTC.
 *
 */
@@ -2901,7 +2986,7 @@ const getMailboxStats = (options) => (options.client ?? client).get({
 /**
 * Resume a suspended mailbox
 *
-* Reactivates a mailbox that was suspended because the organization dropped below the plan needed to keep it active. The mailbox can send and receive again and its threads and messages become visible. Activation is refused when the organization has no room for another active mailbox, or for another custom inbox.ai handle, on its current plan — free up a slot by deleting an active mailbox, or upgrade the plan. Activating a mailbox that is not suspended returns a conflict.
+* Resumes a mailbox that was suspended because the organization dropped below the plan needed to keep it active. The mailbox can send and receive again and its conversations and messages become visible. Resuming is refused when the organization has no room for another active mailbox, or for another custom inbox.ai handle, on its current plan. Free up a slot by deleting an active mailbox, or move to a bigger plan. Resuming a mailbox that is not suspended returns a conflict.
 *
 */
 const resumeMailbox = (options) => (options.client ?? client).post({
@@ -2937,7 +3022,7 @@ const listMailboxReceiveRules = (options) => (options.client ?? client).get({
 /**
 * Add a receive rule
 *
-* Adds an allow or block rule to the mailbox. Rules match the message's envelope sender; domain entries also match subdomains. Block rules always win — over allow rules and over the reply admission on allowlist mailboxes. An entry is either allow or block. Rules have no update operation, so a rule that needs the other action is a new rule and the old one is removed. A mailbox holds up to 200 rules.
+* Adds an allow or block rule to the mailbox. Rules match the message's envelope sender. Domain entries also match subdomains. Block rules always win, both over allow rules and over the reply admission on allowlist mailboxes. An entry is either allow or block. Rules have no update operation, so a rule that needs the other action is a new rule and the old one is removed. A mailbox holds up to 200 rules.
 *
 */
 const createMailboxReceiveRule = (options) => (options.client ?? client).post({
@@ -2977,7 +3062,13 @@ const deleteMailboxReceiveRule = (options) => (options.client ?? client).delete(
 /**
 * List threads
 *
-* Returns a paginated list of conversations across the workspace's mailboxes, most recently active first. `label` selects the view: the inbox (the default when omitted), `archive`, `spam`, `blocked`, or any custom label. Filter by mailbox, linked contact, or last-activity time, or pass `q` to full-text search conversations by their messages' subject and text. Conversations whose every message has been trashed are omitted; restoring a message returns its conversation to the list. `before` and `after` filter by time; to page through results pass the response cursors back as `starting_after` or `ending_before`.
+* Returns a paginated list of conversations across the workspace's mailboxes, most recently active first. `label` selects the view: the inbox (the default when omitted), `archive`, `spam`, `blocked`, or any custom label. You can also filter by mailbox, by linked contact, by participant address, or by a subject substring.
+*
+* To search conversations by their messages' subject and text instead of listing them, use `GET /v1/email/threads/search`.
+*
+* Conversations whose every message has been trashed are left out of the list, and restoring a message brings the conversation back.
+*
+* `before` and `after` filter by time. To page through the results, pass the response cursors back as `starting_after` or `ending_before`.
 *
 */
 const listEmailThreads = (options) => (options?.client ?? client).get({
@@ -3013,7 +3104,7 @@ const deleteEmailThread = (options) => (options.client ?? client).delete({
 /**
 * Get a thread
 *
-* Returns a single conversation. Fetch the messages in the conversation with `GET /v1/email/threads/{thread_id}/messages`. A thread whose retention period has ended returns `410 Gone`.
+* Returns a single conversation. Fetch the messages in the conversation with `GET /v1/email/threads/{thread_id}/messages`. A thread whose retention tier has ended returns `410 Gone`.
 *
 */
 const getEmailThread = (options) => (options.client ?? client).get({
@@ -3031,7 +3122,7 @@ const getEmailThread = (options) => (options.client ?? client).get({
 /**
 * Update a thread
 *
-* Applies label changes to a conversation and links or unlinks a contact. System labels move the conversation: adding `spam` files it (and its received messages) as spam, adding `archive` files it away without deleting it, and adding `inbox` — or removing `spam`, `blocked`, or `archive` — returns it to the inbox; unread counts recompute to match. An archived conversation returns to the inbox by itself when a new message arrives. To block a sender going forward, add a receive rule instead. Omitted fields are left unchanged.
+* Applies label changes to a conversation, and links or unlinks a contact. Adding `spam` files the conversation, and its received messages, as spam. Adding `archive` files it away without deleting it. Adding `inbox`, or removing `spam`, `blocked`, or `archive`, returns it to the inbox, and its unread count recomputes to match. An archived conversation returns to the inbox by itself when a new message arrives. To block a sender going forward, add a receive rule instead. Any field you leave out stays unchanged.
 *
 */
 const updateEmailThread = (options) => (options.client ?? client).patch({
@@ -3053,7 +3144,11 @@ const updateEmailThread = (options) => (options.client ?? client).patch({
 /**
 * List messages in a thread
 *
-* Returns the messages in a conversation newest first, both received and sent; page older messages with `starting_after` (fixed sort — render conversation order by reversing the page). By default every message that is not in the trash is returned, whichever folder the conversation is in; pass `label` to narrow the view instead — `trash` for trashed messages, or any custom label. Pass `include=extracted_text` to inline each message's extracted plain text. A thread whose retention period has ended returns `410 Gone`.
+* Returns the messages in a conversation, newest first, both received and sent. To page through older messages, use `starting_after`. The sort order is fixed, so to render the messages in conversation order, reverse the page yourself.
+*
+* By default, every message that is not in the trash is returned, whichever folder the conversation is in. Pass `label` to narrow the view instead: use `trash` for trashed messages, or any custom label.
+*
+* Pass `include=extracted_text` to inline each message's extracted plain text. A thread whose retention tier has ended returns `410 Gone`.
 *
 */
 const listEmailThreadMessages = (options) => (options.client ?? client).get({
@@ -3071,7 +3166,7 @@ const listEmailThreadMessages = (options) => (options.client ?? client).get({
 /**
 * Get a message in a thread
 *
-* Returns a single message in a conversation, including its extracted plain text. Metadata and extracted text remain readable for the mailbox's retention period; a message that has passed it returns `410 Gone`. A message that exists but does not belong to this thread returns `404`.
+* Returns a single message in a conversation, including its extracted plain text. Metadata and extracted text stay readable for the mailbox's retention tier. A message that has aged past its retention tier returns `410 Gone`. A message that exists but does not belong to this thread returns `404`.
 *
 */
 const getEmailThreadMessage = (options) => (options.client ?? client).get({
@@ -3089,7 +3184,7 @@ const getEmailThreadMessage = (options) => (options.client ?? client).get({
 /**
 * Get a thread message's original body
 *
-* Returns the original rendered HTML and plain-text body of a message in a conversation. The original body is available for 30 days after the message occurred; after that this endpoint returns `410 Gone` while the message's extracted text remains readable on the message itself.
+* Returns the original rendered HTML and plain-text body of a message in a conversation. The original body is available for 30 days after the message occurred. After that, this endpoint returns `410 Gone`, but the message's extracted text stays readable on the message itself.
 *
 */
 const getEmailThreadMessageBody = (options) => (options.client ?? client).get({
@@ -3107,7 +3202,7 @@ const getEmailThreadMessageBody = (options) => (options.client ?? client).get({
 /**
 * List a thread message's attachments
 *
-* Returns the attachments on a message in a conversation. Attachment bytes are downloadable for 30 days after the message occurred; after that this endpoint returns `410 Gone` while the attachment metadata remains readable on the message's `attachment_manifest`.
+* Returns the attachments on a message in a conversation. Attachment bytes are downloadable for 30 days after the message occurred. After that, this endpoint returns `410 Gone`, but the attachment metadata stays readable on the message's `attachment_manifest`.
 *
 */
 const listEmailThreadMessageAttachments = (options) => (options.client ?? client).get({
@@ -3125,7 +3220,7 @@ const listEmailThreadMessageAttachments = (options) => (options.client ?? client
 /**
 * Reply to a thread message
 *
-* Sends a reply to a specific message in a conversation, from the mailbox's own address. Recipients are derived from the message being replied to — its Reply-To address when present, otherwise its From address; set `reply_all` to also include the original To and Cc recipients. The subject and the threading headers that keep the reply in this conversation are set automatically, and the reply is recorded in the conversation. To reply to a conversation as a whole, target its newest received message.
+* Sends a reply to a specific message in a conversation, from the mailbox's own address. Recipients are derived from the message being replied to: its Reply-To address when present, otherwise its From address. Set `reply_all` to also include the original To and Cc recipients. The subject and the threading headers that keep the reply in this conversation are set automatically, and the reply is recorded in the conversation. To reply to a conversation as a whole, target its newest received message.
 *
 */
 const replyEmailThreadMessage = (options) => (options.client ?? client).post({
@@ -3147,7 +3242,7 @@ const replyEmailThreadMessage = (options) => (options.client ?? client).post({
 /**
 * Send a message from a mailbox
 *
-* Sends a new message from the mailbox's own address and starts a new conversation with it. The request mirrors the plain send request minus `from` — the mailbox is the sender identity — and Bird mints the RFC 5322 Message-ID, so later replies from the recipients thread back into the conversation automatically. The send is recorded in the mailbox's durable memory and returned as the conversation's first message. Scheduled sends are not accepted on the mailbox surface. A suspended mailbox cannot send and returns `403`.
+* Sends a new message from the mailbox's own address and starts a new conversation with it. The request mirrors the plain send request minus `from`, because the mailbox is who the message comes from. We set the RFC 5322 Message-ID, so later replies from the recipients thread back into the conversation automatically. The send is added to the mailbox's remembered messages and returned as the conversation's first message. A mailbox always sends immediately, so this endpoint does not accept a scheduled send. A suspended mailbox cannot send and returns `403`.
 *
 */
 const createMailboxMessage = (options) => (options.client ?? client).post({
@@ -3169,7 +3264,18 @@ const createMailboxMessage = (options) => (options.client ?? client).post({
 /**
 * List a mailbox's labels
 *
-* Returns the labels available in a mailbox: the built-in system labels — the placements `inbox`, `archive`, `spam`, `blocked`, and `sent`, plus `trash` and `unread` — followed by every custom label currently in use on its conversations and messages. Apply and remove labels through the conversation and message update endpoints; custom labels exist by being applied, so this list is discovery, not management.
+* Returns the labels available in a mailbox. First, the built-in system
+* labels:
+*
+* - The placements `inbox`, `archive`, `spam`, `blocked`, and `sent`.
+* - `trash`.
+* - `unread`.
+*
+* Then, every custom label currently in use on its conversations and
+* messages. You apply and remove labels through the conversation and
+* message update endpoints, and that is also what creates or removes a
+* custom label: it exists for as long as at least one message or
+* conversation has it applied.
 *
 */
 const listMailboxLabels = (options) => (options.client ?? client).get({
@@ -3273,7 +3379,7 @@ function mergeHeaders(idempotencyKey, extra) {
 //#region src/resources/email.gen.ts
 var EmailResourceBase = class 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");
@@ -3290,7 +3396,7 @@ var EmailResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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" })) {
@@ -3309,7 +3415,7 @@ var EmailResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3327,7 +3433,7 @@ var EmailResourceBase = class extends Resource {
 //#region src/resources/emailStats.gen.ts
 var EmailStatsResource = class 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" });
@@ -3342,7 +3448,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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" });
@@ -3357,7 +3463,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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" });
@@ -3372,7 +3478,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3392,7 +3498,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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" });
@@ -3407,7 +3513,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3427,7 +3533,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3447,7 +3553,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3467,7 +3573,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3486,7 +3592,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3505,7 +3611,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3525,7 +3631,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3544,7 +3650,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3563,7 +3669,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3583,7 +3689,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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" });
@@ -3598,7 +3704,7 @@ var EmailStatsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -3641,7 +3747,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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" });
@@ -3656,7 +3762,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3671,7 +3777,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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", {
@@ -3690,7 +3796,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3704,7 +3810,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3719,7 +3825,7 @@ var EmailMailboxesResourceBase = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3812,7 +3918,7 @@ var EmailMailboxesReceiveRulesResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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", {
@@ -3936,7 +4042,7 @@ var EmailThreadsResourceBase = class extends Resource {
 //#region src/resources/emailThreadsMessages.gen.ts
 var EmailThreadsMessagesResource = class 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")) {
@@ -3956,7 +4062,7 @@ var EmailThreadsMessagesResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -3974,7 +4080,7 @@ var EmailThreadsMessagesResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -4013,7 +4119,7 @@ var EmailThreadsMessagesResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -4073,6 +4179,29 @@ var EmailResource = class extends EmailResourceBase {
 	* });
 	* console.log(msg.id, msg.status); // "em_…", "accepted"
 	*
+	* @example Send a published template instead of inline content
+	* const msg = await bird.email.send({
+	*   from: { email: "onboarding@messagebird.dev", name: "Bird" },
+	*   to: ["delivered@messagebird.dev"],
+	*   category: "transactional",
+	*   template: {
+	*     slug: "welcome-email",
+	*     parameters: { first_name: "Jane" },
+	*   },
+	* });
+	* console.log(msg.id, msg.status);
+	*
+	* @example Sending to the sandbox bounce address, which hard-bounces every time
+	* const msg = await bird.email.send({
+	*   from: { email: "onboarding@messagebird.dev", name: "Bird" },
+	*   to: ["bounce+signup-flow@messagebird.dev"],
+	*   subject: "Sandbox bounce test",
+	*   html: "<p>This message will hard-bounce.</p>",
+	*   tags: [{ name: "flow", value: "signup" }],
+	*   metadata: { test_run: "docs-capture-1" },
+	* });
+	* console.log(msg.id, msg.status); // "em_…", "accepted"
+	*
 	* @example A richer send — cc/bcc, reply-to, tags, metadata, click-tracking off, and an idempotency key (safe to retry; the server dedupes)
 	* await bird.email.send(
 	*   {
@@ -4270,7 +4399,7 @@ var AudiencesResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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", {
@@ -4392,7 +4521,7 @@ var DomainsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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", {
@@ -4526,7 +4655,7 @@ var ContactPropertiesResource = class extends Resource {
 //#region src/resources/contacts.gen.ts
 var ContactsResource = class 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, repeating phone_number to resolve up to 50 numbers in one call (raise limit to match), 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" })) {
@@ -4546,7 +4675,7 @@ var ContactsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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");
@@ -4561,7 +4690,7 @@ var ContactsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -4579,7 +4708,7 @@ var ContactsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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", {
@@ -4611,7 +4740,7 @@ var ContactsResource = class extends Resource {
 		}));
 	}
 	/**
-	* 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({
@@ -4674,7 +4803,7 @@ var SmsResourceBase = class extends Resource {
 var SmsResource = class extends SmsResourceBase {
 	/**
 	* Send one SMS to a single recipient. Supply either `text` (with a `category`)
-	* or a stored `template` (by `id` or `name`, with its `parameters`). The
+	* or a stored `template` (by `id` or `slug`, with its `parameters`). The
 	* result is `accepted`, not yet delivered — read it back with `get` to confirm.
 	*
 	* @example Send free text
@@ -4689,7 +4818,7 @@ var SmsResource = class extends SmsResourceBase {
 	* @example Send by template
 	* await bird.sms.send({
 	*   to: "+14155550100",
-	*   template: { name: "bird_otp_verification", parameters: { code: "123456" } },
+	*   template: { slug: "bird_otp_verification", parameters: { code: "123456" } },
 	* });
 	*/
 	send(params, options) {
@@ -4727,7 +4856,7 @@ var SmsTemplatesResource = class extends Resource {
 	*
 	* @example List the built-in templates
 	* const { data } = await bird.smsTemplates.list({ scope: "system" });
-	* for (const tpl of data) console.log(tpl.id, tpl.name);
+	* for (const tpl of data) console.log(tpl.id, tpl.slug);
 	*/
 	list(query, options) {
 		return this.call("GET", options, ({ signal, headers }) => listSmsTemplates({
@@ -4738,9 +4867,9 @@ var SmsTemplatesResource = class extends Resource {
 		}));
 	}
 	/**
-	* Get one SMS template by its name or id, including its body and the variables it expects. Fetch it before sms_send to see which parameter keys a template send requires.
+	* Get one SMS template by its slug or id, including its body and the variables it expects. Fetch it before sms_send to see which parameter keys a template send requires.
 	*
-	* @example Read one template by name or id
+	* @example Read one template by slug or id
 	* const tpl = await bird.smsTemplates.get("bird_otp_verification");
 	* console.log(tpl.body, tpl.variables);
 	*/
@@ -4821,9 +4950,7 @@ var WhatsappResource = class extends WhatsappResourceBase {
 	*   to: "+15551234567",
 	*   template: {
 	*     slug: "bird_otp",
-	*     components: [
-	*       { type: "body", parameters: [{ type: "text", text: "123456" }] },
-	*     ],
+	*     components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
 	*   },
 	* });
 	* console.log(msg.id, msg.status);
@@ -4880,7 +5007,7 @@ var VoiceResource = class extends Resource {
 //#region src/resources/verifyVerifications.gen.ts
 var VerifyVerificationsResource = class extends Resource {
 	/**
-	* Start a verification: generate a one-time passcode and send it to the recipient in `to` (a phone number over the phone channels enabled for its destination country; an email address over email; or both). It is sent over one channel at a time and fails over to the next in the plan, never over two at once. Calling again for the same recipient reuses the in-progress verification and sends a fresh code after the resend cooldown; it does not start a second one, so use this both to send and to resend. The passcode is never returned; submit what the recipient enters with verify_verifications_check. SMS delivery draws on the workspace's SMS balance.
+	* Start a verification: generate a one-time passcode and send it to the recipient in `to` (a phone number over the phone channels enabled for its destination country; an email address over email; or both). It is sent over one channel at a time and fails over to the next in the plan, never over two at once. Calling again for the same recipient reuses the in-progress verification and sends a fresh code after the resend cooldown; it does not start a second one, so use this both to send and to resend. The passcode is never returned; submit what the recipient enters with verify_verifications_check. SMS, WhatsApp and Telegram delivery all draw on the workspace's balance.
 	*
 	* @example Start a verification over SMS
 	* const verification = await bird.verify.verifications.create({
@@ -5154,6 +5281,46 @@ var RealtimeResource = class extends RealtimeResourceBase {
 	}
 };
 //#endregion
+//#region src/resources/lookup.gen.ts
+var LookupResource = class 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, options) {
+		return this.call("POST", options, ({ signal, headers }) => createPhoneNumberLookup({
+			client: this.client,
+			body: params,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* 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, options) {
+		return this.call("POST", options, ({ signal, headers }) => createEmailLookup({
+			client: this.client,
+			body: params,
+			headers,
+			signal
+		}));
+	}
+};
+//#endregion
 //#region src/client.ts
 const DEFAULT_TIMEOUT_MS = 6e4;
 const DEFAULT_MAX_RETRIES = 2;
@@ -5227,6 +5394,8 @@ var BirdClient = class {
 	contactProperties;
 	/** Sending domains — `bird.domains.create(...)`, `.list(...)`, `.verify(...)`, … */
 	domains;
+	/** Recipient intelligence — `bird.lookup.email(...)`, `.phoneNumber(...)`. Every answer is billed. */
+	lookup;
 	/** Webhooks — `bird.webhooks.unwrap(payload, headers)` verifies an inbound delivery. */
 	webhooks;
 	/** Realtime — `bird.realtime.publish(...)`, `.channels.list(...)`, `.members.disconnect(...)`, … */
@@ -5238,9 +5407,9 @@ var BirdClient = class {
 		this.#headers = {
 			...opts.defaultHeaders,
 			Authorization: `Bearer ${opts.apiKey}`,
-			"User-Agent": `bird-sdk-js/0.27.0`,
+			"User-Agent": `bird-sdk-js/0.29.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.27.0"
+			"Bird-Version": "0.29.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;
@@ -5275,6 +5444,7 @@ var BirdClient = class {
 		this.audiences = new AudiencesResource(this.core, this.#client);
 		this.contactProperties = new ContactPropertiesResource(this.core, this.#client);
 		this.domains = new DomainsResource(this.core, this.#client);
+		this.lookup = new LookupResource(this.core, this.#client);
 		this.webhooks = new WebhooksResource(opts.webhooks);
 		this.realtime = new RealtimeResource(this.core, this.#client);
 	}
@@ -5407,6 +5577,54 @@ const EmailEventType = {
 	EmailUnsubscribed: "email.unsubscribed"
 };
 /**
+* 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.
+*/
+const EmailLookupFlag = {
+	Disposable: "disposable",
+	FreeProvider: "free_provider",
+	Role: "role"
+};
+/**
+* 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.
+*/
+const EmailLookupReason = {
+	InvalidDomain: "invalid_domain",
+	InvalidRecipient: "invalid_recipient",
+	InvalidSyntax: "invalid_syntax"
+};
+/**
+* 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.
+*/
+const EmailLookupResult = {
+	Neutral: "neutral",
+	Risky: "risky",
+	Typo: "typo",
+	Undeliverable: "undeliverable",
+	Valid: "valid"
+};
+/**
+* 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.
+*/
+const LookupFlag = { Ported: "ported" };
+/**
+* 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.
+*/
+const LookupPropertyStatus = {
+	Inconclusive: "inconclusive",
+	Ok: "ok",
+	Unavailable: "unavailable"
+};
+/**
 * 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
 * these with a `default` branch rather than treating the set as closed.
@@ -5425,6 +5643,28 @@ const SMSErrorCode = {
 	Unreachable: "unreachable"
 };
 /**
+* Values of TemplateLanguageStatus 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.
+*/
+const TemplateLanguageStatus = {
+	Draft: "draft",
+	Live: "live",
+	Superseded: "superseded"
+};
+/**
+* Values of TemplateStatus 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.
+*/
+const TemplateStatus = {
+	Active: "active",
+	Draft: "draft",
+	Inactive: "inactive",
+	Pending: "pending",
+	Rejected: "rejected"
+};
+/**
 * Values of VerificationAttemptFailureReason 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.
@@ -5446,6 +5686,7 @@ const VerificationAttemptFailureReason = {
 const VerificationChannel = {
 	Email: "email",
 	Sms: "sms",
+	Telegram: "telegram",
 	Whatsapp: "whatsapp"
 };
 /**
@@ -5472,6 +5713,19 @@ const WhatsAppErrorCode = {
 	Undeliverable: "undeliverable"
 };
 /**
+* Values of WhatsAppEventType 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.
+*/
+const WhatsAppEventType = {
+	WhatsappAccepted: "whatsapp.accepted",
+	WhatsappDelivered: "whatsapp.delivered",
+	WhatsappFailed: "whatsapp.failed",
+	WhatsappRead: "whatsapp.read",
+	WhatsappRejected: "whatsapp.rejected",
+	WhatsappSent: "whatsapp.sent"
+};
+/**
 * Values of WhatsAppTemplateCategory 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.
@@ -5495,6 +5749,6 @@ const WhatsAppTemplateParameterType = {
 	Video: "video"
 };
 //#endregion
-export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, SMSErrorCode, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
+export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, EmailLookupFlag, EmailLookupReason, EmailLookupResult, LookupFlag, LookupPropertyStatus, SMSErrorCode, TemplateLanguageStatus, TemplateStatus, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppEventType, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
 
 //# sourceMappingURL=index.mjs.map