telnyx 5.158.0 → 5.159.0

data/rbi/telnyx/resources/email_inboxes/messages/labels.rbi

@@ -0,0 +1,80 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      class Messages
+        # Create and manage agent inboxes, retrieve inbound messages and threads, and
+        # reply to or forward messages.
+        class Labels
+          # Adds one or more mutable labels to a message. Labels carry agent workflow state
+          # such as `spam`, `needs_review`, or `processed`.
+          #
+          # Labels are **not** the same as the send-time `tags` on outbound messages: `tags`
+          # are immutable and propagate to Email Detail Records and Mission Control for
+          # billing attribution, while labels are mailbox state that never reaches the
+          # reporting contract.
+          #
+          # The operation is an idempotent set union — adding a label the message already
+          # carries is a no-op and still returns 200. Labels are case-sensitive, and message
+          # labels are independent of thread labels.
+          sig do
+            params(
+              message_id: String,
+              inbox_id: String,
+              labels: T::Array[String],
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::EmailInboxes::Messages::LabelCreateResponse
+            )
+          end
+          def create(
+            # Path param: Inbound message UUID.
+            message_id,
+            # Path param: Email inbox UUID.
+            inbox_id:,
+            # Body param: One or more labels. Each label is a freeform, case-sensitive string
+            # of at most 255 characters; a message or thread may carry at most 50 labels. The
+            # `telnyx:` prefix is a reserved system namespace and is rejected on customer
+            # writes.
+            labels:,
+            request_options: {}
+          )
+          end
+
+          # Removes one or more labels from a message. Idempotent — removing a label the
+          # message does not carry is a no-op and still returns 200. Removal is
+          # case-sensitive.
+          sig do
+            params(
+              message_id: String,
+              inbox_id: String,
+              labels: T::Array[String],
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::EmailInboxes::Messages::LabelDeleteAllResponse
+            )
+          end
+          def delete_all(
+            # Path param: Inbound message UUID.
+            message_id,
+            # Path param: Email inbox UUID.
+            inbox_id:,
+            # Body param: One or more labels. Each label is a freeform, case-sensitive string
+            # of at most 255 characters; a message or thread may carry at most 50 labels. The
+            # `telnyx:` prefix is a reserved system namespace and is rejected on customer
+            # writes.
+            labels:,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_inboxes/messages.rbi

@@ -0,0 +1,185 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      class Messages
+        # Create and manage agent inboxes, retrieve inbound messages and threads, and
+        # reply to or forward messages.
+        sig { returns(Telnyx::Resources::EmailInboxes::Messages::Actions) }
+        attr_reader :actions
+
+        # Create and manage agent inboxes, retrieve inbound messages and threads, and
+        # reply to or forward messages.
+        sig { returns(Telnyx::Resources::EmailInboxes::Messages::Labels) }
+        attr_reader :labels
+
+        # Updates the explicit read state of an account-scoped inbound message. Set
+        # `read_at` to `true` to mark the message read at the server's current time, to an
+        # ISO 8601 timestamp to use that timestamp, or to `null` to mark the message
+        # unread. Repeating the same update is idempotent.
+        sig do
+          params(
+            message_id: String,
+            inbox_id: String,
+            read_at:
+              T.nilable(
+                T.any(
+                  Telnyx::EmailInboxes::MessageUpdateParams::ReadAt::OrBoolean,
+                  Time
+                )
+              ),
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::EmailInboxes::MessageUpdateResponse)
+        end
+        def update(
+          # Path param: Inbound email message UUID.
+          message_id,
+          # Path param: Email inbox UUID.
+          inbox_id:,
+          # Body param: Set to `true` for server time, an ISO 8601 timestamp for an explicit
+          # read time, or `null` to mark unread.
+          read_at:,
+          request_options: {}
+        )
+        end
+
+        # Lists inbound messages newest first. All access is scoped to the authenticated
+        # account. `filter[search]` performs PostgreSQL full-text search over the subject,
+        # plain-text body, and HTML body. Filters compose with stable cursor pagination.
+        sig do
+          params(
+            inbox_id: String,
+            filter_from: String,
+            filter_label: String,
+            filter_read: T::Boolean,
+            filter_received_after: Time,
+            filter_received_before: Time,
+            filter_search: String,
+            filter_subject: String,
+            filter_unread: T::Boolean,
+            page_after: String,
+            page_size: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::EmailInboxes::MessageListResponse)
+        end
+        def list(
+          # Email inbox UUID.
+          inbox_id,
+          # Case-insensitive literal substring of the sender address.
+          filter_from: nil,
+          # Returns only messages carrying this label. Matching is exact and case-sensitive.
+          # Reserved `telnyx:` labels can be filtered on even though they cannot be written
+          # by customers.
+          filter_label: nil,
+          # Whether the message has a read timestamp.
+          filter_read: nil,
+          # Inclusive ISO 8601 lower bound for the received timestamp.
+          filter_received_after: nil,
+          # Inclusive ISO 8601 upper bound for the received timestamp.
+          filter_received_before: nil,
+          # Full-text query over subject and body, up to 500 characters.
+          filter_search: nil,
+          # Case-insensitive literal substring of the subject.
+          filter_subject: nil,
+          # Whether the message has no read timestamp. Set to `true` to return only unread
+          # messages.
+          filter_unread: 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
+
+        # Creates an unsent reply draft for an inbound message. Unlike the
+        # `/actions/reply` endpoint, which sends immediately, this stores a draft that can
+        # be reviewed and edited before sending.
+        #
+        # `reply_to_message_id` and `thread_id` are inherited from the parent message and
+        # cannot be set by the caller. The recipient, `Re:` subject and
+        # `In-Reply-To`/`References` headers are pre-filled from the parent using the same
+        # rules as a live reply, so sending the draft threads identically. Supplying `to`
+        # or `subject` explicitly overrides the pre-filled value.
+        sig do
+          params(
+            message_id: String,
+            inbox_id: String,
+            attachments: T::Array[T.anything],
+            bcc:
+              T::Array[
+                T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)
+              ],
+            cc:
+              T::Array[
+                T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)
+              ],
+            from_email: String,
+            from_name: String,
+            headers: T::Hash[Symbol, String],
+            html: String,
+            html_body: String,
+            labels: T::Array[String],
+            metadata: T.anything,
+            reply_to: String,
+            subject: String,
+            tags: T::Array[String],
+            text: String,
+            text_body: String,
+            to:
+              T::Array[
+                T.any(String, Telnyx::EmailInboxes::EmailAddress::OrHash)
+              ],
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailInboxes::EmailDraftResponse)
+        end
+        def drafts(
+          # Path param: Inbound message UUID to reply to.
+          message_id,
+          # Path param: Email inbox UUID.
+          inbox_id:,
+          # Body param
+          attachments: nil,
+          # Body param
+          bcc: nil,
+          # Body param
+          cc: nil,
+          # Body param
+          from_email: nil,
+          # Body param
+          from_name: nil,
+          # Body param
+          headers: nil,
+          # Body param: Alias for `html_body`, matching the send endpoint.
+          html: nil,
+          # Body param
+          html_body: nil,
+          # Body param
+          labels: nil,
+          # Body param
+          metadata: nil,
+          # Body param
+          reply_to: nil,
+          # Body param
+          subject: nil,
+          # Body param
+          tags: nil,
+          # Body param: Alias for `text_body`, matching the send endpoint.
+          text: nil,
+          # Body param
+          text_body: nil,
+          # Body param
+          to: nil,
+          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_inboxes/threads/labels.rbi

@@ -0,0 +1,75 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      class Threads
+        # Create and manage agent inboxes, retrieve inbound messages and threads, and
+        # reply to or forward messages.
+        class Labels
+          # Adds one or more mutable labels to a thread, letting an agent mark a whole
+          # conversation (for example `needs_review`) without labelling each message
+          # individually.
+          #
+          # Thread labels are independent of message labels: labelling a thread does not
+          # label its messages, and labelling a message does not label its thread.
+          # Idempotent and case-sensitive.
+          sig do
+            params(
+              thread_id: String,
+              inbox_id: String,
+              labels: T::Array[String],
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::EmailInboxes::Threads::LabelCreateResponse
+            )
+          end
+          def create(
+            # Path param: Thread UUID.
+            thread_id,
+            # Path param: Email inbox UUID.
+            inbox_id:,
+            # Body param: One or more labels. Each label is a freeform, case-sensitive string
+            # of at most 255 characters; a message or thread may carry at most 50 labels. The
+            # `telnyx:` prefix is a reserved system namespace and is rejected on customer
+            # writes.
+            labels:,
+            request_options: {}
+          )
+          end
+
+          # Removes one or more labels from a thread. Idempotent — removing a label the
+          # thread does not carry is a no-op and still returns 200.
+          sig do
+            params(
+              thread_id: String,
+              inbox_id: String,
+              labels: T::Array[String],
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::EmailInboxes::Threads::LabelDeleteAllResponse
+            )
+          end
+          def delete_all(
+            # Path param: Thread UUID.
+            thread_id,
+            # Path param: Email inbox UUID.
+            inbox_id:,
+            # Body param: One or more labels. Each label is a freeform, case-sensitive string
+            # of at most 255 characters; a message or thread may carry at most 50 labels. The
+            # `telnyx:` prefix is a reserved system namespace and is rejected on customer
+            # writes.
+            labels:,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_inboxes/threads.rbi

@@ -0,0 +1,70 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      # Create and manage agent inboxes, retrieve inbound messages and threads, and
+      # reply to or forward messages.
+      class Threads
+        # Create and manage agent inboxes, retrieve inbound messages and threads, and
+        # reply to or forward messages.
+        sig { returns(Telnyx::Resources::EmailInboxes::Threads::Labels) }
+        attr_reader :labels
+
+        # Returns a bounded page of inbound and outbound thread messages interleaved in
+        # chronological order using stable cursor pagination.
+        sig do
+          params(
+            thread_id: String,
+            inbox_id: String,
+            page_after: String,
+            page_size: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::EmailInboxes::ThreadRetrieveResponse)
+        end
+        def retrieve(
+          # Path param: Email thread UUID.
+          thread_id,
+          # Path param: Email inbox UUID.
+          inbox_id:,
+          # Query param: Opaque message cursor returned by the previous thread-detail page.
+          page_after: nil,
+          # Query param: Number of thread messages to return. Defaults to 25; maximum
+          # is 100.
+          page_size: nil,
+          request_options: {}
+        )
+        end
+
+        # Lists thread summaries newest first using stable cursor pagination.
+        sig do
+          params(
+            inbox_id: String,
+            filter_label: String,
+            page_after: String,
+            page_size: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailInboxes::InboundThreadListResponse)
+        end
+        def list(
+          # Email inbox UUID.
+          inbox_id,
+          # Returns only threads carrying this label. 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
+end

data/rbi/telnyx/resources/email_inboxes.rbi

@@ -0,0 +1,100 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Create and manage agent inboxes, retrieve inbound messages and threads, and
+    # reply to or forward messages.
+    class EmailInboxes
+      # Create, list, retrieve, update, delete, and send unsent draft messages belonging
+      # to an agent inbox.
+      sig { returns(Telnyx::Resources::EmailInboxes::Drafts) }
+      attr_reader :drafts
+
+      # Create and manage agent inboxes, retrieve inbound messages and threads, and
+      # reply to or forward messages.
+      sig { returns(Telnyx::Resources::EmailInboxes::Filters) }
+      attr_reader :filters
+
+      sig { returns(Telnyx::Resources::EmailInboxes::Messages) }
+      attr_reader :messages
+
+      # Create and manage agent inboxes, retrieve inbound messages and threads, and
+      # reply to or forward messages.
+      sig { returns(Telnyx::Resources::EmailInboxes::Threads) }
+      attr_reader :threads
+
+      # Creates an inbox on an inbound-enabled domain. When `domain_id` is omitted,
+      # Telnyx allocates the account's shared inbound subdomain so the inbox is
+      # immediately usable without customer DNS setup. When `username` is omitted, a
+      # unique username is generated.
+      sig do
+        params(
+          domain_id: String,
+          username: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailInboxResponse)
+      end
+      def create(
+        # Account-owned, inbound-enabled domain UUID. The account's shared inbound
+        # subdomain is allocated when omitted.
+        domain_id: nil,
+        # Inbox local part. Trimmed and lowercased before validation; the normalized value
+        # must be 1-64 characters, start and end with a letter or digit, and contain only
+        # letters, digits, dots, hyphens, and underscores. Generated when omitted.
+        username: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns an account-scoped, non-deleted inbox. Missing and foreign inboxes are
+      # indistinguishable.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::EmailInboxResponse)
+      end
+      def retrieve(
+        # Email inbox UUID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Lists the account's non-deleted inboxes newest first using stable cursor
+      # pagination.
+      sig do
+        params(
+          page_cursor: String,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::EmailInboxListResponse)
+      end
+      def list(
+        # Opaque cursor returned by the previous inbox page.
+        page_cursor: nil,
+        # Number of results to return. Defaults to 20; maximum is 250.
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
+      # Soft-deletes an account-scoped inbox. Its address remains reserved and the inbox
+      # is no longer returned by list or get operations.
+      sig do
+        params(id: String, request_options: Telnyx::RequestOptions::OrHash).void
+      end
+      def delete(
+        # Email inbox UUID.
+        id,
+        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_messages/recipients.rbi

@@ -0,0 +1,66 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailMessages
+      # Send and manage email messages. Legacy `/v2/emails` routes are aliases for these
+      # endpoints.
+      class Recipients
+        # Returns the current delivery state of a single recipient, including status,
+        # billable flag, SMTP detail, and lifecycle timestamps. BCC recipient addresses
+        # are redacted (returned as null).
+        sig do
+          params(
+            recipient_id: String,
+            email_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::EmailMessages::RecipientRetrieveResponse)
+        end
+        def retrieve(
+          # Recipient UUID.
+          recipient_id,
+          # Email message UUID.
+          email_id:,
+          request_options: {}
+        )
+        end
+
+        # Lists per-recipient delivery states for a single message with cursor pagination.
+        # Each recipient has an independent status, billable flag, and lifecycle
+        # timestamps. BCC recipient addresses are redacted (returned as null) to protect
+        # BCC privacy. Default page size is 25, maximum is 100.
+        sig do
+          params(
+            email_id: String,
+            kind: Telnyx::EmailMessages::RecipientListParams::Kind::OrSymbol,
+            page_cursor: String,
+            page_size: Integer,
+            status:
+              Telnyx::EmailMessages::RecipientListParams::Status::OrSymbol,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::EmailMessages::RecipientListResponse)
+        end
+        def list(
+          # Email message UUID.
+          email_id,
+          # Filter recipients by address kind.
+          kind: 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,
+          # Filter recipients by status.
+          status: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end