telnyx 5.158.0 → 5.159.0

data/lib/telnyx/resources/email_inboxes/drafts.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      # Create, list, retrieve, update, delete, and send unsent draft messages belonging
+      # to an agent inbox.
+      class Drafts
+        # Creates an unsent draft in the inbox. Every field is optional — a draft is a
+        # work-in-progress and may be saved incomplete. Send-time requirements (sender,
+        # subject, at least one recipient) are enforced when the draft is sent, not when
+        # it is created.
+        #
+        # Drafts are unbillable and emit no Email Detail Records until they are sent.
+        #
+        # @overload create(inbox_id, attachments: nil, bcc: nil, cc: nil, from_email: nil, from_name: nil, headers: nil, html: nil, html_body: nil, labels: nil, metadata: nil, reply_to: nil, subject: nil, tags: nil, text: nil, text_body: nil, to: nil, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param attachments [Array<Object>]
+        #
+        # @param bcc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>]
+        #
+        # @param cc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>]
+        #
+        # @param from_email [String]
+        #
+        # @param from_name [String]
+        #
+        # @param headers [Hash{Symbol=>String}]
+        #
+        # @param html [String] Alias for `html_body`, matching the send endpoint.
+        #
+        # @param html_body [String]
+        #
+        # @param labels [Array<String>]
+        #
+        # @param metadata [Object]
+        #
+        # @param reply_to [String]
+        #
+        # @param subject [String]
+        #
+        # @param tags [Array<String>]
+        #
+        # @param text [String] Alias for `text_body`, matching the send endpoint.
+        #
+        # @param text_body [String]
+        #
+        # @param to [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>]
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::EmailDraftResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftCreateParams
+        def create(inbox_id, params = {})
+          parsed, options = Telnyx::EmailInboxes::DraftCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["email_inboxes/%1$s/drafts", inbox_id],
+            body: parsed,
+            model: Telnyx::EmailInboxes::EmailDraftResponse,
+            options: options
+          )
+        end
+
+        # Returns a single draft. Drafts that have been sent remain retrievable, so the
+        # exact content that was sent stays auditable.
+        #
+        # @overload retrieve(draft_id, inbox_id:, request_options: {})
+        #
+        # @param draft_id [String] Email draft UUID.
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::EmailDraftResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftRetrieveParams
+        def retrieve(draft_id, params)
+          parsed, options = Telnyx::EmailInboxes::DraftRetrieveParams.dump_request(params)
+          inbox_id =
+            parsed.delete(:inbox_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["email_inboxes/%1$s/drafts/%2$s", inbox_id, draft_id],
+            model: Telnyx::EmailInboxes::EmailDraftResponse,
+            options: options
+          )
+        end
+
+        # Updates the supplied fields on a draft. `account_id` and `inbox_id` are
+        # server-owned and ignored if present in the body, so a draft can never be moved
+        # between accounts or inboxes.
+        #
+        # A draft that is being sent or has already been sent is immutable and returns 422
+        # — modifying it would race with delivery or rewrite the record of what was
+        # actually sent.
+        #
+        # @overload update(draft_id, inbox_id:, attachments: nil, bcc: nil, cc: nil, from_email: nil, from_name: nil, headers: nil, html: nil, html_body: nil, labels: nil, metadata: nil, reply_to: nil, subject: nil, tags: nil, text: nil, text_body: nil, to: nil, request_options: {})
+        #
+        # @param draft_id [String] Path param: Email draft UUID.
+        #
+        # @param inbox_id [String] Path param: Email inbox UUID.
+        #
+        # @param attachments [Array<Object>] Body param
+        #
+        # @param bcc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param cc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param from_email [String] Body param
+        #
+        # @param from_name [String] Body param
+        #
+        # @param headers [Hash{Symbol=>String}] Body param
+        #
+        # @param html [String] Body param: Alias for `html_body`, matching the send endpoint.
+        #
+        # @param html_body [String] Body param
+        #
+        # @param labels [Array<String>] Body param
+        #
+        # @param metadata [Object] Body param
+        #
+        # @param reply_to [String] Body param
+        #
+        # @param subject [String] Body param
+        #
+        # @param tags [Array<String>] Body param
+        #
+        # @param text [String] Body param: Alias for `text_body`, matching the send endpoint.
+        #
+        # @param text_body [String] Body param
+        #
+        # @param to [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::EmailDraftResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftUpdateParams
+        def update(draft_id, params)
+          parsed, options = Telnyx::EmailInboxes::DraftUpdateParams.dump_request(params)
+          inbox_id =
+            parsed.delete(:inbox_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :put,
+            path: ["email_inboxes/%1$s/drafts/%2$s", inbox_id, draft_id],
+            body: parsed,
+            model: Telnyx::EmailInboxes::EmailDraftResponse,
+            options: options
+          )
+        end
+
+        # Lists drafts newest first using stable cursor pagination. All access is scoped
+        # to the authenticated account and the given inbox.
+        #
+        # @overload list(inbox_id, filter_status: nil, page_after: nil, page_size: nil, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param filter_status [Symbol, Telnyx::Models::EmailInboxes::DraftListParams::FilterStatus] Restrict results to drafts in this state.
+        #
+        # @param page_after [String] Opaque cursor returned by the previous page.
+        #
+        # @param page_size [Integer] Number of results to return. Defaults to 25; maximum is 100.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::DraftListResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftListParams
+        def list(inbox_id, params = {})
+          parsed, options = Telnyx::EmailInboxes::DraftListParams.dump_request(params)
+          query = Telnyx::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["email_inboxes/%1$s/drafts", inbox_id],
+            query: query.transform_keys(
+              filter_status: "filter[status]",
+              page_after: "page[after]",
+              page_size: "page[size]"
+            ),
+            model: Telnyx::Models::EmailInboxes::DraftListResponse,
+            options: options
+          )
+        end
+
+        # Permanently deletes an unsent draft. Drafts that are being sent or have been
+        # sent cannot be deleted; sent drafts are retained for audit.
+        #
+        # @overload delete(draft_id, inbox_id:, request_options: {})
+        #
+        # @param draft_id [String] Email draft UUID.
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftDeleteParams
+        def delete(draft_id, params)
+          parsed, options = Telnyx::EmailInboxes::DraftDeleteParams.dump_request(params)
+          inbox_id =
+            parsed.delete(:inbox_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :delete,
+            path: ["email_inboxes/%1$s/drafts/%2$s", inbox_id, draft_id],
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Identical to `PUT`; both apply a partial update to the supplied fields.
+        #
+        # @overload patch(draft_id, inbox_id:, attachments: nil, bcc: nil, cc: nil, from_email: nil, from_name: nil, headers: nil, html: nil, html_body: nil, labels: nil, metadata: nil, reply_to: nil, subject: nil, tags: nil, text: nil, text_body: nil, to: nil, request_options: {})
+        #
+        # @param draft_id [String] Path param: Email draft UUID.
+        #
+        # @param inbox_id [String] Path param: Email inbox UUID.
+        #
+        # @param attachments [Array<Object>] Body param
+        #
+        # @param bcc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param cc [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param from_email [String] Body param
+        #
+        # @param from_name [String] Body param
+        #
+        # @param headers [Hash{Symbol=>String}] Body param
+        #
+        # @param html [String] Body param: Alias for `html_body`, matching the send endpoint.
+        #
+        # @param html_body [String] Body param
+        #
+        # @param labels [Array<String>] Body param
+        #
+        # @param metadata [Object] Body param
+        #
+        # @param reply_to [String] Body param
+        #
+        # @param subject [String] Body param
+        #
+        # @param tags [Array<String>] Body param
+        #
+        # @param text [String] Body param: Alias for `text_body`, matching the send endpoint.
+        #
+        # @param text_body [String] Body param
+        #
+        # @param to [Array<String, Telnyx::Models::EmailInboxes::EmailAddress>] Body param
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::EmailDraftResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftPatchParams
+        def patch(draft_id, params)
+          parsed, options = Telnyx::EmailInboxes::DraftPatchParams.dump_request(params)
+          inbox_id =
+            parsed.delete(:inbox_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :patch,
+            path: ["email_inboxes/%1$s/drafts/%2$s", inbox_id, draft_id],
+            body: parsed,
+            model: Telnyx::EmailInboxes::EmailDraftResponse,
+            options: options
+          )
+        end
+
+        # Sends the draft through the standard send pipeline — the same domain resolution,
+        # suppression, reputation, daily-quota, persistence and Detail Record behaviour as
+        # `POST /v2/email_messages`. The response body is the created email message.
+        #
+        # If the draft has no explicit `from_email`, the inbox address is used.
+        #
+        # The draft is marked `sent` only after the send is accepted; a send rejected for
+        # suppression, quota or reputation leaves the draft editable so it can be fixed
+        # and retried. A draft that is already `sent` returns 422 rather than sending
+        # twice.
+        #
+        # @overload send_(draft_id, inbox_id:, request_options: {})
+        #
+        # @param draft_id [String] Email draft UUID.
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::EmailMessageResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::DraftSendParams
+        def send_(draft_id, params)
+          parsed, options = Telnyx::EmailInboxes::DraftSendParams.dump_request(params)
+          inbox_id =
+            parsed.delete(:inbox_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :post,
+            path: ["email_inboxes/%1$s/drafts/%2$s/send", inbox_id, draft_id],
+            model: Telnyx::EmailInboxes::EmailMessageResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/email_inboxes/filters.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class EmailInboxes
+      # Create and manage agent inboxes, retrieve inbound messages and threads, and
+      # reply to or forward messages.
+      class Filters
+        # Returns the inbox's sender allowlist and blocklist. Entries are normalized to
+        # lowercase. A blocklist match takes precedence over an allowlist match; when both
+        # lists are empty, all senders are accepted.
+        #
+        # @overload list(inbox_id, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::FilterListResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::FilterListParams
+        def list(inbox_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["email_inboxes/%1$s/filters", inbox_id],
+            model: Telnyx::Models::EmailInboxes::FilterListResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Adds entries to either the allowlist or blocklist. The operation is an
+        # idempotent set union: entries already present remain unchanged.
+        #
+        # @overload add(inbox_id, entries:, type:, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param entries [Array<String>]
+        #
+        # @param type [Symbol, Telnyx::Models::EmailInboxes::MutateInboxFiltersRequest::Type] The list to change.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::FilterAddResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::FilterAddParams
+        def add(inbox_id, params)
+          parsed, options = Telnyx::EmailInboxes::FilterAddParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["email_inboxes/%1$s/filters", inbox_id],
+            body: parsed,
+            model: Telnyx::Models::EmailInboxes::FilterAddResponse,
+            options: options
+          )
+        end
+
+        # Removes entries from either the allowlist or blocklist. The operation is
+        # idempotent: removing an entry that is not present still returns the current
+        # filter lists.
+        #
+        # @overload delete_all(inbox_id, entries:, type:, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param entries [Array<String>]
+        #
+        # @param type [Symbol, Telnyx::Models::EmailInboxes::MutateInboxFiltersRequest::Type] The list to change.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::FilterDeleteAllResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::FilterDeleteAllParams
+        def delete_all(inbox_id, params)
+          parsed, options = Telnyx::EmailInboxes::FilterDeleteAllParams.dump_request(params)
+          @client.request(
+            method: :delete,
+            path: ["email_inboxes/%1$s/filters", inbox_id],
+            body: parsed,
+            model: Telnyx::Models::EmailInboxes::FilterDeleteAllResponse,
+            options: options
+          )
+        end
+
+        # Replaces both sender filter lists atomically. Omitting either list clears that
+        # list. Use `POST` or `DELETE` for incremental changes.
+        #
+        # @overload replace(inbox_id, allowlist: nil, blocklist: nil, request_options: {})
+        #
+        # @param inbox_id [String] Email inbox UUID.
+        #
+        # @param allowlist [Array<String>]
+        #
+        # @param blocklist [Array<String>]
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::EmailInboxes::FilterReplaceResponse]
+        #
+        # @see Telnyx::Models::EmailInboxes::FilterReplaceParams
+        def replace(inbox_id, params = {})
+          parsed, options = Telnyx::EmailInboxes::FilterReplaceParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: ["email_inboxes/%1$s/filters", inbox_id],
+            body: parsed,
+            model: Telnyx::Models::EmailInboxes::FilterReplaceResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/email_inboxes/messages/actions.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+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 Actions
+          # Some parameter documentations has been truncated, see
+          # {Telnyx::Models::EmailInboxes::Messages::ActionForwardParams} for more details.
+          #
+          # Sends from the inbox address through the standard email send pipeline to
+          # caller-supplied To, Cc, and Bcc recipients. `to` must contain at least one
+          # recipient. Optional `text` and `html` are prepended to a forwarded-message block
+          # containing the original metadata and available body content. The subject is
+          # prefixed with `Fwd:` unless it already has that prefix.
+          #
+          # Threading headers are derived from the original message: `In-Reply-To` is set to
+          # its RFC Message-ID, and `References` contains the original References values
+          # plus that Message-ID, de-duplicated and limited to the most recent 20 values.
+          #
+          # @overload forward(message_id, inbox_id:, to:, bcc: nil, cc: nil, html: nil, text: nil, request_options: {})
+          #
+          # @param message_id [String] Path param: Inbound email message UUID.
+          #
+          # @param inbox_id [String] Path param: Email inbox UUID.
+          #
+          # @param to [String, Telnyx::Models::EmailInboxes::Messages::ActionForwardParams::To::UnionMember1, Array<String, Telnyx::Models::EmailInboxes::Messages::InboxActionEmailAddressInput::UnionMember1>] Body param: One recipient or a non-empty recipient array. Each recipient may be
+          #
+          # @param bcc [String, Telnyx::Models::EmailInboxes::Messages::InboxActionRecipientInput::UnionMember1, Array<String, Telnyx::Models::EmailInboxes::Messages::InboxActionEmailAddressInput::UnionMember1>] Body param: One recipient or a recipient array. Each recipient may be an email s
+          #
+          # @param cc [String, Telnyx::Models::EmailInboxes::Messages::InboxActionRecipientInput::UnionMember1, Array<String, Telnyx::Models::EmailInboxes::Messages::InboxActionEmailAddressInput::UnionMember1>] Body param: One recipient or a recipient array. Each recipient may be an email s
+          #
+          # @param html [String] Body param: Optional HTML note prepended to the generated forwarded-message bloc
+          #
+          # @param text [String] Body param: Optional plain-text note prepended to the generated forwarded-messag
+          #
+          # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Telnyx::Models::EmailInboxes::EmailMessageResponse]
+          #
+          # @see Telnyx::Models::EmailInboxes::Messages::ActionForwardParams
+          def forward(message_id, params)
+            parsed, options = Telnyx::EmailInboxes::Messages::ActionForwardParams.dump_request(params)
+            inbox_id =
+              parsed.delete(:inbox_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :post,
+              path: ["email_inboxes/%1$s/messages/%2$s/actions/forward", inbox_id, message_id],
+              body: parsed,
+              model: Telnyx::EmailInboxes::EmailMessageResponse,
+              options: options
+            )
+          end
+
+          # Sends from the inbox address through the standard email send pipeline. The
+          # recipient is the original `Reply-To`, falling back to `From`; original Cc
+          # recipients are not included. The subject is prefixed with `Re:` unless it
+          # already has that prefix.
+          #
+          # Threading headers are derived from the original message: `In-Reply-To` is set to
+          # its RFC Message-ID, and `References` contains the original References values
+          # plus that Message-ID, de-duplicated and limited to the most recent 20 values.
+          #
+          # @overload reply(message_id, inbox_id:, html: nil, text: nil, request_options: {})
+          #
+          # @param message_id [String] Path param: Inbound email message UUID.
+          #
+          # @param inbox_id [String] Path param: Email inbox UUID.
+          #
+          # @param html [String] Body param: HTML reply body.
+          #
+          # @param text [String] Body param: Plain-text reply body.
+          #
+          # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Telnyx::Models::EmailInboxes::EmailMessageResponse]
+          #
+          # @see Telnyx::Models::EmailInboxes::Messages::ActionReplyParams
+          def reply(message_id, params)
+            parsed, options = Telnyx::EmailInboxes::Messages::ActionReplyParams.dump_request(params)
+            inbox_id =
+              parsed.delete(:inbox_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :post,
+              path: ["email_inboxes/%1$s/messages/%2$s/actions/reply", inbox_id, message_id],
+              body: parsed,
+              model: Telnyx::EmailInboxes::EmailMessageResponse,
+              options: options
+            )
+          end
+
+          # Sends from the inbox address through the standard email send pipeline. The To
+          # list starts with the original `Reply-To` (or `From`) and includes original To
+          # recipients; the Cc list includes original Cc recipients. The inbox address is
+          # excluded, and recipients are de-duplicated case-insensitively across To and Cc.
+          # Bcc is always empty. The subject is prefixed with `Re:` unless it already has
+          # that prefix.
+          #
+          # Threading headers are derived from the original message: `In-Reply-To` is set to
+          # its RFC Message-ID, and `References` contains the original References values
+          # plus that Message-ID, de-duplicated and limited to the most recent 20 values.
+          #
+          # @overload reply_all(message_id, inbox_id:, html: nil, text: nil, request_options: {})
+          #
+          # @param message_id [String] Path param: Inbound email message UUID.
+          #
+          # @param inbox_id [String] Path param: Email inbox UUID.
+          #
+          # @param html [String] Body param: HTML reply body.
+          #
+          # @param text [String] Body param: Plain-text reply body.
+          #
+          # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Telnyx::Models::EmailInboxes::EmailMessageResponse]
+          #
+          # @see Telnyx::Models::EmailInboxes::Messages::ActionReplyAllParams
+          def reply_all(message_id, params)
+            parsed, options = Telnyx::EmailInboxes::Messages::ActionReplyAllParams.dump_request(params)
+            inbox_id =
+              parsed.delete(:inbox_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :post,
+              path: ["email_inboxes/%1$s/messages/%2$s/actions/reply_all", inbox_id, message_id],
+              body: parsed,
+              model: Telnyx::EmailInboxes::EmailMessageResponse,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Telnyx::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end