telnyx 5.169.0 → 5.170.0

data/lib/telnyx/models/email_event_list_response.rb

@@ -4,101 +4,328 @@ module Telnyx
   module Models
     # @see Telnyx::Resources::EmailEvents#list
     class EmailEventListResponse < Telnyx::Internal::Type::BaseModel
-      # @!attribute id
+      # @!attribute data
       #
-      #   @return [String]
-      required :id, String
+      #   @return [Array<Telnyx::Models::EmailEventListResponse::Data>]
+      required :data, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::Models::EmailEventListResponse::Data] }
 
-      # @!attribute email_id
+      # @!attribute meta
       #
-      #   @return [String]
-      required :email_id, String
+      #   @return [Telnyx::Models::EmailEventListResponse::Meta]
+      required :meta, -> { Telnyx::Models::EmailEventListResponse::Meta }
 
-      # @!attribute occurred_at
-      #
-      #   @return [Time]
-      required :occurred_at, Time
+      # @!method initialize(data:, meta:)
+      #   @param data [Array<Telnyx::Models::EmailEventListResponse::Data>]
+      #   @param meta [Telnyx::Models::EmailEventListResponse::Meta]
 
-      # @!attribute record_type
-      #
-      #   @return [Symbol, Telnyx::Models::EmailEventListResponse::RecordType]
-      required :record_type, enum: -> { Telnyx::Models::EmailEventListResponse::RecordType }
+      class Data < Telnyx::Internal::Type::BaseModel
+        # @!attribute id
+        #   Event UUID.
+        #
+        #   @return [String]
+        required :id, String
 
-      # @!attribute type
-      #
-      #   @return [Symbol, Telnyx::Models::EmailEventType]
-      required :type, enum: -> { Telnyx::EmailEventType }
+        # @!attribute canonical_event_type
+        #   Additive canonical outcome name, prefixed with `email.`. Gateway rejection is
+        #   `email.gw_reject`, ambiguous injection timeout is `email.injection_timeout`, and
+        #   MTA expiration is `email.expired`. Unchanged outcomes retain their names.
+        #   Existing stored rows are translated only when recorded payload evidence proves
+        #   the outcome; a legacy failed row is not guessed or sharpened.
+        #
+        #   @return [String]
+        required :canonical_event_type, String
 
-      # @!attribute email
-      #   Summary of the associated email message. Present when the email_message preload
-      #   is available.
-      #
-      #   @return [Telnyx::Models::EmailEventListResponse::Email, nil]
-      optional :email, -> { Telnyx::Models::EmailEventListResponse::Email }
+        # @!attribute event_type
+        #   Legacy customer-visible event name, prefixed with `email.`. Gateway rejections
+        #   render `email.failed`; MTA expirations render `email.bounced`. Webhook
+        #   subscription allowlists match the legacy name.
+        #
+        #   @return [String]
+        required :event_type, String
 
-      # @!attribute payload
-      #
-      #   @return [Hash{Symbol=>Object}, nil]
-      optional :payload, Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown]
+        # @!attribute occurred_at
+        #
+        #   @return [Time]
+        required :occurred_at, Time
 
-      # @!method initialize(id:, email_id:, occurred_at:, record_type:, type:, email: nil, payload: nil)
-      #   Some parameter documentations has been truncated, see
-      #   {Telnyx::Models::EmailEventListResponse} for more details.
-      #
-      #   @param id [String]
-      #
-      #   @param email_id [String]
-      #
-      #   @param occurred_at [Time]
-      #
-      #   @param record_type [Symbol, Telnyx::Models::EmailEventListResponse::RecordType]
-      #
-      #   @param type [Symbol, Telnyx::Models::EmailEventType]
-      #
-      #   @param email [Telnyx::Models::EmailEventListResponse::Email] Summary of the associated email message. Present when the email_message preload
-      #
-      #   @param payload [Hash{Symbol=>Object}]
+        # @!attribute payload
+        #   Payload returned by GET /email_events. Every row includes id, status, and
+        #   occurred_at. Recipient-scoped rows also include recipient_id, from, subject, and
+        #   exactly one object-valued to, cc, or bcc field. Legacy or message-scoped rows
+        #   can omit recipient_id and use object-valued or string-valued to/cc fields,
+        #   including an empty string when no address exists; bcc is redacted. If the
+        #   related message or recipient cannot be loaded, the minimal fallback can omit
+        #   from, subject, and recipient fields. Additional persisted public evidence can be
+        #   present.
+        #
+        #   @return [Telnyx::Models::EmailEventListResponse::Data::Payload]
+        required :payload, -> { Telnyx::Models::EmailEventListResponse::Data::Payload }
+
+        # @!attribute recipient_id
+        #   Durable email recipient UUID. Present for recipient-scoped events, including
+        #   each queued, sending, sandbox, cancelled, and daily_limit_exceeded fan-out
+        #   event.
+        #
+        #   @return [String, nil]
+        optional :recipient_id, String
+
+        # @!method initialize(id:, canonical_event_type:, event_type:, occurred_at:, payload:, recipient_id: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Telnyx::Models::EmailEventListResponse::Data} for more details.
+        #
+        #   An account-polling event. The envelope is webhook-shaped, but polling preserves
+        #   stored-event cardinality: queued, sending, sandbox, cancelled, and
+        #   daily_limit_exceeded message events fan out per recipient; scheduled remains one
+        #   message-scoped row. Payload fields vary among recipient-scoped, message-scoped,
+        #   and minimal fallback rows.
+        #
+        #   @param id [String] Event UUID.
+        #
+        #   @param canonical_event_type [String] Additive canonical outcome name, prefixed with `email.`. Gateway rejection is `e
+        #
+        #   @param event_type [String] Legacy customer-visible event name, prefixed with `email.`. Gateway rejections r
+        #
+        #   @param occurred_at [Time]
+        #
+        #   @param payload [Telnyx::Models::EmailEventListResponse::Data::Payload] Payload returned by GET /email_events. Every row includes id, status, and occurr
+        #
+        #   @param recipient_id [String] Durable email recipient UUID. Present for recipient-scoped events, including eac
+
+        # @see Telnyx::Models::EmailEventListResponse::Data#payload
+        class Payload < Telnyx::Internal::Type::BaseModel
+          # @!attribute id
+          #   Email message UUID.
+          #
+          #   @return [String]
+          required :id, String
 
-      # @see Telnyx::Models::EmailEventListResponse#record_type
-      module RecordType
-        extend Telnyx::Internal::Type::Enum
+          # @!attribute occurred_at
+          #
+          #   @return [Time]
+          required :occurred_at, Time
 
-        EMAIL_EVENT = :email_event
+          # @!attribute status
+          #   Stored event outcome slug, not the authoritative recipient status. Account
+          #   polling returns the stored name, including suppression, scan, and quarantine
+          #   lifecycle names. Webhooks retain legacy payload names: gateway rejections use
+          #   failed and MTA expirations use bounced. New sharp stored rows can expose
+          #   gw_reject, injection_timeout, or expired. Use the envelope canonical_event_type
+          #   to identify the outcome across surfaces.
+          #
+          #   @return [Symbol, Telnyx::Models::EmailEventListResponse::Data::Payload::Status]
+          required :status, enum: -> { Telnyx::Models::EmailEventListResponse::Data::Payload::Status }
 
-        # @!method self.values
-        #   @return [Array<Symbol>]
+          # @!attribute bcc
+          #
+          #   @return [Telnyx::Models::EmailWebhookRecipient, Symbol, Telnyx::Models::EmailEventListResponse::Data::Payload::Bcc, nil]
+          optional :bcc, union: -> { Telnyx::Models::EmailEventListResponse::Data::Payload::Bcc }
+
+          # @!attribute cc
+          #   Legacy message-scoped address, or an empty string when absent.
+          #
+          #   @return [Telnyx::Models::EmailWebhookRecipient, String, nil]
+          optional :cc, union: -> { Telnyx::Models::EmailEventListResponse::Data::Payload::Cc }
+
+          # @!attribute from
+          #   Sender projection in account event polling. The display name is explicitly null
+          #   when the message has no sender name.
+          #
+          #   @return [Telnyx::Models::EmailEventListResponse::Data::Payload::From, nil]
+          optional :from, -> { Telnyx::Models::EmailEventListResponse::Data::Payload::From }
+
+          # @!attribute recipient_id
+          #   Durable email recipient UUID. Present for recipient-scoped events.
+          #
+          #   @return [String, nil]
+          optional :recipient_id, String
+
+          # @!attribute subject
+          #
+          #   @return [String, nil]
+          optional :subject, String
+
+          # @!attribute to
+          #   Legacy message-scoped address, or an empty string when absent.
+          #
+          #   @return [Telnyx::Models::EmailWebhookRecipient, String, nil]
+          optional :to, union: -> { Telnyx::Models::EmailEventListResponse::Data::Payload::To }
+
+          # @!method initialize(id:, occurred_at:, status:, bcc: nil, cc: nil, from: nil, recipient_id: nil, subject: nil, to: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Telnyx::Models::EmailEventListResponse::Data::Payload} for more details.
+          #
+          #   Payload returned by GET /email_events. Every row includes id, status, and
+          #   occurred_at. Recipient-scoped rows also include recipient_id, from, subject, and
+          #   exactly one object-valued to, cc, or bcc field. Legacy or message-scoped rows
+          #   can omit recipient_id and use object-valued or string-valued to/cc fields,
+          #   including an empty string when no address exists; bcc is redacted. If the
+          #   related message or recipient cannot be loaded, the minimal fallback can omit
+          #   from, subject, and recipient fields. Additional persisted public evidence can be
+          #   present.
+          #
+          #   @param id [String] Email message UUID.
+          #
+          #   @param occurred_at [Time]
+          #
+          #   @param status [Symbol, Telnyx::Models::EmailEventListResponse::Data::Payload::Status] Stored event outcome slug, not the authoritative recipient status. Account polli
+          #
+          #   @param bcc [Telnyx::Models::EmailWebhookRecipient, Symbol, Telnyx::Models::EmailEventListResponse::Data::Payload::Bcc]
+          #
+          #   @param cc [Telnyx::Models::EmailWebhookRecipient, String] Legacy message-scoped address, or an empty string when absent.
+          #
+          #   @param from [Telnyx::Models::EmailEventListResponse::Data::Payload::From] Sender projection in account event polling. The display name is explicitly null
+          #
+          #   @param recipient_id [String] Durable email recipient UUID. Present for recipient-scoped events.
+          #
+          #   @param subject [String]
+          #
+          #   @param to [Telnyx::Models::EmailWebhookRecipient, String] Legacy message-scoped address, or an empty string when absent.
+
+          # Stored event outcome slug, not the authoritative recipient status. Account
+          # polling returns the stored name, including suppression, scan, and quarantine
+          # lifecycle names. Webhooks retain legacy payload names: gateway rejections use
+          # failed and MTA expirations use bounced. New sharp stored rows can expose
+          # gw_reject, injection_timeout, or expired. Use the envelope canonical_event_type
+          # to identify the outcome across surfaces.
+          #
+          # @see Telnyx::Models::EmailEventListResponse::Data::Payload#status
+          module Status
+            extend Telnyx::Internal::Type::Enum
+
+            QUEUED = :queued
+            DEFERRED = :deferred
+            SCHEDULED = :scheduled
+            CANCELLED = :cancelled
+            SANDBOX = :sandbox
+            SENDING = :sending
+            SENT = :sent
+            FAILED = :failed
+            DELIVERED = :delivered
+            BOUNCED = :bounced
+            COMPLAINED = :complained
+            SUPPRESSED = :suppressed
+            REJECTED = :rejected
+            OPENED = :opened
+            CLICKED = :clicked
+            UNSUBSCRIBED = :unsubscribed
+            DAILY_LIMIT_EXCEEDED = :daily_limit_exceeded
+            SCAN_DEFERRED = :scan_deferred
+            QUARANTINED = :quarantined
+            QUARANTINE_RELEASED = :quarantine_released
+            QUARANTINE_RELEASE_DISPATCHED = :quarantine_release_dispatched
+            QUARANTINE_REJECTED = :quarantine_rejected
+            QUARANTINE_EXPIRED = :quarantine_expired
+            GW_REJECT = :gw_reject
+            INJECTION_TIMEOUT = :injection_timeout
+            EXPIRED = :expired
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+
+          # @see Telnyx::Models::EmailEventListResponse::Data::Payload#bcc
+          module Bcc
+            extend Telnyx::Internal::Type::Union
+
+            variant -> { Telnyx::EmailWebhookRecipient }
+
+            variant const: -> { Telnyx::Models::EmailEventListResponse::Data::Payload::Bcc::REDACTED }
+
+            # @!method self.variants
+            #   @return [Array(Telnyx::Models::EmailWebhookRecipient, Symbol)]
+
+            define_sorbet_constant!(:Variants) do
+              T.type_alias do
+                T.any(
+                  Telnyx::EmailWebhookRecipient,
+                  Telnyx::Models::EmailEventListResponse::Data::Payload::Bcc::TaggedSymbol
+                )
+              end
+            end
+
+            # @!group
+
+            REDACTED = :redacted
+
+            # @!endgroup
+          end
+
+          # Legacy message-scoped address, or an empty string when absent.
+          #
+          # @see Telnyx::Models::EmailEventListResponse::Data::Payload#cc
+          module Cc
+            extend Telnyx::Internal::Type::Union
+
+            variant -> { Telnyx::EmailWebhookRecipient }
+
+            # Legacy message-scoped address, or an empty string when absent.
+            variant String
+
+            # @!method self.variants
+            #   @return [Array(Telnyx::Models::EmailWebhookRecipient, String)]
+          end
+
+          # @see Telnyx::Models::EmailEventListResponse::Data::Payload#from
+          class From < Telnyx::Internal::Type::BaseModel
+            # @!attribute email
+            #
+            #   @return [String]
+            required :email, String
+
+            # @!attribute name
+            #
+            #   @return [String, nil]
+            required :name, String, nil?: true
+
+            # @!method initialize(email:, name:)
+            #   Sender projection in account event polling. The display name is explicitly null
+            #   when the message has no sender name.
+            #
+            #   @param email [String]
+            #   @param name [String, nil]
+          end
+
+          # Legacy message-scoped address, or an empty string when absent.
+          #
+          # @see Telnyx::Models::EmailEventListResponse::Data::Payload#to
+          module To
+            extend Telnyx::Internal::Type::Union
+
+            variant -> { Telnyx::EmailWebhookRecipient }
+
+            # Legacy message-scoped address, or an empty string when absent.
+            variant String
+
+            # @!method self.variants
+            #   @return [Array(Telnyx::Models::EmailWebhookRecipient, String)]
+          end
+        end
       end
 
-      # @see Telnyx::Models::EmailEventListResponse#email
-      class Email < Telnyx::Internal::Type::BaseModel
-        # @!attribute cc
+      # @see Telnyx::Models::EmailEventListResponse#meta
+      class Meta < Telnyx::Internal::Type::BaseModel
+        # @!attribute page_size
         #
-        #   @return [Array<Telnyx::Models::EmailInboxes::EmailAddress>]
-        required :cc, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::EmailInboxes::EmailAddress] }
+        #   @return [Integer]
+        required :page_size, Integer
 
-        # @!attribute from
+        # @!attribute time_range
         #
-        #   @return [Telnyx::Models::EmailInboxes::EmailAddress]
-        required :from, -> { Telnyx::EmailInboxes::EmailAddress }
+        #   @return [Telnyx::Models::TimeRange]
+        required :time_range, -> { Telnyx::TimeRange }
 
-        # @!attribute subject
+        # @!attribute page_cursor
+        #   Cursor for the next page, when more results are available.
         #
-        #   @return [String]
-        required :subject, String
+        #   @return [String, nil]
+        optional :page_cursor, String
 
-        # @!attribute to
+        # @!method initialize(page_size:, time_range:, page_cursor: nil)
+        #   @param page_size [Integer]
         #
-        #   @return [Array<Telnyx::Models::EmailInboxes::EmailAddress>]
-        required :to, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::EmailInboxes::EmailAddress] }
-
-        # @!method initialize(cc:, from:, subject:, to:)
-        #   Summary of the associated email message. Present when the email_message preload
-        #   is available.
+        #   @param time_range [Telnyx::Models::TimeRange]
         #
-        #   @param cc [Array<Telnyx::Models::EmailInboxes::EmailAddress>]
-        #   @param from [Telnyx::Models::EmailInboxes::EmailAddress]
-        #   @param subject [String]
-        #   @param to [Array<Telnyx::Models::EmailInboxes::EmailAddress>]
+        #   @param page_cursor [String] Cursor for the next page, when more results are available.
       end
     end
   end

data/lib/telnyx/models/email_event_type.rb

@@ -2,6 +2,12 @@
 
 module Telnyx
   module Models
+    # Bare stored event names returned by message history. In addition to the normal
+    # send and delivery lifecycle, polling can expose suppression, scan, and
+    # quarantine lifecycle rows. Sharp canonical names gw_reject, injection_timeout,
+    # and expired distinguish gateway rejection, ambiguous injection timeout, and MTA
+    # expiration. The failed and bounced names remain valid for system/admin failures
+    # and hard bounces respectively. Existing stored rows retain their original names.
     module EmailEventType
       extend Telnyx::Internal::Type::Enum
 
@@ -16,11 +22,21 @@ module Telnyx
       DELIVERED = :delivered
       BOUNCED = :bounced
       COMPLAINED = :complained
+      SUPPRESSED = :suppressed
       REJECTED = :rejected
       OPENED = :opened
       CLICKED = :clicked
       UNSUBSCRIBED = :unsubscribed
       DAILY_LIMIT_EXCEEDED = :daily_limit_exceeded
+      SCAN_DEFERRED = :scan_deferred
+      QUARANTINED = :quarantined
+      QUARANTINE_RELEASED = :quarantine_released
+      QUARANTINE_RELEASE_DISPATCHED = :quarantine_release_dispatched
+      QUARANTINE_REJECTED = :quarantine_rejected
+      QUARANTINE_EXPIRED = :quarantine_expired
+      GW_REJECT = :gw_reject
+      INJECTION_TIMEOUT = :injection_timeout
+      EXPIRED = :expired
 
       # @!method self.values
       #   @return [Array<Symbol>]

data/lib/telnyx/models/email_inboxes/email_message.rb

@@ -32,14 +32,20 @@ module Telnyx
 
         # @!attribute events
         #
-        #   @return [Array<Telnyx::Models::MessageEvent>]
-        required :events, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::MessageEvent] }
+        #   @return [Array<Telnyx::Models::EmailInboxes::EmailMessage::Event>]
+        required :events, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::EmailInboxes::EmailMessage::Event] }
 
         # @!attribute from
         #
         #   @return [Telnyx::Models::EmailInboxes::EmailAddress]
         required :from, -> { Telnyx::EmailInboxes::EmailAddress }
 
+        # @!attribute metadata
+        #   Customer-supplied metadata stored with the message.
+        #
+        #   @return [Hash{Symbol=>Object}]
+        required :metadata, Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown]
+
         # @!attribute record_type
         #
         #   @return [Symbol, Telnyx::Models::EmailInboxes::EmailMessage::RecordType]
@@ -63,6 +69,12 @@ module Telnyx
         #   @return [String]
         required :subject, String
 
+        # @!attribute tags
+        #   Customer-supplied tags stored with the message.
+        #
+        #   @return [Array<String>]
+        required :tags, Telnyx::Internal::Type::ArrayOf[String]
+
         # @!attribute template_id
         #
         #   @return [String, nil]
@@ -115,7 +127,7 @@ module Telnyx
         #   @return [Array<Telnyx::Models::SuppressedRecipient>, nil]
         optional :suppressed, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::SuppressedRecipient] }
 
-        # @!method initialize(id:, attachments:, bcc:, cc:, created_at:, events:, from:, record_type:, reply_to:, status:, subject:, template_id:, template_variables:, to:, inline_css: nil, recipient_statuses: nil, sandbox: nil, scheduled_at: nil, suppressed: nil)
+        # @!method initialize(id:, attachments:, bcc:, cc:, created_at:, events:, from:, metadata:, record_type:, reply_to:, status:, subject:, tags:, template_id:, template_variables:, to:, inline_css: nil, recipient_statuses: nil, sandbox: nil, scheduled_at: nil, suppressed: nil)
         #   Some parameter documentations has been truncated, see
         #   {Telnyx::Models::EmailInboxes::EmailMessage} for more details.
         #
@@ -129,10 +141,12 @@ module Telnyx
         #
         #   @param created_at [Time]
         #
-        #   @param events [Array<Telnyx::Models::MessageEvent>]
+        #   @param events [Array<Telnyx::Models::EmailInboxes::EmailMessage::Event>]
         #
         #   @param from [Telnyx::Models::EmailInboxes::EmailAddress]
         #
+        #   @param metadata [Hash{Symbol=>Object}] Customer-supplied metadata stored with the message.
+        #
         #   @param record_type [Symbol, Telnyx::Models::EmailInboxes::EmailMessage::RecordType]
         #
         #   @param reply_to [String, nil]
@@ -141,6 +155,8 @@ module Telnyx
         #
         #   @param subject [String]
         #
+        #   @param tags [Array<String>] Customer-supplied tags stored with the message.
+        #
         #   @param template_id [String, nil]
         #
         #   @param template_variables [Hash{Symbol=>Object}]
@@ -220,6 +236,42 @@ module Telnyx
           #   @param url [String, nil] Telnyx-hosted public URL for the attachment content.
         end
 
+        class Event < Telnyx::Internal::Type::BaseModel
+          # @!attribute occurred_at
+          #
+          #   @return [Time]
+          required :occurred_at, Time
+
+          # @!attribute type
+          #   Bare stored event names returned by message history. In addition to the normal
+          #   send and delivery lifecycle, polling can expose suppression, scan, and
+          #   quarantine lifecycle rows. Sharp canonical names gw_reject, injection_timeout,
+          #   and expired distinguish gateway rejection, ambiguous injection timeout, and MTA
+          #   expiration. The failed and bounced names remain valid for system/admin failures
+          #   and hard bounces respectively. Existing stored rows retain their original names.
+          #
+          #   @return [Symbol, Telnyx::Models::EmailEventType]
+          required :type, enum: -> { Telnyx::EmailEventType }
+
+          # @!attribute payload
+          #
+          #   @return [Hash{Symbol=>Object}, nil]
+          optional :payload, Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown]
+
+          # @!method initialize(occurred_at:, type:, payload: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Telnyx::Models::EmailInboxes::EmailMessage::Event} for more details.
+          #
+          #   An event embedded in a message response. The dedicated per-message events
+          #   endpoint additionally returns event_type and canonical_event_type.
+          #
+          #   @param occurred_at [Time]
+          #
+          #   @param type [Symbol, Telnyx::Models::EmailEventType] Bare stored event names returned by message history. In addition to the normal s
+          #
+          #   @param payload [Hash{Symbol=>Object}]
+        end
+
         # @see Telnyx::Models::EmailInboxes::EmailMessage#record_type
         module RecordType
           extend Telnyx::Internal::Type::Enum

data/lib/telnyx/models/email_message_batch_params.rb

@@ -16,8 +16,13 @@ module Telnyx
       required :messages, -> { Telnyx::Internal::Type::ArrayOf[Telnyx::EmailMessageBatchParams::Message] }
 
       # @!attribute sandbox_mode
-      #   Applies sandbox mode to all messages in the batch. Overrides any per-message
-      #   sandbox_mode in the messages array.
+      #   Applies sandbox mode to all messages in the batch and overrides any per-message
+      #   `sandbox_mode` value — each message's effective `sandbox_mode` is exactly this
+      #   envelope value. Reserved recipients at `test.telnyx.com` produce the
+      #   deterministic event chains documented on CreateEmailRequest.sandbox_mode; no
+      #   batch item is injected into the MTA or outbound Kafka path. Sandbox batch items
+      #   are non-billable, consume no daily-send-limit quota, and feed no
+      #   delivery-reputation signals.
       #
       #   @return [Boolean, nil]
       optional :sandbox_mode, Telnyx::Internal::Type::Boolean
@@ -33,7 +38,7 @@ module Telnyx
       #
       #   @param messages [Array<Telnyx::Models::EmailMessageBatchParams::Message>] Array of email messages to send. Up to 1,000 messages per batch request. Each me
       #
-      #   @param sandbox_mode [Boolean] Applies sandbox mode to all messages in the batch. Overrides any per-message san
+      #   @param sandbox_mode [Boolean] Applies sandbox mode to all messages in the batch and overrides any per-message
       #
       #   @param idempotency_key [String]
       #
@@ -105,7 +110,9 @@ module Telnyx
         optional :inline_css, Telnyx::Internal::Type::Boolean
 
         # @!attribute metadata
-        #   Custom metadata. Write-only; not returned in responses.
+        #   Custom metadata key/value pairs. Stored on the message, returned on message
+        #   responses, and propagated to Email Detail Records. Usable in `filter[metadata]`
+        #   when listing messages.
         #
         #   @return [Hash{Symbol=>Object}, nil]
         optional :metadata, Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown]
@@ -118,15 +125,21 @@ module Telnyx
         optional :reply_to, union: -> { Telnyx::EmailAddressInput }
 
         # @!attribute sandbox_mode
+        #   Per-message sandbox flag. The batch-level `sandbox_mode` envelope value is
+        #   authoritative: it overwrites every message's `sandbox_mode` before processing,
+        #   including the `false` default when the envelope omits the field. A per-item
+        #   `sandbox_mode: true` inside a non-sandbox batch is therefore a real send. Set
+        #   the envelope field to run any batch item in sandbox mode.
         #
         #   @return [Boolean, nil]
         optional :sandbox_mode, Telnyx::Internal::Type::Boolean
 
         # @!attribute scheduled_at
-        #   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.
+        #   Future ISO 8601 delivery time. Invalid or non-future timestamps are rejected.
+        #   Single sends return HTTP 422; in batch sends the invalid item is reported in the
+        #   207 per-item errors while other items continue. `send_at` remains a deprecated
+        #   request alias. A non-null `scheduled_at` takes precedence over `send_at`; when
+        #   `scheduled_at` is omitted or null, `send_at` is used.
         #
         #   @return [Time, nil]
         optional :scheduled_at, Time, nil?: true
@@ -148,8 +161,9 @@ module Telnyx
         optional :subject, String
 
         # @!attribute tags
-        #   Tags for categorization and reporting. Stored on the message and propagated to
-        #   Email Detail Records. Not returned in API responses.
+        #   Tags for categorization and filtering. Stored on the message, returned on
+        #   message responses, and propagated to Email Detail Records. Usable in
+        #   `filter[tags]` when listing messages.
         #
         #   @return [Array<String>, nil]
         optional :tags, Telnyx::Internal::Type::ArrayOf[String]
@@ -162,7 +176,10 @@ module Telnyx
         # @!attribute template_variables
         #   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.
+        #   object for template rendering. When the template enables `strict_variables`, a
+        #   missing required variable fails the request with 422 (single send) or a per-item
+        #   `unprocessable_entity` error (batch) naming the variable; no message is
+        #   persisted for the failed item.
         #
         #   @return [Hash{Symbol=>Object}, nil]
         optional :template_variables, Telnyx::Internal::Type::HashOf[Telnyx::Internal::Type::Unknown]
@@ -215,19 +232,19 @@ module Telnyx
         #
         #   @param inline_css [Boolean]
         #
-        #   @param metadata [Hash{Symbol=>Object}] Custom metadata. Write-only; not returned in responses.
+        #   @param metadata [Hash{Symbol=>Object}] Custom metadata key/value pairs. Stored on the message, returned on message resp
         #
         #   @param reply_to [String, Telnyx::Models::EmailInboxes::EmailAddress] Reply-to address. If provided as an object with a name, only the email is stored
         #
-        #   @param sandbox_mode [Boolean]
+        #   @param sandbox_mode [Boolean] Per-message sandbox flag. The batch-level `sandbox_mode` envelope value is autho
         #
-        #   @param scheduled_at [Time, nil] Future ISO 8601 time to schedule sending. Invalid or past timestamps
+        #   @param scheduled_at [Time, nil] Future ISO 8601 delivery time. Invalid or non-future timestamps are rejected. Si
         #
         #   @param send_at [Time] Deprecated alias for `scheduled_at`.
         #
         #   @param subject [String] Required unless `template_id` is supplied. When using a template, the template's
         #
-        #   @param tags [Array<String>] Tags for categorization and reporting. Stored on the message and propagated to E
+        #   @param tags [Array<String>] Tags for categorization and filtering. Stored on the message, returned on messag
         #
         #   @param template_id [String]
         #