telnyx 5.158.0 → 5.159.0

data/rbi/telnyx/resources/dir/references.rbi

@@ -13,9 +13,29 @@ module Telnyx
         # endpoint). Until it is, this returns `409` and no references are stored.
         #
         # The request body carries exactly two business references plus one financial
-        # reference. On success the references are stored and the response echoes them in
-        # the same shape as the GET. Submitting again converges on the already-stored
-        # references rather than erroring.
+        # reference. The first submission stores them and returns `201`. Resubmitting
+        # returns `200`: identical values are simply confirmed and nothing is written,
+        # while changed values replace those references.
+        #
+        # Replacing a reference is allowed only while the DIR itself is still editable,
+        # the same window in which a single reference may be updated; once the DIR has
+        # been submitted for vetting this returns `400`. A replaced reference's pending
+        # verification call is cancelled and its dial-in code stops working, and the
+        # replacement contact is emailed fresh scheduling details. References whose
+        # details did not change keep their existing call, code, and the notice already
+        # sent to them.
+        #
+        # The response always echoes the stored references in the same shape as the GET.
+        #
+        # Who qualifies: the two business references confirm the company's reputation and
+        # operations. Each should be a senior contact at an organization the business
+        # works with, such as a vendor, partner, or client: a C-suite executive (CEO, CFO,
+        # CTO, COO), an owner or founder as reflected in the company's corporate records,
+        # or a senior manager, director, or executive. The financial reference confirms
+        # the company pays its bills and should be a licensed certified public accountant
+        # (CPA) the company uses, a contact at a bank or financial institution that has a
+        # relationship with the company, or a reasonable alternative banking or financial
+        # reference.
         sig do
           params(
             dir_id: String,
@@ -27,7 +47,13 @@ module Telnyx
         def create(
           # The DIR id. Lowercase UUID.
           dir_id,
-          # Exactly two business references.
+          # Exactly two business references. Array order determines each one's slot: the
+          # first entry becomes slot 1 and the second becomes slot 2. Those slots are what
+          # you pass when updating a single reference later. Each should be a senior contact
+          # who can speak to your company's reputation and operations: a C-suite executive
+          # (CEO, CFO, CTO, COO), an owner or founder as reflected in your corporate
+          # records, or a senior manager, director, or executive at an organization you work
+          # with, such as a vendor, partner, or client.
           business_references:,
           # One reference supplied at submit. The reference type is implied by the field
           # that carries it (business_references vs financial_reference).
@@ -60,8 +86,11 @@ module Telnyx
           ).returns(Telnyx::Models::Dir::ReferenceUpdateResponse)
         end
         def update(
-          # Path param: Reference slot. Business references use slots 0 and 1; the financial
-          # reference uses slot 0.
+          # Path param: Reference slot, counting from 1. Business references are slots 1 and
+          # 2, matching the order they were sent in the `business_references` array; the
+          # financial reference is slot 1. Every reference returned by the submit and list
+          # endpoints carries its own `ref_type` and `slot`, so you do not need to derive
+          # them.
           slot,
           # Path param: The DIR id. Lowercase UUID.
           dir_id:,
@@ -87,10 +116,12 @@ module Telnyx
 
         # List the business and financial references submitted for a DIR.
         #
-        # Returns the two business references (slots 0 and 1) followed by the single
-        # financial reference. Each entry carries only the customer-supplied details
-        # (name, title, organization, relationship, phone, email, timezone). Returns an
-        # empty list when no references were submitted.
+        # Returns the two business references (slots 1 and 2) followed by the single
+        # financial reference. Each entry carries its `ref_type` and `slot`, which
+        # together address the reference when updating it, alongside the details supplied
+        # when it was submitted (name, title, organization, relationship, phone, email,
+        # timezone). No internal identifiers are exposed. Returns an empty list when no
+        # references were submitted.
         sig do
           params(
             dir_id: String,

data/rbi/telnyx/resources/dir.rbi

@@ -250,8 +250,9 @@ module Telnyx
       # numbers flip back to `submitted`. When re-submitting from `verified`, the
       # existing registration stays live throughout the new vetting cycle.
       #
-      # Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `409`
-      # if the DIR has an unresolved infringement claim.
+      # 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.
       sig do
         params(
           dir_id: String,

data/rbi/telnyx/resources/email_blocks/import.rbi

@@ -0,0 +1,61 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailBlocks
+      # Async CSV import of competitor suppression lists.
+      class Import
+        # Accepts `multipart/form-data` with a `file` field (the CSV) and an optional
+        # `block_ttl_days` (integer >0, default 30). Validates:
+        #
+        # - content ≤ 25 MiB, else `413`
+        # - row count ≤ 250 000, else `413`
+        # - 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`).
+        sig do
+          params(
+            file: Telnyx::Internal::FileInput,
+            block_ttl_days: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailBlocks::EmailBlockImportResponse)
+        end
+        def create(
+          # The CSV file (Plug.Upload). Missing/non-upload → 400.
+          file:,
+          # TTL for imported `manual_block` rows; other reasons get `expires_at: null`.
+          # Invalid/missing → falls back to 30.
+          block_ttl_days: nil,
+          request_options: {}
+        )
+        end
+
+        # Account-scoped fetch (cross-account → 404; malformed UUID → 404). Nullable
+        # fields are omitted until terminal: `provider`/`completed_at` when nil;
+        # `processed_rows`/`created_count`/`existing_count`/ `skipped_count`/`error_count`
+        # only when `status == completed`; `errors` only when non-empty; `failure_reason`
+        # only on terminal failure.
+        sig do
+          params(
+            id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailBlocks::EmailBlockImportResponse)
+        end
+        def retrieve(
+          # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+          id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_blocks.rbi

@@ -0,0 +1,198 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Recipient suppression records (`/v2/email_blocks`).
+    class EmailBlocks
+      # Async CSV import of competitor suppression lists.
+      sig { returns(Telnyx::Resources::EmailBlocks::Import) }
+      attr_reader :import
+
+      # Creates a suppression with `reason: manual_block` and `source: manual`.
+      # Caller-supplied `reason` / `source` are **ignored**; `scope` is **derived**
+      # server-side from `domain_id` / `from` and is never trusted. Idempotent: if a
+      # matching row already exists (NULL-safe dedupe key: account_id, scope, to,
+      # reason, domain_id, from), returns the existing record with `200` (no new audit
+      # event).
+      #
+      # `bounce_category`, `dsn_code`, `meta`, and `group_id` are **not accepted** on
+      # the public surface. Use the unsubscribe-group suppression endpoint or the
+      # internal create surface for those.
+      sig do
+        params(
+          to: String,
+          domain_id: T.nilable(String),
+          expires_at: T.nilable(Time),
+          from: T.nilable(String),
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailBlockResponse)
+      end
+      def create(
+        # Recipient address (normalized: trim + lower-case).
+        to:,
+        # `null` ⇒ account scope.
+        domain_id: nil,
+        expires_at: nil,
+        # Sender address (normalized). `null` ⇒ account/domain scope.
+        from: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a suppression
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailBlockResponse)
+      end
+      def retrieve(
+        # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+        id,
+        request_options: {}
+      )
+      end
+
+      # Account-scoped list. Two mutually exclusive pagination modes:
+      #
+      # - **Offset**: `page[number]` (default 1) + `page[size]` (default 25, max 100).
+      #   `meta` contains `total_pages`.
+      # - **Cursor**: `page[after]` and/or `page[before]` (opaque `Base.url_encode64` of
+      #   `{"created_at","id"}`). Cannot combine with `page[number]`; `after`+`before`
+      #   together is an error. `meta` contains `next_cursor` / `previous_cursor`
+      #   (omitted when their flag is false).
+      #
+      # Sort defaults to `-created_at` (desc); only `created_at` is sortable. A `--`
+      # prefix is an error. `nil`/empty filter values are silently dropped.
+      sig do
+        params(
+          filter_created_after: Time,
+          filter_created_before: Time,
+          filter_domain_id: String,
+          filter_reason: Telnyx::EmailBlockListParams::FilterReason::OrSymbol,
+          page_after: String,
+          page_before: String,
+          page_number: Integer,
+          page_size: Integer,
+          sort: Telnyx::EmailBlockListParams::Sort::OrSymbol,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Internal::DefaultFlatPagination[Telnyx::EmailBlock])
+      end
+      def list(
+        # `created_at > value` (ISO 8601).
+        filter_created_after: nil,
+        # `created_at < value` (ISO 8601).
+        filter_created_before: nil,
+        # Exact-match filter on domain_id (UUID).
+        filter_domain_id: nil,
+        # Exact-match filter on reason.
+        filter_reason: nil,
+        # Opaque cursor (`Base.url_encode64` of `{"created_at","id"}`). Cursor mode;
+        # mutually exclusive with `page[number]` and `page[before]`.
+        page_after: nil,
+        # Opaque cursor (see `page[after]`). Mutually exclusive with `page[after]` and
+        # `page[number]`.
+        page_before: nil,
+        # Offset page number (≥1, default 1).
+        page_number: nil,
+        # Page size (1–100, default 25).
+        page_size: nil,
+        # Sort field. Leading `-` = desc; only `created_at` is sortable. Default
+        # `-created_at`. `--` is an error.
+        sort: nil,
+        request_options: {}
+      )
+      end
+
+      # Soft-deletes (status → `removed`; tombstone retained). A `removed` audit event
+      # is appended unless the block was already `removed` (idempotent — returns the
+      # existing row with `200` and no new event). Mutates `updated_at`.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailBlockResponse)
+      end
+      def delete(
+        # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+        id,
+        request_options: {}
+      )
+      end
+
+      # Offset pagination only (`page[number]` default 1, `page[size]` default **50**,
+      # max 100). No `sort`, no `filter`, no cursor — ordering is fixed
+      # `desc occurred_at, desc id`. Verifies the block belongs to the account first
+      # (cross-account → 404).
+      sig do
+        params(
+          id: String,
+          page_number: Integer,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailBlockRetrieveEventsResponse)
+      end
+      def retrieve_events(
+        # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+        id,
+        # Offset page number (≥1, default 1).
+        page_number: nil,
+        # Page size (default 50, max 100).
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
+      # Streams the account's suppressions as a chunked CSV (server-side cursor; never
+      # materialized). Content-type `text/csv`, header
+      # `Content-Disposition: attachment; filename="email_blocks_export.csv"`.
+      #
+      # Filters (`filter[reason]`, `filter[domain_id]`, `filter[created_after]`,
+      # `filter[created_before]`) are the only params that affect output. `sort` and
+      # `page[*]` are **parsed** (bad values still produce `400`) but **ignored** — rows
+      # 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).
+      sig do
+        params(
+          filter_created_after: Time,
+          filter_created_before: Time,
+          filter_domain_id: String,
+          filter_reason:
+            Telnyx::EmailBlockRetrieveExportParams::FilterReason::OrSymbol,
+          page_number: Integer,
+          page_size: Integer,
+          sort: Telnyx::EmailBlockRetrieveExportParams::Sort::OrSymbol,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(String)
+      end
+      def retrieve_export(
+        # `created_at > value` (ISO 8601).
+        filter_created_after: nil,
+        # `created_at < value` (ISO 8601).
+        filter_created_before: nil,
+        # Exact-match filter on domain_id (UUID).
+        filter_domain_id: nil,
+        # Exact-match filter on reason.
+        filter_reason: nil,
+        # Offset page number (≥1, default 1).
+        page_number: nil,
+        # Page size (1–100, default 25).
+        page_size: nil,
+        # Sort field. Leading `-` = desc; only `created_at` is sortable. Default
+        # `-created_at`. `--` is an error.
+        sort: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_domains/webhooks.rbi

@@ -0,0 +1,122 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailDomains
+      # Per-domain webhook endpoints with event subscriptions
+      class Webhooks
+        # Creates a webhook endpoint subscribed to a specific allowlist of event types.
+        # Both `email.*` events (published by email-api) and `email_domain.*` events
+        # (published by this service) flow through the same webhooks.
+        sig do
+          params(
+            domain_id: String,
+            events: T::Array[Telnyx::EmailDomains::EmailWebhookEvent::OrSymbol],
+            url: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailDomains::EmailWebhookResponse)
+        end
+        def create(
+          # Email domain UUID
+          domain_id,
+          # At least one event type is required.
+          events:,
+          # HTTPS endpoint to deliver subscribed events to.
+          url:,
+          request_options: {}
+        )
+        end
+
+        # Retrieve a webhook
+        sig do
+          params(
+            id: String,
+            domain_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailDomains::EmailWebhookResponse)
+        end
+        def retrieve(
+          # Email webhook UUID
+          id,
+          # Email domain UUID
+          domain_id:,
+          request_options: {}
+        )
+        end
+
+        # Update a webhook's URL and/or event subscription. A webhook is bound to its
+        # domain — `domain_id` is not mutable.
+        sig do
+          params(
+            id: String,
+            domain_id: String,
+            events: T::Array[Telnyx::EmailDomains::EmailWebhookEvent::OrSymbol],
+            url: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailDomains::EmailWebhookResponse)
+        end
+        def update(
+          # Path param: Email webhook UUID
+          id,
+          # Path param: Email domain UUID
+          domain_id:,
+          # Body param
+          events: nil,
+          # Body param
+          url: nil,
+          request_options: {}
+        )
+        end
+
+        # List webhooks for an email domain
+        sig do
+          params(
+            domain_id: String,
+            page_number: Integer,
+            page_size: Integer,
+            sort: Telnyx::EmailDomains::WebhookListParams::Sort::OrSymbol,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Internal::DefaultFlatPagination[
+              Telnyx::EmailDomains::EmailWebhook
+            ]
+          )
+        end
+        def list(
+          # Email domain UUID
+          domain_id,
+          # Page number to return (offset pagination)
+          page_number: nil,
+          # Number of records per page
+          page_size: nil,
+          # Field to sort by. Prefix with `-` for descending order.
+          sort: nil,
+          request_options: {}
+        )
+        end
+
+        # Delete a webhook
+        sig do
+          params(
+            id: String,
+            domain_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailDomains::EmailWebhookResponse)
+        end
+        def delete(
+          # Email webhook UUID
+          id,
+          # Email domain UUID
+          domain_id:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_domains.rbi

@@ -0,0 +1,180 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailDomains
+      # Per-domain webhook endpoints with event subscriptions
+      sig { returns(Telnyx::Resources::EmailDomains::Webhooks) }
+      attr_reader :webhooks
+
+      # Create an email domain
+      sig do
+        params(
+          domain: String,
+          dmarc_policy: T.nilable(Telnyx::EmailDmarcPolicy::OrHash),
+          inbound_enabled: T::Boolean,
+          tracking: Telnyx::DomainsTrackingSettings::OrHash,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailDomainResponse)
+      end
+      def create(
+        domain:,
+        # DMARC policy for a sending domain. Drives the recommended \_dmarc.<domain> TXT
+        # record. DMARC is advisory and never blocks sending. When omitted or null, the
+        # domain uses the advisory default (v=DMARC1; p=none;
+        # rua=mailto:dmarc@telnyx.com).
+        dmarc_policy: nil,
+        # Enable inbound routing for this domain
+        inbound_enabled: nil,
+        tracking: nil,
+        request_options: {}
+      )
+      end
+
+      # Shared (`type: shared`) Telnyx-managed domains are included/readable for every
+      # account, in addition to the account's own custom domains.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailDomainResponse)
+      end
+      def retrieve(
+        # Email domain UUID
+        id,
+        request_options: {}
+      )
+      end
+
+      # Update an email domain
+      sig do
+        params(
+          id: String,
+          dmarc_policy: T.nilable(Telnyx::EmailDmarcPolicy::OrHash),
+          inbound_enabled: T::Boolean,
+          tracking: Telnyx::DomainsTrackingSettings::OrHash,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailDomainResponse)
+      end
+      def update(
+        # Email domain UUID
+        id,
+        # DMARC policy for a sending domain. Drives the recommended \_dmarc.<domain> TXT
+        # record. DMARC is advisory and never blocks sending. When omitted or null, the
+        # domain uses the advisory default (v=DMARC1; p=none;
+        # rua=mailto:dmarc@telnyx.com).
+        dmarc_policy: nil,
+        # Enable or disable inbound routing for this domain
+        inbound_enabled: nil,
+        tracking: nil,
+        request_options: {}
+      )
+      end
+
+      # Shared (`type: shared`) Telnyx-managed domains are included/readable for every
+      # account, in addition to the account's own custom domains.
+      sig do
+        params(
+          filter_domain: String,
+          filter_profile_id: String,
+          filter_status: Telnyx::EmailDomainStatus::OrSymbol,
+          filter_type: Telnyx::EmailDomainType::OrSymbol,
+          filter_usable_for_inbound: T::Boolean,
+          filter_usable_for_sending: T::Boolean,
+          page_after: String,
+          page_before: String,
+          page_number: Integer,
+          page_size: Integer,
+          sort: Telnyx::EmailDomainListParams::Sort::OrSymbol,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Internal::DefaultFlatPagination[Telnyx::EmailDomain])
+      end
+      def list(
+        # Partial match on domain name (case-insensitive)
+        filter_domain: nil,
+        # Filter by profile UUID
+        filter_profile_id: nil,
+        filter_status: nil,
+        filter_type: nil,
+        filter_usable_for_inbound: nil,
+        filter_usable_for_sending: nil,
+        # Cursor for records after the provided value (cursor pagination)
+        page_after: nil,
+        # Cursor for records before the provided value (cursor pagination)
+        page_before: nil,
+        # Page number to return (offset pagination)
+        page_number: nil,
+        # Number of records per page
+        page_size: nil,
+        # Field to sort by. Prefix with `-` for descending order.
+        sort: nil,
+        request_options: {}
+      )
+      end
+
+      # Delete an email domain
+      sig do
+        params(
+          id: String,
+          force: T::Boolean,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailDomainResponse)
+      end
+      def delete(
+        # Email domain UUID
+        id,
+        # Required as true when deleting verified domains
+        force: nil,
+        request_options: {}
+      )
+      end
+
+      # List DNS records for an email domain
+      sig do
+        params(
+          domain_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailDomainRetrieveDNSRecordsResponse)
+      end
+      def retrieve_dns_records(
+        # Email domain UUID
+        domain_id,
+        request_options: {}
+      )
+      end
+
+      # Returns a summary of domain health including verification status and usability.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailDomainRetrieveHealthResponse)
+      end
+      def retrieve_health(
+        # Email domain UUID
+        id,
+        request_options: {}
+      )
+      end
+
+      # Verify DNS records for an email domain
+      sig do
+        params(
+          domain_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailDomainResponse)
+      end
+      def verify(
+        # Email domain UUID
+        domain_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end