telnyx 5.158.0 → 5.159.0

data/rbi/telnyx/resources/email_messages.rbi

@@ -0,0 +1,299 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Send and manage email messages. Legacy `/v2/emails` routes are aliases for these
+    # endpoints.
+    class EmailMessages
+      # Send and manage email messages. Legacy `/v2/emails` routes are aliases for these
+      # endpoints.
+      sig { returns(Telnyx::Resources::EmailMessages::Recipients) }
+      attr_reader :recipients
+
+      # Queues, schedules, or sandbox-sends an email message. The legacy `/v2/emails`
+      # POST route is a backward-compatible alias for this operation.
+      #
+      # `subject` is required unless `template_id` is supplied. When using
+      # `template_id`, do not also provide `subject`, `html_body`, or `text_body`; the
+      # template is rendered with `template_variables`.
+      #
+      # Note: template lookup failures (not found, wrong account) return 400, not 404.
+      sig do
+        params(
+          from: T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash),
+          to:
+            T::Array[T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)],
+          attachments: T::Array[Telnyx::AttachmentRequest::OrHash],
+          bcc:
+            T::Array[T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)],
+          cc:
+            T::Array[T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)],
+          forward_of_message_id: T.nilable(String),
+          from_name: String,
+          group_id: T.nilable(String),
+          headers: T::Hash[Symbol, String],
+          html_body: String,
+          ignore_suppression: T::Boolean,
+          in_reply_to_message_id: T.nilable(String),
+          inline_css: T::Boolean,
+          metadata: T::Hash[Symbol, T.anything],
+          reply_to: T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash),
+          reply_to_all: T.nilable(T::Boolean),
+          sandbox_mode: T::Boolean,
+          scheduled_at: T.nilable(Time),
+          send_at: Time,
+          subject: String,
+          tags: T::Array[String],
+          template_id: String,
+          template_variables: T::Hash[Symbol, T.anything],
+          text_body: String,
+          tracking_settings: Telnyx::TrackingSettings::OrHash,
+          idempotency_key: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailInboxes::EmailMessageResponse)
+      end
+      def create(
+        # Body param
+        from:,
+        # Body param
+        to:,
+        # Body param
+        attachments: nil,
+        # Body param
+        bcc: nil,
+        # Body param
+        cc: nil,
+        # Body param: Telnyx message UUID of the message this send forwards. Forwarded
+        # messages start a NEW thread per RFC 5322 — NO `In-Reply-To` or `References`
+        # headers are set on the outbound MIME. The id is recorded in the message's
+        # metadata for EDR provenance only.
+        #
+        # The id is validated as a UUID but is NOT looked up against the message store —
+        # existence is the caller's responsibility (the forward is pure metadata; it does
+        # not affect delivery). Cannot be combined with `in_reply_to_message_id` (422).
+        forward_of_message_id: nil,
+        # Body param: Optional display name for string `from`; overrides `from.name` when
+        # provided.
+        from_name: nil,
+        # Body param: Optional unsubscribe-group UUID used for group-scoped suppression
+        # checks and unsubscribe handling.
+        group_id: nil,
+        # Body param: Custom email headers. Write-only; not returned in responses.
+        headers: nil,
+        # Body param: HTML email body. Returned only by `GET /email_messages/{id}`;
+        # omitted from create and list responses.
+        html_body: nil,
+        # Body param: When true, allows delivery to recipients whose suppressions
+        # explicitly permit an override. Hard bounces, spam complaints, and
+        # invalid-address suppressions cannot be overridden. Requires the `email:override`
+        # API scope.
+        ignore_suppression: nil,
+        # Body param: Telnyx message UUID of the message this send replies to. When
+        # provided, the API sets RFC 5322 `In-Reply-To` and `References` headers on the
+        # outbound MIME so the recipient's mailbox (Gmail/Outlook) threads it correctly.
+        # The parent is looked up under the caller's account scope; a UUID belonging to
+        # another account yields a non-enumerating 404.
+        #
+        # Wire-only (Phase 1): the API sets the headers and does NOT resolve or mutate
+        # `thread_id` on the server side. Messages sent without this parameter are
+        # standalone (no threading headers injected).
+        #
+        # Cannot be combined with `forward_of_message_id` (422).
+        in_reply_to_message_id: nil,
+        # Body param
+        inline_css: nil,
+        # Body param: Custom metadata. Write-only; not returned in responses.
+        metadata: nil,
+        # Body param: Reply-to address. If provided as an object with a name, only the
+        # email is stored; the name is ignored.
+        reply_to: nil,
+        # Body param: Indicates a reply-all intent. In Phase 1 (wire-only) this does not
+        # change the threading headers — recipient selection is customer- controlled
+        # (`to`/`cc`), and a thread is not defined by its audience. When the referenced
+        # message has no thread context, reply-all degrades to a plain reply (parent ID
+        # only in `References`). The resolution engine (separate work) will expand the
+        # ancestor chain at a later phase with no API change.
+        #
+        # Only meaningful alongside `in_reply_to_message_id`.
+        reply_to_all: nil,
+        # Body param
+        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.
+        scheduled_at: nil,
+        # Body param: Deprecated alias for `scheduled_at`.
+        send_at: nil,
+        # Body param: Required unless `template_id` is supplied. When using a template,
+        # 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.
+        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.
+        template_variables: nil,
+        # Body param: Plain text email body. Returned only by `GET /email_messages/{id}`;
+        # omitted from create and list responses.
+        text_body: nil,
+        # Body param: Per-send open and click tracking overrides. Omitted properties
+        # inherit the sender domain's tracking settings.
+        tracking_settings: 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.
+        # Generate a unique UUID v4 for each operation and reuse it only when retrying
+        # that operation with the same request. Invalid headers—including duplicate,
+        # empty, malformed, or overlong values—return 400 with error code 10015. A request
+        # already in progress with the same key returns 409; reusing the key with a
+        # different request returns 422. Only successful responses are replayed, for up to
+        # 24 hours. Do not include sensitive data in the key.
+        idempotency_key: nil,
+        request_options: {}
+      )
+      end
+
+      # The legacy `/v2/emails/{id}` GET route is a backward-compatible alias for this
+      # operation.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailMessageRetrieveResponse)
+      end
+      def retrieve(
+        # Email message UUID.
+        id,
+        request_options: {}
+      )
+      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.
+      sig do
+        params(
+          page_cursor: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailMessageListResponse)
+      end
+      def list(
+        # 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,
+        request_options: {}
+      )
+      end
+
+      # Permanently deletes an account-scoped email message, its events, its durable
+      # recipients, and unshared attachment objects. Returns 404 when the message does
+      # not exist in the authenticated account. The legacy `/v2/emails/{id}` DELETE
+      # route is a backward-compatible alias.
+      sig do
+        params(id: String, request_options: Telnyx::RequestOptions::OrHash).void
+      end
+      def delete(
+        # Email message UUID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Creates up to 50 email messages in a single request.
+      sig do
+        params(
+          messages: T::Array[Telnyx::EmailMessageBatchParams::Message::OrHash],
+          sandbox_mode: T::Boolean,
+          idempotency_key: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailMessageBatchResponse)
+      end
+      def batch(
+        # Body param
+        messages:,
+        # Body param: Applies sandbox mode to all messages in the batch. Overrides any
+        # per-message sandbox_mode in the messages array.
+        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.
+        # Generate a unique UUID v4 for each operation and reuse it only when retrying
+        # that operation with the same request. Invalid headers—including duplicate,
+        # empty, malformed, or overlong values—return 400 with error code 10015. A request
+        # already in progress with the same key returns 409; reusing the key with a
+        # different request returns 422. Only successful responses are replayed, for up to
+        # 24 hours. Do not include sensitive data in the key.
+        idempotency_key: nil,
+        request_options: {}
+      )
+      end
+
+      # Permanently deletes every email in the authenticated account sent from or to the
+      # supplied address, including retained events whose parent message has expired.
+      # Events and durable recipients are deleted immediately with each message. The
+      # operation never searches or reports matches in another account. The legacy
+      # `/v2/emails` DELETE route is a backward-compatible alias.
+      sig do
+        params(
+          address: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).void
+      end
+      def delete_all(
+        # Sender or recipient address to delete. Matching is trimmed and case-insensitive.
+        address:,
+        request_options: {}
+      )
+      end
+
+      # Cancels a scheduled email and returns it with status `cancelled`. The legacy
+      # `/v2/emails/{id}/schedule` DELETE route is an alias.
+      sig do
+        params(
+          email_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailInboxes::EmailMessageResponse)
+      end
+      def delete_schedule(
+        # Email message UUID.
+        email_id,
+        request_options: {}
+      )
+      end
+
+      # 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.
+      sig do
+        params(
+          email_id: String,
+          page_cursor: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailMessageRetrieveEventsResponse)
+      end
+      def retrieve_events(
+        # Email message UUID.
+        email_id,
+        # 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,
+        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_templates.rbi

@@ -0,0 +1,167 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Create, list, retrieve, update, delete, and render Liquid email templates.
+    class EmailTemplates
+      # Creates a Liquid email template. Variables are auto-extracted when omitted.
+      sig do
+        params(
+          name: String,
+          html_body: T.nilable(String),
+          subject: T.nilable(String),
+          text_body: T.nilable(String),
+          variables: T::Array[String],
+          idempotency_key: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailTemplateResponse)
+      end
+      def create(
+        # Body param: Letters, numbers, spaces, hyphens, and underscores only.
+        name:,
+        # Body param: Liquid template HTML body.
+        html_body: nil,
+        # Body param: Liquid template subject.
+        subject: nil,
+        # Body param: Liquid template text body.
+        text_body: nil,
+        # Body param: Template variables. Auto-extracted from subject/body fields when
+        # absent.
+        variables: 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.
+        # Generate a unique UUID v4 for each operation and reuse it only when retrying
+        # that operation with the same request. Invalid headers—including duplicate,
+        # empty, malformed, or overlong values—return 400 with error code 10015. A request
+        # already in progress with the same key returns 409; reusing the key with a
+        # different request returns 422. Only successful responses are replayed, for up to
+        # 24 hours. Do not include sensitive data in the key.
+        idempotency_key: nil,
+        request_options: {}
+      )
+      end
+
+      # Get an email template
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailTemplateResponse)
+      end
+      def retrieve(
+        # Email template UUID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Updates one or more template fields.
+      sig do
+        params(
+          id: String,
+          html_body: T.nilable(String),
+          name: String,
+          subject: T.nilable(String),
+          text_body: T.nilable(String),
+          variables: T::Array[String],
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailTemplateResponse)
+      end
+      def update(
+        # Email template UUID.
+        id,
+        # Liquid template HTML body.
+        html_body: nil,
+        name: nil,
+        # Liquid template subject.
+        subject: nil,
+        # Liquid template text body.
+        text_body: nil,
+        variables: nil,
+        request_options: {}
+      )
+      end
+
+      # Lists templates sorted newest first by `created_at desc, id desc`.
+      sig do
+        params(
+          page_cursor: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailTemplateListResponse)
+      end
+      def list(
+        # 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,
+        request_options: {}
+      )
+      end
+
+      # Delete an email template
+      sig do
+        params(id: String, request_options: Telnyx::RequestOptions::OrHash).void
+      end
+      def delete(
+        # Email template UUID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Renders a template using the provided Liquid variables. Missing
+      # `template_variables` defaults to `{}`.
+      sig do
+        params(
+          id: String,
+          template_variables: T::Hash[Symbol, T.anything],
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailTemplateRenderResponse)
+      end
+      def render(
+        # Email template UUID.
+        id,
+        # Variables for Liquid template rendering. Non-object values are silently treated
+        # as an empty object.
+        template_variables: nil,
+        request_options: {}
+      )
+      end
+
+      # Replaces template fields. Behaves identically to PATCH; provided for
+      # compatibility with Phoenix resource routes.
+      sig do
+        params(
+          id: String,
+          html_body: T.nilable(String),
+          name: String,
+          subject: T.nilable(String),
+          text_body: T.nilable(String),
+          variables: T::Array[String],
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailTemplateResponse)
+      end
+      def replace(
+        # Email template UUID.
+        id,
+        # Liquid template HTML body.
+        html_body: nil,
+        name: nil,
+        # Liquid template subject.
+        subject: nil,
+        # Liquid template text body.
+        text_body: nil,
+        variables: 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_threads.rbi

@@ -0,0 +1,74 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Account-wide conversation threads across every inbox, for agents operating many
+    # inboxes at once.
+    class EmailThreads
+      # Returns a thread and a bounded page of its inbound and outbound messages,
+      # interleaved in chronological order. The `inbox_id` returned by the list endpoint
+      # is required because a thread ID can occur in multiple inboxes. Only messages
+      # matching that `(inbox_id, thread_id)` pair are returned. Threads outside the
+      # account return an opaque 404.
+      sig do
+        params(
+          thread_id: String,
+          inbox_id: String,
+          page_after: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailThreadRetrieveResponse)
+      end
+      def retrieve(
+        # Email thread UUID.
+        thread_id,
+        # Inbox UUID that, together with `thread_id`, identifies the thread.
+        inbox_id:,
+        # Opaque message cursor returned by the previous thread-detail page.
+        page_after: nil,
+        # Number of thread messages to return. Defaults to 25; maximum is 100.
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
+      # Lists thread summaries for the whole account, newest first, using stable cursor
+      # pagination. An agent operating many inboxes gets every conversation in one call
+      # instead of one call per inbox. Each thread carries its own `inbox_id` so a reply
+      # can be routed back to the right inbox. Use `filter[inbox_id]` (repeatable) to
+      # narrow the result to specific inboxes. Because a thread ID can be delivered to
+      # multiple inboxes, each result is identified by its `(inbox_id, id)` pair.
+      sig do
+        params(
+          filter_inbox_id: T::Array[String],
+          filter_label: String,
+          page_after: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailInboxes::InboundThreadListResponse)
+      end
+      def list(
+        # Restrict results to one or more inboxes. Repeat the parameter
+        # (`filter[inbox_id][]=...&filter[inbox_id][]=...`) or pass a comma-separated
+        # list. Omit to list every inbox in the account. Inboxes outside the account are
+        # silently excluded. If the filter is present, it must contain at least one
+        # non-empty UUID.
+        filter_inbox_id: nil,
+        # Returns only threads carrying this label. Matching is exact and case-sensitive.
+        # Thread labels are independent of the labels on the thread's messages.
+        filter_label: nil,
+        # Opaque cursor returned by the previous page.
+        page_after: nil,
+        # Number of results to return. Defaults to 25; maximum is 100.
+        page_size: 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_unsubscribe_groups/suppressions.rbi

@@ -0,0 +1,83 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailUnsubscribeGroups
+      # Named groups and group-scoped suppressions.
+      class Suppressions
+        # Creates a suppression with `reason: unsubscribe`, `source: manual`,
+        # `group_id: <this group>`. All other body fields are ignored; only `to` is read.
+        # Idempotent (same dedupe key → `200`, no new event).
+        sig do
+          params(
+            id: String,
+            to: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailBlockResponse)
+        end
+        def create(
+          # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+          id,
+          to:,
+          request_options: {}
+        )
+        end
+
+        # Account + group scoped. Offset pagination only (`page[number]` default 1,
+        # `page[size]` default 25, max 100). No `sort`/`filter`/ cursor — ordering fixed
+        # `desc created_at, desc id`. Uses the shared `QueryParser.parse_offset/1` — a
+        # malformed `page` returns `400` (code `10015`), consistent with
+        # `GET /v2/email_blocks`. `meta` includes `total_pages`. Rows reuse the standard
+        # suppression shape (`group_id` set to this group).
+        sig do
+          params(
+            id: String,
+            page_number: Integer,
+            page_size: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Internal::DefaultFlatPagination[Telnyx::EmailBlock])
+        end
+        def list(
+          # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+          id,
+          # Offset page number (≥1, default 1).
+          page_number: nil,
+          # Page size (1–100, default 25).
+          page_size: nil,
+          request_options: {}
+        )
+        end
+
+        # Soft-deletes all active blocks for (account, group, normalized email) — one
+        # `removed` audit event per block (`actor: manual`). The `email` path segment is
+        # normalized (trim + lower-case) before matching. Idempotent on already-removed
+        # rows (returns `404` since they're no longer `active`).
+        #
+        # Two distinct `404` cases: a missing/cross-account **group** returns
+        # `10001 "The requested unsubscribe group was not found"`; a group that exists but
+        # has **no active suppression** for that email returns
+        # `10001 "The requested group suppression was not found"`.
+        sig do
+          params(
+            email: String,
+            id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).void
+        end
+        def delete(
+          # Recipient address (normalized: trim + lower-case before matching).
+          email,
+          # 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