telnyx 5.158.0 → 5.159.0

data/lib/telnyx/resources/calls/actions.rb

@@ -10,7 +10,7 @@ module Telnyx
         #
         # Add messages to the conversation started by an AI assistant on the call.
         #
-        # @overload add_ai_assistant_messages(call_control_id, client_state: nil, command_id: nil, messages: nil, request_options: {})
+        # @overload add_ai_assistant_messages(call_control_id, client_state: nil, command_id: nil, messages: nil, trigger_response: nil, request_options: {})
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
@@ -20,6 +20,8 @@ module Telnyx
         #
         # @param messages [Array<Telnyx::Models::Calls::UserMessage, Telnyx::Models::Calls::AssistantMessage, Telnyx::Models::Calls::ToolMessage, Telnyx::Models::Calls::SystemMessage, Telnyx::Models::Calls::DeveloperMessage>] The messages to add to the conversation.
         #
+        # @param trigger_response [Boolean] When `true`, the injected messages immediately trigger an assistant response/tur
+        #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Telnyx::Models::Calls::ActionAddAIAssistantMessagesResponse]
@@ -634,6 +636,85 @@ module Telnyx
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::Calls::ActionPayParams} for more details.
+        #
+        # Collect payment details from the caller using DTMF and either charge or tokenize
+        # the payment method through a configured Pay connector. Pay pauses active call
+        # recordings while sensitive payment details are collected.
+        #
+        # When `payment_token` is supplied, the DTMF collection steps are skipped and the
+        # existing token is sent to the connector.
+        #
+        # **Expected Webhooks:**
+        #
+        # - `call.payment.progress`
+        # - `call.payment.completed`
+        #
+        # **Test mode card numbers:** `4111111111111111` (Visa), `5555555555554444`
+        # (Mastercard), `378282246310005` (American Express), `6011111111111117`
+        # (Discover), `3065930009020004` (Diners Club), `3566002020360505` (JCB),
+        # `6200000000000005` (UnionPay), and `6771798021000008` (Maestro). Test-mode
+        # connectors reject other card numbers before contacting the configured processor.
+        # The UnionPay and Maestro numbers are accepted for processor testing, but Pay
+        # currently does not emit a card type for them.
+        #
+        # @overload pay(call_control_id, amount: nil, client_state: nil, command_id: nil, connector_name: nil, currency: nil, description: nil, inter_digit_timeout_millis: nil, language: nil, max_attempts: nil, metadata: nil, parameters: nil, payment_method: nil, payment_token: nil, prompts: nil, service_level: nil, timeout_millis: nil, transaction_type: nil, voice: nil, request_options: {})
+        #
+        # @param call_control_id [String] Unique identifier and token for controlling the call
+        #
+        # @param amount [Float] Amount to charge. Required when `transaction_type` is `charge`.
+        #
+        # @param client_state [String] Base64-encoded state included in subsequent webhooks.
+        #
+        # @param command_id [String] Idempotency key for the command. Telnyx ignores a duplicate command with the sam
+        #
+        # @param connector_name [String] Name of the Pay connector used to process the transaction.
+        #
+        # @param currency [Symbol, Telnyx::Models::Calls::ActionPayParams::Currency] Currency used for the transaction. Pay currently supports USD only.
+        #
+        # @param description [String] Optional description forwarded with the payment transaction.
+        #
+        # @param inter_digit_timeout_millis [Integer] Time in milliseconds to wait between consecutive DTMF digits.
+        #
+        # @param language [String] Language used for payment prompts.
+        #
+        # @param max_attempts [Integer] Maximum number of attempts for each payment collection step.
+        #
+        # @param metadata [Hash{Symbol=>Object}] Metadata forwarded to the Pay connector.
+        #
+        # @param parameters [Hash{Symbol=>Object}] Additional parameters forwarded to the Pay connector.
+        #
+        # @param payment_method [Symbol, Telnyx::Models::Calls::ActionPayParams::PaymentMethod] Payment method to collect.
+        #
+        # @param payment_token [String] Existing payment token. When supplied, payment-detail collection is skipped.
+        #
+        # @param prompts [Telnyx::Models::Calls::ActionPayParams::Prompts] Custom text-to-speech prompts keyed by payment collection step.
+        #
+        # @param service_level [String] Speech synthesis service level used for payment prompts. Pay defaults to `premiu
+        #
+        # @param timeout_millis [Integer] Time in milliseconds to wait for DTMF input for each collection step.
+        #
+        # @param transaction_type [Symbol, Telnyx::Models::Calls::ActionPayParams::TransactionType] Transaction to perform. If omitted, Pay infers `tokenize` when `amount` is absen
+        #
+        # @param voice [String] Voice used for payment prompts. Accepts `male`, `female`, or a provider voice in
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::Calls::ActionPayResponse]
+        #
+        # @see Telnyx::Models::Calls::ActionPayParams
+        def pay(call_control_id, params = {})
+          parsed, options = Telnyx::Calls::ActionPayParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["calls/%1$s/actions/pay", call_control_id],
+            body: parsed,
+            model: Telnyx::Models::Calls::ActionPayResponse,
+            options: options
+          )
+        end
+
         # Some parameter documentations has been truncated, see
         # {Telnyx::Models::Calls::ActionReferParams} for more details.
         #
@@ -890,7 +971,7 @@ module Telnyx
         # - `call.conversation.ended`
         # - `call.conversation_insights.generated`
         #
-        # @overload start_ai_assistant(call_control_id, assistant: nil, client_state: nil, command_id: nil, greeting: nil, interruption_settings: nil, message_history: nil, participants: nil, send_message_history_updates: nil, transcription: nil, voice: nil, voice_settings: nil, request_options: {})
+        # @overload start_ai_assistant(call_control_id, assistant: nil, client_state: nil, command_id: nil, greeting: nil, interruption_settings: nil, message_history: nil, participants: nil, send_message_history_updates: nil, transcription: nil, request_options: {})
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
@@ -912,10 +993,6 @@ module Telnyx
         #
         # @param transcription [Telnyx::Models::Calls::TranscriptionConfig] The settings associated with speech to text for the voice assistant. This is onl
         #
-        # @param voice [String] The voice to be used by the voice assistant. Currently we support ElevenLabs, Te
-        #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::RimeVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
-        #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Telnyx::Models::Calls::ActionStartAIAssistantResponse]
@@ -1339,7 +1416,7 @@ module Telnyx
         #
         # @param transcription_engine [Symbol, Telnyx::Models::Calls::TranscriptionStartRequest::TranscriptionEngine] Engine to use for speech recognition. Legacy values `A` - `Google`, `B` - `Telny
         #
-        # @param transcription_engine_config [Telnyx::Models::Calls::TranscriptionEngineGoogleConfig, Telnyx::Models::Calls::TranscriptionEngineTelnyxConfig, Telnyx::Models::Calls::TranscriptionEngineAzureConfig, Telnyx::Models::Calls::TranscriptionEngineXaiConfig, Telnyx::Models::Calls::TranscriptionEngineAssemblyaiConfig, Telnyx::Models::Calls::TranscriptionEngineSpeechmaticsConfig, Telnyx::Models::Calls::TranscriptionEngineSonioxConfig, Telnyx::Models::Calls::TranscriptionEngineParakeetConfig, Telnyx::Models::Calls::TranscriptionEngineAConfig, Telnyx::Models::Calls::TranscriptionEngineBConfig, Telnyx::Models::Calls::DeepgramNova2Config, Telnyx::Models::Calls::DeepgramNova3Config]
+        # @param transcription_engine_config [Telnyx::Models::Calls::TranscriptionEngineGoogleConfig, Telnyx::Models::Calls::TranscriptionEngineTelnyxConfig, Telnyx::Models::Calls::TranscriptionEngineAzureConfig, Telnyx::Models::Calls::TranscriptionEngineXaiConfig, Telnyx::Models::Calls::TranscriptionEngineAssemblyaiConfig, Telnyx::Models::Calls::TranscriptionEngineSpeechmaticsConfig, Telnyx::Models::Calls::TranscriptionEngineSonioxConfig, Telnyx::Models::Calls::TranscriptionEngineParakeetConfig, Telnyx::Models::Calls::TranscriptionStartRequest::TranscriptionEngineConfig::Humain, Telnyx::Models::Calls::TranscriptionStartRequest::TranscriptionEngineConfig::Reson8, Telnyx::Models::Calls::TranscriptionEngineAConfig, Telnyx::Models::Calls::TranscriptionEngineBConfig, Telnyx::Models::Calls::DeepgramNova2Config, Telnyx::Models::Calls::DeepgramNova3Config]
         #
         # @param transcription_tracks [String] Indicates which leg of the call will be transcribed. Use `inbound` for the leg t
         #
@@ -1733,7 +1810,7 @@ module Telnyx
         # - `call.machine.premium.greeting.ended` if `answering_machine_detection=premium`
         #   was requested and a beep was detected
         #
-        # @overload transfer(call_control_id, to:, answering_machine_detection: nil, answering_machine_detection_config: nil, audio_url: nil, client_state: nil, command_id: nil, custom_headers: nil, early_media: nil, from: nil, from_display_name: nil, media_encryption: nil, media_name: nil, mute_dtmf: nil, park_after_unbridge: nil, preferred_codecs: nil, privacy: nil, record: nil, record_channels: nil, record_custom_file_name: nil, record_format: nil, record_max_length: nil, record_timeout_secs: nil, record_track: nil, record_trim: nil, send_digits_on_answer: nil, sip_auth_password: nil, sip_auth_username: nil, sip_headers: nil, sip_region: nil, sip_transport_protocol: nil, sound_modifications: nil, target_leg_client_state: nil, time_limit_secs: nil, timeout_secs: nil, webhook_retries_policies: nil, webhook_url: nil, webhook_url_method: nil, webhook_urls: nil, webhook_urls_method: nil, request_options: {})
+        # @overload transfer(call_control_id, to:, answering_machine_detection: nil, answering_machine_detection_config: nil, audio_url: nil, client_state: nil, command_id: nil, custom_headers: nil, early_media: nil, from: nil, from_display_name: nil, media_encryption: nil, media_name: nil, mute_dtmf: nil, park_after_unbridge: nil, preferred_codecs: nil, privacy: nil, record: nil, record_channels: nil, record_custom_file_name: nil, record_format: nil, record_max_length: nil, record_timeout_secs: nil, record_track: nil, record_trim: nil, route_to_mobile: nil, send_digits_on_answer: nil, sip_auth_password: nil, sip_auth_username: nil, sip_headers: nil, sip_region: nil, sip_transport_protocol: nil, sound_modifications: nil, target_leg_client_state: nil, time_limit_secs: nil, timeout_secs: nil, webhook_retries_policies: nil, webhook_url: nil, webhook_url_method: nil, webhook_urls: nil, webhook_urls_method: nil, request_options: {})
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
@@ -1785,6 +1862,8 @@ module Telnyx
         #
         # @param record_trim [Symbol, Telnyx::Models::Calls::ActionTransferParams::RecordTrim] When set to `trim-silence`, silence will be removed from the beginning and end o
         #
+        # @param route_to_mobile [Boolean] When set to true, routes the call directly to the mobile device associated with
+        #
         # @param send_digits_on_answer [String] DTMF digits to send automatically after the transfer destination answers. Useful
         #
         # @param sip_auth_password [String] SIP Authentication password used for SIP challenges.

data/lib/telnyx/resources/calls.rb

@@ -35,7 +35,7 @@ module Telnyx
       # When the `record` parameter is set to `record-from-answer`, the response will
       # include a `recording_id` field.
       #
-      # @overload dial(connection_id:, from:, to:, answering_machine_detection: nil, answering_machine_detection_config: nil, assistant: nil, audio_url: nil, billing_group_id: nil, bridge_intent: nil, bridge_on_answer: nil, client_state: nil, command_id: nil, conference_config: nil, conversation_relay_config: nil, custom_headers: nil, deepfake_detection: nil, dialogflow_config: nil, enable_dialogflow: nil, from_display_name: nil, link_to: nil, media_encryption: nil, media_name: nil, park_after_unbridge: nil, preferred_codecs: nil, prevent_double_bridge: nil, privacy: nil, record: nil, record_channels: nil, record_custom_file_name: nil, record_format: nil, record_max_length: nil, record_timeout_secs: nil, record_track: nil, record_trim: nil, retry_on_timeout: nil, send_digits_on_answer: nil, send_silence_when_idle: nil, sip_auth_password: nil, sip_auth_username: nil, sip_headers: nil, sip_region: nil, sip_transport_protocol: nil, sound_modifications: nil, stream_auth_token: nil, stream_bidirectional_codec: nil, stream_bidirectional_mode: nil, stream_bidirectional_sampling_rate: nil, stream_bidirectional_target_legs: nil, stream_codec: nil, stream_establish_before_call_originate: nil, stream_track: nil, stream_url: nil, supervise_call_control_id: nil, supervisor_role: nil, time_limit_secs: nil, timeout_secs: nil, transcription: nil, transcription_config: nil, webhook_retries_policies: nil, webhook_url: nil, webhook_url_method: nil, webhook_urls: nil, webhook_urls_method: nil, request_options: {})
+      # @overload dial(connection_id:, from:, to:, answering_machine_detection: nil, answering_machine_detection_config: nil, assistant: nil, audio_url: nil, billing_group_id: nil, bridge_intent: nil, bridge_on_answer: nil, client_state: nil, command_id: nil, conference_config: nil, conversation_relay_config: nil, custom_headers: nil, deepfake_detection: nil, dialogflow_config: nil, enable_dialogflow: nil, from_display_name: nil, link_to: nil, media_encryption: nil, media_name: nil, park_after_unbridge: nil, preferred_codecs: nil, prevent_double_bridge: nil, privacy: nil, record: nil, record_channels: nil, record_custom_file_name: nil, record_format: nil, record_max_length: nil, record_timeout_secs: nil, record_track: nil, record_trim: nil, retry_on_timeout: nil, route_to_mobile: nil, send_digits_on_answer: nil, send_silence_when_idle: nil, sip_auth_password: nil, sip_auth_username: nil, sip_headers: nil, sip_region: nil, sip_transport_protocol: nil, sound_modifications: nil, stream_auth_token: nil, stream_bidirectional_codec: nil, stream_bidirectional_mode: nil, stream_bidirectional_sampling_rate: nil, stream_bidirectional_target_legs: nil, stream_codec: nil, stream_establish_before_call_originate: nil, stream_track: nil, stream_url: nil, supervise_call_control_id: nil, supervisor_role: nil, time_limit_secs: nil, timeout_secs: nil, transcription: nil, transcription_config: nil, webhook_retries_policies: nil, webhook_url: nil, webhook_url_method: nil, webhook_urls: nil, webhook_urls_method: nil, request_options: {})
       #
       # @param connection_id [String] The ID of the Call Control App (formerly ID of the connection) to be used when d
       #
@@ -107,6 +107,8 @@ module Telnyx
       #
       # @param retry_on_timeout [Boolean] Whether to keep trying the remaining routing paths (e.g. alternate providers/gat
       #
+      # @param route_to_mobile [Boolean] When set to true, routes the call directly to the mobile device associated with
+      #
       # @param send_digits_on_answer [String] DTMF digits to send automatically after the called party answers. Useful for rea
       #
       # @param send_silence_when_idle [Boolean] Generate silence RTP packets when no transmission available.

data/lib/telnyx/resources/custom_storage_credentials.rb

@@ -15,7 +15,7 @@ module Telnyx
       #
       # @param backend [Symbol, Telnyx::Models::CustomStorageConfiguration::Backend]
       #
-      # @param configuration [Telnyx::Models::GcsConfigurationData, Telnyx::Models::S3ConfigurationData, Telnyx::Models::AzureConfigurationData]
+      # @param configuration [Telnyx::Models::GcsConfigurationData, Telnyx::Models::S3ConfigurationData, Telnyx::Models::CustomStorageConfiguration::Configuration::S3Generic, Telnyx::Models::AzureConfigurationData]
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -67,7 +67,7 @@ module Telnyx
       #
       # @param backend [Symbol, Telnyx::Models::CustomStorageConfiguration::Backend]
       #
-      # @param configuration [Telnyx::Models::GcsConfigurationData, Telnyx::Models::S3ConfigurationData, Telnyx::Models::AzureConfigurationData]
+      # @param configuration [Telnyx::Models::GcsConfigurationData, Telnyx::Models::S3ConfigurationData, Telnyx::Models::CustomStorageConfiguration::Configuration::S3Generic, Telnyx::Models::AzureConfigurationData]
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #

data/lib/telnyx/resources/dir/references.rb

@@ -16,15 +16,35 @@ 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.
         #
         # @overload create(dir_id, business_references:, financial_reference:, request_options: {})
         #
         # @param dir_id [String] The DIR id. Lowercase UUID.
         #
-        # @param business_references [Array<Telnyx::Models::Dir::ReferenceInput>] Exactly two business references.
+        # @param business_references [Array<Telnyx::Models::Dir::ReferenceInput>] Exactly two business references. Array order determines each one's slot: the fir
         #
         # @param financial_reference [Telnyx::Models::Dir::ReferenceInput] One reference supplied at submit. The reference type is implied by the field tha
         #
@@ -58,7 +78,7 @@ module Telnyx
         #
         # @overload update(slot, dir_id:, ref_type:, email: nil, full_name: nil, job_title: nil, organization: nil, phone_e164: nil, relationship_to_registrant: nil, timezone: nil, request_options: {})
         #
-        # @param slot [Integer] Path param: Reference slot. Business references use slots 0 and 1; the financial
+        # @param slot [Integer] Path param: Reference slot, counting from 1. Business references are slots 1 and
         #
         # @param dir_id [String] Path param: The DIR id. Lowercase UUID.
         #
@@ -104,10 +124,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.
         #
         # @overload list(dir_id, request_options: {})
         #

data/lib/telnyx/resources/dir.rb

@@ -288,8 +288,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.
       #
       # @overload submit(dir_id, request_options: {})
       #

data/lib/telnyx/resources/email_blocks/import.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class EmailBlocks
+      # Async CSV import of competitor suppression lists.
+      class Import
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::EmailBlocks::ImportCreateParams} for more details.
+        #
+        # 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`).
+        #
+        # @overload create(file:, block_ttl_days: nil, request_options: {})
+        #
+        # @param file [Pathname, StringIO, IO, String, Telnyx::FilePart] The CSV file (Plug.Upload). Missing/non-upload → 400.
+        #
+        # @param block_ttl_days [Integer] TTL for imported `manual_block` rows; other reasons get `expires_at: null`. Inva
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailBlocks::EmailBlockImportResponse]
+        #
+        # @see Telnyx::Models::EmailBlocks::ImportCreateParams
+        def create(params)
+          parsed, options = Telnyx::EmailBlocks::ImportCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "email_blocks/import",
+            headers: {"content-type" => "multipart/form-data"},
+            body: parsed,
+            model: Telnyx::EmailBlocks::EmailBlockImportResponse,
+            options: 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.
+        #
+        # @overload retrieve(id, request_options: {})
+        #
+        # @param id [String] Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailBlocks::EmailBlockImportResponse]
+        #
+        # @see Telnyx::Models::EmailBlocks::ImportRetrieveParams
+        def retrieve(id, params = {})
+          @client.request(
+            method: :get,
+            path: ["email_blocks/import/%1$s", id],
+            model: Telnyx::EmailBlocks::EmailBlockImportResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/email_blocks.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    # Recipient suppression records (`/v2/email_blocks`).
+    class EmailBlocks
+      # Async CSV import of competitor suppression lists.
+      # @return [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.
+      #
+      # @overload create(to:, domain_id: nil, expires_at: nil, from: nil, request_options: {})
+      #
+      # @param to [String] Recipient address (normalized: trim + lower-case).
+      #
+      # @param domain_id [String, nil] `null` ⇒ account scope.
+      #
+      # @param expires_at [Time, nil]
+      #
+      # @param from [String, nil] Sender address (normalized). `null` ⇒ account/domain scope.
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::EmailBlockResponse]
+      #
+      # @see Telnyx::Models::EmailBlockCreateParams
+      def create(params)
+        parsed, options = Telnyx::EmailBlockCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "email_blocks",
+          body: parsed,
+          model: Telnyx::EmailBlockResponse,
+          options: options
+        )
+      end
+
+      # Retrieve a suppression
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::EmailBlockResponse]
+      #
+      # @see Telnyx::Models::EmailBlockRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["email_blocks/%1$s", id],
+          model: Telnyx::EmailBlockResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Telnyx::Models::EmailBlockListParams} for more details.
+      #
+      # 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.
+      #
+      # @overload list(filter_created_after: nil, filter_created_before: nil, filter_domain_id: nil, filter_reason: nil, page_after: nil, page_before: nil, page_number: nil, page_size: nil, sort: nil, request_options: {})
+      #
+      # @param filter_created_after [Time] `created_at > value` (ISO 8601).
+      #
+      # @param filter_created_before [Time] `created_at < value` (ISO 8601).
+      #
+      # @param filter_domain_id [String] Exact-match filter on domain_id (UUID).
+      #
+      # @param filter_reason [Symbol, Telnyx::Models::EmailBlockListParams::FilterReason] Exact-match filter on reason.
+      #
+      # @param page_after [String] Opaque cursor (`Base.url_encode64` of `{"created_at","id"}`). Cursor mode; mutua
+      #
+      # @param page_before [String] Opaque cursor (see `page[after]`). Mutually exclusive with `page[after]` and `pa
+      #
+      # @param page_number [Integer] Offset page number (≥1, default 1).
+      #
+      # @param page_size [Integer] Page size (1–100, default 25).
+      #
+      # @param sort [Symbol, Telnyx::Models::EmailBlockListParams::Sort] Sort field. Leading `-` = desc; only `created_at` is sortable. Default `-created
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::EmailBlock>]
+      #
+      # @see Telnyx::Models::EmailBlockListParams
+      def list(params = {})
+        parsed, options = Telnyx::EmailBlockListParams.dump_request(params)
+        query = Telnyx::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "email_blocks",
+          query: query.transform_keys(
+            filter_created_after: "filter[created_after]",
+            filter_created_before: "filter[created_before]",
+            filter_domain_id: "filter[domain_id]",
+            filter_reason: "filter[reason]",
+            page_after: "page[after]",
+            page_before: "page[before]",
+            page_number: "page[number]",
+            page_size: "page[size]"
+          ),
+          page: Telnyx::Internal::DefaultFlatPagination,
+          model: Telnyx::EmailBlock,
+          options: 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`.
+      #
+      # @overload delete(id, request_options: {})
+      #
+      # @param id [String] Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::EmailBlockResponse]
+      #
+      # @see Telnyx::Models::EmailBlockDeleteParams
+      def delete(id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["email_blocks/%1$s", id],
+          model: Telnyx::EmailBlockResponse,
+          options: params[: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).
+      #
+      # @overload retrieve_events(id, page_number: nil, page_size: nil, request_options: {})
+      #
+      # @param id [String] Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+      #
+      # @param page_number [Integer] Offset page number (≥1, default 1).
+      #
+      # @param page_size [Integer] Page size (default 50, max 100).
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::EmailBlockRetrieveEventsResponse]
+      #
+      # @see Telnyx::Models::EmailBlockRetrieveEventsParams
+      def retrieve_events(id, params = {})
+        parsed, options = Telnyx::EmailBlockRetrieveEventsParams.dump_request(params)
+        query = Telnyx::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["email_blocks/%1$s/events", id],
+          query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
+          model: Telnyx::Models::EmailBlockRetrieveEventsResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Telnyx::Models::EmailBlockRetrieveExportParams} for more details.
+      #
+      # 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).
+      #
+      # @overload retrieve_export(filter_created_after: nil, filter_created_before: nil, filter_domain_id: nil, filter_reason: nil, page_number: nil, page_size: nil, sort: nil, request_options: {})
+      #
+      # @param filter_created_after [Time] `created_at > value` (ISO 8601).
+      #
+      # @param filter_created_before [Time] `created_at < value` (ISO 8601).
+      #
+      # @param filter_domain_id [String] Exact-match filter on domain_id (UUID).
+      #
+      # @param filter_reason [Symbol, Telnyx::Models::EmailBlockRetrieveExportParams::FilterReason] Exact-match filter on reason.
+      #
+      # @param page_number [Integer] Offset page number (≥1, default 1).
+      #
+      # @param page_size [Integer] Page size (1–100, default 25).
+      #
+      # @param sort [Symbol, Telnyx::Models::EmailBlockRetrieveExportParams::Sort] Sort field. Leading `-` = desc; only `created_at` is sortable. Default `-created
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [String]
+      #
+      # @see Telnyx::Models::EmailBlockRetrieveExportParams
+      def retrieve_export(params = {})
+        parsed, options = Telnyx::EmailBlockRetrieveExportParams.dump_request(params)
+        query = Telnyx::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "email_blocks/export",
+          query: query.transform_keys(
+            filter_created_after: "filter[created_after]",
+            filter_created_before: "filter[created_before]",
+            filter_domain_id: "filter[domain_id]",
+            filter_reason: "filter[reason]",
+            page_number: "page[number]",
+            page_size: "page[size]"
+          ),
+          headers: {"accept" => "text/csv"},
+          model: String,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Telnyx::Client]
+      def initialize(client:)
+        @client = client
+        @import = Telnyx::Resources::EmailBlocks::Import.new(client: client)
+      end
+    end
+  end
+end