telnyx 5.169.0 → 5.171.0

data/rbi/telnyx/resources/dir.rbi

@@ -47,17 +47,21 @@ module Telnyx
       # Edit a DIR. DIRs in `draft`, `rejected`, `unsuccessful`, or `suspended` can be
       # edited freely: PATCH is a pure edit, `status` is never changed, and you re-vet
       # by calling `POST /v2/dir/{dir_id}/submit` explicitly. A `verified` DIR can also
-      # be edited in place: a PATCH that changes any value returns the DIR to `draft`
-      # and branded delivery stops until you re-submit and the DIR is approved again,
-      # while a PATCH that changes nothing (an empty body or values identical to the
-      # current ones) leaves the DIR `verified`, so idempotent retries are safe. DIRs in
-      # any other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
+      # be edited in place: a PATCH that changes any value returns the DIR to `draft`;
+      # the currently approved identity keeps displaying, and the edited content goes
+      # live only after you re-submit and the DIR is approved again. A PATCH that
+      # changes nothing (an empty body or values identical to the current ones) leaves
+      # the DIR `verified`, so idempotent retries are safe. Changing only
+      # `bpo_authorizations` or `webhook_url` is the exception: the DIR stays
+      # `verified`. Each BPO authorization is reviewed on its own instead. DIRs in any
+      # other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
       # `permanently_rejected`) cannot be edited.
       sig do
         params(
           dir_id: String,
           authorizer_email: String,
           authorizer_name: String,
+          bpo_authorizations: T::Array[Telnyx::BpoAuthorizationInput::OrHash],
           call_reasons: T::Array[String],
           certify_brand_is_accurate: T::Boolean,
           certify_ip_ownership: T::Boolean,
@@ -66,6 +70,7 @@ module Telnyx
           documents: T::Array[Telnyx::Document::OrHash],
           logo_url: String,
           reselling: T::Boolean,
+          webhook_url: T.nilable(String),
           request_options: Telnyx::RequestOptions::OrHash
         ).returns(Telnyx::DirWrapped)
       end
@@ -78,6 +83,13 @@ module Telnyx
         # Name of the person at your enterprise authorizing this DIR. Must be a real
         # individual.
         authorizer_name: nil,
+        # Optional. Replace this DIR's authorized BPO (Business Process Outsourcer)
+        # accounts with these, each with its signed Letter of Authorization. The supplied
+        # list replaces the current one: a BPO left out has its authorization removed, and
+        # a new BPO (or a changed Letter of Authorization) is created `pending` admin
+        # review. Send an empty list to clear all authorizations; omit the field to leave
+        # them unchanged. Editing this list does not re-vet the DIR. Maximum 10.
+        bpo_authorizations: nil,
         # 1–10 reasons your business calls customers. Validate phrasing against
         # `POST /call_reasons/validate`.
         call_reasons: nil,
@@ -102,6 +114,10 @@ module Telnyx
         # Set to true if your organization places calls on behalf of other enterprises
         # (BPO/reseller). Updating this triggers re-vetting on next submit.
         reselling: nil,
+        # Optional `https://` URL that receives webhook notifications when this DIR's
+        # compliance review completes. Send `null` to clear. Changing only this field on a
+        # `verified` DIR does not re-vet it. Maximum 2048 characters.
+        webhook_url: nil,
         request_options: {}
       )
       end
@@ -153,14 +169,18 @@ module Telnyx
       )
       end
 
-      # Delete a DIR. Failure modes: `400` if a child phone number is in a non-deletable
-      # status, `409` if the DIR has an unresolved infringement claim, `404` if the DIR
-      # is not yours.
+      # Request deletion of a DIR. This does not remove the DIR on this call: it records
+      # the request, moves the DIR to `delete_requested`, and Telnyx completes the
+      # removal (de-registration and cleanup) shortly after. A verified DIR keeps
+      # serving its branded identity, and keeps billing, until the removal is executed.
+      # Failure modes: `400` if a child phone number is still attached or the DIR is
+      # `in_review` (wait for the review to finish), `409` if the DIR has an unresolved
+      # infringement claim, `404` if the DIR is not yours.
       sig do
         params(
           dir_id: String,
           request_options: Telnyx::RequestOptions::OrHash
-        ).void
+        ).returns(Telnyx::Models::DirDeleteResponse)
       end
       def delete(
         # The DIR id. Lowercase UUID.
@@ -169,6 +189,40 @@ module Telnyx
       )
       end
 
+      # The Letter of Authorization in which a Brand Owner authorizes an approved BPO
+      # (Business Process Outsourcer) to place branded calls that display this DIR on
+      # the owner's behalf. Both parties are read from the caller's account: the Brand
+      # Owner is the enterprise that owns the DIR, and the BPO is `bpo_enterprise_id`.
+      # No business identity is accepted in the body.
+      #
+      # When `signature` is omitted the PDF is returned unsigned so the Brand Owner can
+      # sign it externally and the BPO can upload it via the Documents API. When
+      # `signature` is present the PDF embeds the supplied image, printed name, and
+      # signed-at date.
+      #
+      # Returns `application/pdf`.
+      sig do
+        params(
+          dir_id: String,
+          bpo_enterprise_id: String,
+          signature: Telnyx::SignaturePayload::OrHash,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(StringIO)
+      end
+      def bpo_loa(
+        # The DIR id.
+        dir_id,
+        # The approved BPO enterprise the Brand Owner is authorizing. Must be a BPO
+        # account on the caller's organization that has already been approved.
+        bpo_enterprise_id:,
+        # Optional. When provided the rendered PDF embeds the signature image, printed
+        # name, and signed-at date. When absent the PDF is returned unsigned so the Brand
+        # Owner can sign externally and the BPO can upload it via the Documents API.
+        signature: nil,
+        request_options: {}
+      )
+      end
+
       # Reference list of `document_type` values accepted by
       # `DirCreateRequest.documents[].document_type` and the infringement-contest
       # endpoint. Each entry has a stable `short_name` (used in API calls) and a
@@ -223,7 +277,7 @@ module Telnyx
           dir_id: String,
           phone_numbers: T::Array[String],
           agent: Telnyx::Enterprises::Reputation::AgentInput::OrHash,
-          signature: Telnyx::DirNewLoaParams::Signature::OrHash,
+          signature: Telnyx::SignaturePayload::OrHash,
           request_options: Telnyx::RequestOptions::OrHash
         ).returns(StringIO)
       end
@@ -233,8 +287,9 @@ module Telnyx
         # Telephone numbers to authorize on the DIR, in `+E164` format (`+` followed by
         # 10-15 digits). Max 15 per request.
         phone_numbers:,
-        # Third-party reseller / partner managing the enterprise's phone numbers. Omit
-        # when the enterprise works directly with Telnyx.
+        # Third-party reseller / partner managing the enterprise's phone numbers on its
+        # behalf, such as a call center (BPO) acting for a client. Omit when the
+        # enterprise manages its own numbers.
         agent: nil,
         # Optional. When provided the rendered PDF embeds the signature image, printed
         # name, and signed-at date. When absent the PDF is returned unsigned so the
@@ -244,6 +299,37 @@ module Telnyx
       )
       end
 
+      # List the BPO (Business Process Outsourcer) accounts a Brand Owner has authorized
+      # on this DIR, together with the review state of each authorization.
+      #
+      # Authorizations are supplied as the `bpo_authorizations` array when creating or
+      # updating a DIR, and each one is reviewed on its own. Only an `approved`
+      # authorization adds that BPO to this DIR's authorized callers in the branded
+      # calling registry; `pending` and `rejected` authorizations do not. Each entry
+      # includes the `loa_document_id` you submitted: because `bpo_authorizations`
+      # replaces the whole list on every DIR update, send each entry you want to keep
+      # back with its `loa_document_id` unchanged, and it keeps its review state. A
+      # rejected entry carries a `rejection_reason`. Returns an empty list when the DIR
+      # has authorized no BPOs.
+      sig do
+        params(
+          dir_id: String,
+          page_number: Integer,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::DirRetrieveBpoAuthorizationsResponse)
+      end
+      def retrieve_bpo_authorizations(
+        # The DIR id. Lowercase UUID.
+        dir_id,
+        # 1-based page number. Out-of-range values return an empty page with correct meta.
+        page_number: nil,
+        # Items per page. Maximum 250; values above are clamped to 250.
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
       # Submit a DIR for vetting. Sends the DIR back through the vetting cycle from any
       # non-terminal status. When re-submitting from `suspended` or `expired`, the DIR's
       # previous Branded Calling registration is torn down transactionally and its phone
@@ -252,7 +338,7 @@ module Telnyx
       #
       # Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `400`
       # if the DIR's business and financial references have not been submitted. Returns
-      # `409` if the DIR has an unresolved infringement claim.
+      # `400` if the DIR has an unresolved infringement claim.
       sig do
         params(
           dir_id: String,
@@ -298,13 +384,16 @@ module Telnyx
         certify_brand_is_accurate:,
         # Must be `true`.
         certify_ip_ownership:,
-        # Must be `true`.
+        # Check to certify that the brand no longer infringes anyone else's trademark or
+        # intellectual property.
         certify_no_infringement:,
         # Must be `true`.
         certify_no_shaft_content:,
         # Explanation of how the infringement concern was addressed.
         infringement_resolution_notes:,
         call_reasons: nil,
+        # The business name shown to call recipients, 1 to 35 characters, no emoji, not
+        # blank.
         display_name: nil,
         # Append-only supporting documents to attach while resolving the claim (e.g.
         # authorization or licensing proof).

data/rbi/telnyx/resources/email_blocks/imports.rbi

@@ -13,9 +13,23 @@ module Telnyx
         # - header-only / all-blank / undetectable provider → `400` Returns `202` with the
         #   import record (status `pending`); an Oban worker (`EmailBlockImportWorker`,
         #   max_attempts 3) transitions `pending → processing → completed | failed`.
-        #   `block_ttl_days` applies only to imported `manual_block` rows; other reasons
-        #   get `expires_at: nil`. Provider is auto-detected from the CSV header
-        #   (`sendgrid` / `mailgun` / `ses` / `generic`).
+        #
+        # Native Telnyx exports are detected by the stable first-12-column header
+        # signature (`id` … `group_id`) and are restored with their original `from`,
+        # `domain_id`, `group_id`, `source`, `status`, `expires_at`, plus
+        # `bounce_category`, `dsn_code`, and `meta` when present (`scope` is re-derived
+        # from `domain_id`/`from`; the exported `scope` cell must be a valid enum value).
+        # Lifecycle changes reconcile through the same create path as the API: a row
+        # already in the requested state restores its mutable backup fields without a new
+        # audit event, and a real transition (e.g. tombstone → active) appends the
+        # matching lifecycle event. `block_ttl_days` is not applied to native rows — their
+        # exported `expires_at` is preserved verbatim.
+        #
+        # Competitor and generic imports (SendGrid / Mailgun / SES / generic) remain
+        # account-scoped (`from`, `domain_id`, `group_id`, `scope` are not read) and
+        # `block_ttl_days` applies only to imported `manual_block` rows; other reasons get
+        # `expires_at: nil`. Provider is auto-detected from the CSV header (`sendgrid` /
+        # `mailgun` / `ses` / `generic`).
         sig do
           params(
             file: Telnyx::Internal::FileInput,

data/rbi/telnyx/resources/email_blocks.rbi

@@ -158,9 +158,11 @@ module Telnyx
       # stream `ORDER BY created_at ASC, id ASC` with no pagination.
       #
       # CSV columns:
-      # `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id`.
-      # The CSV carries the `group_id` column so group-scoped suppressions' group link
-      # survives the export (empty for account-scope rows).
+      # `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id,bounce_category,dsn_code, meta`
+      # (15 columns). The first 12 columns are the stable native signature;
+      # `bounce_category`, `dsn_code`, and `meta` are optional backup fields (empty when
+      # unset). The CSV carries the `group_id` column so group-scoped suppressions'
+      # group link survives the export (empty for account-scope rows).
       sig do
         params(
           filter_created_after: Time,

data/rbi/telnyx/resources/email_domains.rbi

@@ -167,6 +167,28 @@ module Telnyx
       )
       end
 
+      # Generates a new DKIM key for the domain, activates it, and retires the previous
+      # key. The response includes the updated DKIM DNS records the customer must
+      # publish. Selectors are fixed, so rotation replaces the TXT value at the existing
+      # `<selector>._domainkey.<domain>` host rather than adding a second record —
+      # `old_selector_retained` is false and the new TXT value must be published
+      # promptly, since signing switches to the new key immediately and the old TXT
+      # value will no longer match. The previous key is retired to a `retiring` state
+      # (retained, not revoked) so it can be revoked after the DNS propagation grace
+      # period.
+      sig do
+        params(
+          domain_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailDomainRotateDkimResponse)
+      end
+      def rotate_dkim(
+        # Email domain UUID
+        domain_id,
+        request_options: {}
+      )
+      end
+
       # Checks the published DNS records against the records required for the email
       # domain and returns the latest verification results.
       sig do

data/rbi/telnyx/resources/email_events.rbi

@@ -5,21 +5,30 @@ module Telnyx
     # Retrieve account-level email events and event statistics.
     class EmailEvents
       # Lists account-level email events sorted oldest first by
-      # `occurred_at asc, id asc`.
+      # `occurred_at asc, id asc`. Each row contains a legacy email.-prefixed event_type
+      # and an additive canonical_event_type. Gateway rejection renders email.failed
+      # with canonical email.gw_reject; ambiguous injection timeout renders
+      # email.injection_timeout in both; MTA expiration renders email.bounced with
+      # canonical email.expired. Message-scoped queued, sending, sandbox, cancelled, and
+      # daily_limit_exceeded rows fan out per durable recipient with stable derived IDs
+      # matching webhook delivery. Scheduled is the cardinality exception: account
+      # polling retains one message-scoped scheduled row with its stored event ID, while
+      # scheduled webhook publication fans out per recipient with derived IDs; reconcile
+      # scheduled events by message ID, event type, and occurrence time rather than
+      # event UUID. Recipient-scoped stored rows retain their stored UUIDs across
+      # polling and webhook delivery. Legacy names are derived from stored rows; an
+      # AdminBounce row stored as failed renders email.failed in polling while its
+      # webhook retains email.bounced, both with canonical email.failed.
       sig do
         params(
           email_id: String,
           event_type: Telnyx::EmailEventListParams::EventType::Variants,
           from: Time,
-          page_cursor: String,
           page_size: Integer,
+          page_cursor: String,
           to: Time,
           request_options: Telnyx::RequestOptions::OrHash
-        ).returns(
-          Telnyx::Internal::EmailCursorPagination[
-            Telnyx::Models::EmailEventListResponse
-          ]
-        )
+        ).returns(Telnyx::Models::EmailEventListResponse)
       end
       def list(
         # Filter events for a specific email message UUID. Invalid UUID values are
@@ -28,14 +37,26 @@ module Telnyx
         # Comma-separated list of event types to include. Also accepts repeated query
         # parameters (e.g. event_type=delivered&event_type=bounced). Unknown values return
         # no matches.
+        #
+        # Dual-name compatibility: values are accepted bare or `email.`-prefixed. A legacy
+        # value keeps matching the rows it matched pre-rename — no widening: `failed` also
+        # matches the rows that now store the canonical names of the outcomes it covered
+        # (`gw_reject`, `injection_timeout`, `expired`); `bounced` matches stored
+        # `bounced` rows only (recipient-scoped Expirations stored `failed` pre-rename and
+        # never matched `bounced`, so `expired` is deliberately not a `bounced`
+        # expansion). A canonical value matches its own rows plus legacy rows whose
+        # recorded payload evidence proves that outcome (`expired` also surfaces legacy
+        # `bounced` rows with `bounce_category: transient`). The additive
+        # `canonical_event_type` field in each response row names the canonical outcome.
         event_type: nil,
         # Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when omitted.
         from: nil,
-        # Opaque URL-safe Base64 cursor returned by a previous list response.
-        page_cursor: nil,
         # Number of results to return. Defaults to 25; maximum is 100. Invalid values are
         # clamped to the valid range.
         page_size: nil,
+        # Opaque URL-safe Base64 cursor returned by a previous event list response. The
+        # legacy `page[after]` and flat `page_cursor` forms are also accepted.
+        page_cursor: nil,
         # Inclusive ISO 8601 end timestamp. When `from` is provided without `to`, defaults
         # to `from + 30 days`.
         to: nil,

data/rbi/telnyx/resources/email_messages.rbi

@@ -102,7 +102,9 @@ module Telnyx
         in_reply_to_message_id: nil,
         # Body param
         inline_css: nil,
-        # Body param: Custom metadata. Write-only; not returned in responses.
+        # Body param: Custom metadata key/value pairs. Stored on the message, returned on
+        # message responses, and propagated to Email Detail Records. Usable in
+        # `filter[metadata]` when listing messages.
         metadata: nil,
         # Body param: Reply-to address. If provided as an object with a name, only the
         # email is stored; the name is ignored.
@@ -116,12 +118,37 @@ module Telnyx
         #
         # Only meaningful alongside `in_reply_to_message_id`.
         reply_to_all: nil,
-        # Body param
+        # Body param: Validates and accepts the message without injecting it into the MTA
+        # or outbound Kafka path. Nothing is delivered: sandbox records are non-billable,
+        # consume no daily-send-limit quota, and feed no delivery-reputation signals.
+        #
+        # The reserved sandbox test-recipient domain is `test.telnyx.com`. In sandbox
+        # mode, these addresses produce deterministic recipient-scoped lifecycle events:
+        #
+        # - `delivered@test.telnyx.com`: queued -> sending -> sent -> delivered
+        # - `hard-bounce@test.telnyx.com`: queued -> sending -> sent -> bounced
+        #   (permanent)
+        # - `soft-bounce@test.telnyx.com`: queued -> sending -> sent -> bounced
+        #   (transient)
+        # - `complaint@test.telnyx.com`: queued -> sending -> sent -> complained
+        # - `suppressed@test.telnyx.com`: queued -> suppressed
+        # - `invalid@test.telnyx.com`: queued -> sending -> failed (invalid recipient)
+        # - `dkim-fail@test.telnyx.com`: queued -> sending -> failed (DKIM unavailable)
+        # - `rate-limit@test.telnyx.com`: queued -> sending -> failed (rate limit
+        #   exceeded)
+        #
+        # Matching is case-insensitive for both the local part and the domain and requires
+        # the exact domain `test.telnyx.com` — subdomains and other domains do not match.
+        # Mixed sandbox sends simulate only reserved test recipients; other recipients
+        # retain ordinary sandbox behavior (accepted, no delivery attempted). Hard-bounce
+        # and complaint outcomes also use the normal automatic-suppression pipeline.
+        # Non-sandbox sends to these addresses use the normal delivery path.
         sandbox_mode: nil,
-        # Body param: Future ISO 8601 time to schedule sending. Invalid or past timestamps
-        # are silently ignored and the email is sent immediately. The legacy alias
-        # `send_at` is still accepted for backward compatibility; when both are provided,
-        # `scheduled_at` wins.
+        # Body param: Future ISO 8601 delivery time. Invalid or non-future timestamps are
+        # rejected. Single sends return HTTP 422; in batch sends the invalid item is
+        # reported in the 207 per-item errors while other items continue. `send_at`
+        # remains a deprecated request alias. A non-null `scheduled_at` takes precedence
+        # over `send_at`; when `scheduled_at` is omitted or null, `send_at` is used.
         scheduled_at: nil,
         # Body param: Deprecated alias for `scheduled_at`.
         send_at: nil,
@@ -129,14 +156,18 @@ module Telnyx
         # the template's subject is rendered; if the template has no subject or renders
         # empty, the request returns 400.
         subject: nil,
-        # Body param: Tags for categorization and reporting. Stored on the message and
-        # propagated to Email Detail Records. Not returned in API responses.
+        # Body param: Tags for categorization and filtering. Stored on the message,
+        # returned on message responses, and propagated to Email Detail Records. Usable in
+        # `filter[tags]` when listing messages.
         tags: nil,
         # Body param
         template_id: nil,
         # Body param: Variables for Liquid template rendering. Non-object values may cause
         # a 422 validation error on message creation, but are silently treated as an empty
-        # object for template rendering.
+        # object for template rendering. When the template enables `strict_variables`, a
+        # missing required variable fails the request with 422 (single send) or a per-item
+        # `unprocessable_entity` error (batch) naming the variable; no message is
+        # persisted for the failed item.
         template_variables: nil,
         # Body param: Plain text email body. Returned only by `GET /email_messages/{id}`;
         # omitted from create and list responses.
@@ -163,7 +194,7 @@ module Telnyx
         params(
           id: String,
           request_options: Telnyx::RequestOptions::OrHash
-        ).returns(Telnyx::Models::EmailMessageRetrieveResponse)
+        ).returns(Telnyx::EmailMessageDetailResponse)
       end
       def retrieve(
         # Email message UUID.
@@ -172,11 +203,13 @@ module Telnyx
       )
       end
 
-      # Lists messages sorted newest first by `created_at desc, id desc`. No filters
-      # other than cursor pagination are implemented. The legacy `/v2/emails` GET route
-      # is a backward-compatible alias for this operation.
+      # Lists messages sorted newest first by `created_at desc, id desc`. Tags and
+      # metadata filters compose with cursor pagination. The legacy `/v2/emails` GET
+      # route is a backward-compatible alias for this operation.
       sig do
         params(
+          filter_metadata: String,
+          filter_tags: String,
           page_cursor: String,
           page_size: Integer,
           request_options: Telnyx::RequestOptions::OrHash
@@ -187,6 +220,19 @@ module Telnyx
         )
       end
       def list(
+        # Metadata containment filter, supplied as a JSON object or comma-separated
+        # `key=value` pairs. All supplied key/value pairs must be contained in the message
+        # metadata. An empty value or empty JSON object omits the filter. Malformed
+        # values, valid non-object JSON, pairs without `=`, empty keys, and
+        # non-string/nested query shapes return HTTP 400.
+        filter_metadata: nil,
+        # Comma-separated tags. Each segment is trimmed, and messages having at least one
+        # supplied tag are returned; matching is exact and case-sensitive after trimming.
+        # Because commas delimit values and surrounding whitespace is removed, this filter
+        # cannot represent stored tags containing literal commas or leading/trailing
+        # whitespace. An empty value omits the filter. Empty segments and
+        # non-string/nested query shapes return HTTP 400.
+        filter_tags: nil,
         # Opaque URL-safe Base64 cursor returned by a previous list response.
         page_cursor: nil,
         # Number of results to return. Defaults to 25; maximum is 100. Invalid values are
@@ -214,7 +260,10 @@ module Telnyx
       # checks run first and can reject the whole batch before message creation. After
       # those checks pass, each message is validated and sent independently; item-level
       # failures do not affect other messages, and the processed batch returns 207
-      # Multi-Status.
+      # Multi-Status. Per-message failures include validation errors; when a template
+      # has `strict_variables` enabled, a missing required variable produces a per-item
+      # `unprocessable_entity` error naming that variable while the other messages
+      # continue.
       sig do
         params(
           messages: T::Array[Telnyx::EmailMessageBatchParams::Message::OrHash],
@@ -228,8 +277,13 @@ module Telnyx
         # request. Each message is validated and sent independently; per-message failures
         # do not affect other messages in the batch.
         messages:,
-        # Body param: Applies sandbox mode to all messages in the batch. Overrides any
-        # per-message sandbox_mode in the messages array.
+        # Body param: Applies sandbox mode to all messages in the batch and overrides any
+        # per-message `sandbox_mode` value — each message's effective `sandbox_mode` is
+        # exactly this envelope value. Reserved recipients at `test.telnyx.com` produce
+        # the deterministic event chains documented on CreateEmailRequest.sandbox_mode; no
+        # batch item is injected into the MTA or outbound Kafka path. Sandbox batch items
+        # are non-billable, consume no daily-send-limit quota, and feed no
+        # delivery-reputation signals.
         sandbox_mode: nil,
         # Header param: Optional opaque, unquoted key for safely retrying the same logical
         # request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
@@ -280,6 +334,15 @@ module Telnyx
       # Lists events for a single message sorted oldest first by
       # `occurred_at asc, id asc`. The legacy `/v2/emails/{id}/events` GET route is a
       # backward-compatible alias.
+      #
+      # For compatibility, each event carries the legacy customer-visible `event_type`
+      # (`email.`-prefixed), the additive `canonical_event_type` (`email.`-prefixed),
+      # and the deprecated `type` duplicate — whose value keeps the exact legacy format:
+      # the bare stored event name, never `email.`-prefixed. Gateway rejections render
+      # `email.failed` + canonical `email.gw_reject`; MTA expirations render
+      # `email.bounced` + canonical `email.expired`; every unchanged outcome carries
+      # identical `event_type` and `canonical_event_type` values (and `type` keeps the
+      # stored name).
       sig do
         params(
           email_id: String,
@@ -300,6 +363,27 @@ module Telnyx
       )
       end
 
+      # Moves an existing scheduled email to a new future send time. Only the delivery
+      # time (`scheduled_at`) changes; the message ID, content, recipients, tags, and
+      # metadata remain unchanged. Returns `409 Conflict` if the message is no longer
+      # scheduled or its scheduled-send worker has already started processing it. This
+      # route emits no dedicated `rescheduled` event.
+      sig do
+        params(
+          email_id: String,
+          scheduled_at: Time,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailMessageDetailResponse)
+      end
+      def update_schedule(
+        # Email message UUID.
+        email_id,
+        # New ISO 8601 delivery time. Must be strictly in the future.
+        scheduled_at:,
+        request_options: {}
+      )
+      end
+
       # @api private
       sig { params(client: Telnyx::Client).returns(T.attached_class) }
       def self.new(client:)