mailtrap 2.16.0 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a727114a65c3b0d37de9dcc946d8e5d7d0c5c786b408844c4d399b9ae8caa32
-  data.tar.gz: 0ca0ebb87fe19a6d1a59268da9ba4b5f7cbe5c85224236764aa94dad103d6dc7
+  metadata.gz: df2746012d3720b47808a3bd7b8f44f473b49f53bf30b0b758d4467e0b8a578d
+  data.tar.gz: ba58958bb95d0344e5107c82b76a2a3a1586ea9bfe16211e07d39e167c119d82
 SHA512:
-  metadata.gz: b3b319869ad41f336475b58a86ef8d2b4c4e13979ae740690b5b4f95429b0094b0387ea7e1cde605085735e61bcc710af7c2424a7a7b44144c7db9fedb265ebd
-  data.tar.gz: 3d93fccceadcf06720feda85ff17ff2278df6f1a93f6b734e14e57f7a4d843b77cda69f88c350290f415474920a70c63056a6446265cba1e0d56c2601c7ffd02
+  metadata.gz: b3e163c56c0f08fc0be204e73a471fa451d5d8ae2eb87700f223c9e44a8a14161b88f916ac6d0d88b37b14c19807fd4d49424aa71b8075b4d7cbd8c87edbe487
+  data.tar.gz: f7cde5772e9b716761678f4d230b8f8e2d0ed6ba7b0f4afb5546377f36add5a991cc0f4e4e7cb2a44ee0f7c97419f56f732f31cb4f771ef698f154920007b3d5

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [2.18.0] - 2026-10-07
+
+## What's Changed
+* Add inbound forward rules, forward outcomes, thread delivery and search by @mklocek in https://github.com/mailtrap/mailtrap-ruby/pull/132
+
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.17.0...v2.18.0
+
+## [2.17.0] - 2026-10-07
+
+## What's Changed
+* Add TemplatesAPI for the paginated /api/templates endpoints by @izikaj in https://github.com/mailtrap/mailtrap-ruby/pull/133
+
+## New Contributors
+* @izikaj made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/133
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.16.0...v2.17.0
+
 ## [2.16.0] - 2026-08-31
 
 ## What's Changed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.16.0)
+    mailtrap (2.18.0)
       base64
 
 GEM

data/README.md

@@ -195,6 +195,7 @@ Inbound Email:
 - Inbound Inboxes API – [`inbound_inboxes_api.rb`](examples/inbound_inboxes_api.rb)
 - Inbound Messages API (list, get, delete, reply, reply_all, forward) – [`inbound_messages_api.rb`](examples/inbound_messages_api.rb)
 - Inbound Threads API – [`inbound_threads_api.rb`](examples/inbound_threads_api.rb)
+- Inbound Forward Rules API – [`inbound_forward_rules_api.rb`](examples/inbound_forward_rules_api.rb)
 
 Contact management:
 
@@ -211,7 +212,8 @@ General:
 - API Tokens API – [`api_tokens_api.rb`](examples/api_tokens_api.rb)
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
 - Permissions API – [`permissions_api.rb`](examples/permissions_api.rb)
-- Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
+- Templates API (experimental) – [`templates_api.rb`](examples/templates_api.rb)
+- Email Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 - Verifying webhook signatures – [`webhooks_signature_verification.ru`](examples/webhooks_signature_verification.ru)
 

data/lib/mailtrap/inbound_forward_outcome.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound forward outcome
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader rule_id [Integer] The forward rule ID
+  # @attr_reader rule_name [String, nil] The forward rule name
+  # @attr_reader destination [String] The destination address
+  # @attr_reader status [String] forwarded or rejected
+  # @attr_reader reason [String, nil] The rejection reason
+  # @attr_reader message_id [String, nil] The forwarded message ID
+  InboundForwardOutcome = Struct.new(
+    :rule_id,
+    :rule_name,
+    :destination,
+    :status,
+    :reason,
+    :message_id,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_forward_rule.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound forward rule
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader id [Integer] The forward rule ID
+  # @attr_reader name [String] The rule name
+  # @attr_reader created_at [String] Creation timestamp
+  # @attr_reader updated_at [String] Last update timestamp
+  # @attr_reader conditions [Array<InboundForwardRuleCondition>] The rule conditions
+  # @attr_reader destinations [Array<InboundForwardRuleDestination>] The rule destinations
+  InboundForwardRule = Struct.new(
+    :id,
+    :name,
+    :created_at,
+    :updated_at,
+    :conditions,
+    :destinations,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_forward_rule_condition.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound forward rule condition
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader match_type [String] The match type
+  # @attr_reader operator [String] The comparison operator
+  # @attr_reader value [String, nil] The value to compare against
+  # @attr_reader header_key [String, nil] The header name
+  InboundForwardRuleCondition = Struct.new(
+    :match_type,
+    :operator,
+    :value,
+    :header_key,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_forward_rule_destination.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound forward rule destination
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader email [String] The destination email address
+  InboundForwardRuleDestination = Struct.new(
+    :email,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_forward_rules_api.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbound_forward_rule'
+require_relative 'inbound_forward_rule_condition'
+require_relative 'inbound_forward_rule_destination'
+
+module Mailtrap
+  class InboundForwardRulesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name conditions destinations]
+    self.response_class = InboundForwardRule
+
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # Lists forward rules in an inbox
+    # @param inbox_id [Integer] The inbox ID
+    # @return [Array<InboundForwardRule>] Array of forward rules
+    # @!macro api_errors
+    def list(inbox_id)
+      response = client.get(forward_rules_path(inbox_id))
+      Array(response[:data]).map { |item| build_rule(item) }
+    end
+
+    # Retrieves a specific forward rule
+    # @param inbox_id [Integer] The inbox ID
+    # @param forward_rule_id [Integer] The forward rule ID
+    # @return [InboundForwardRule] Forward rule object
+    # @!macro api_errors
+    def get(inbox_id, forward_rule_id)
+      handle_response(client.get("#{forward_rules_path(inbox_id)}/#{forward_rule_id}"))
+    end
+
+    # Creates a new forward rule
+    # @param inbox_id [Integer] The inbox ID
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The rule name
+    # @option options [Array<Hash>] :conditions The rule conditions
+    # @option options [Array<Hash>] :destinations The rule destinations
+    # @return [InboundForwardRule] Created forward rule
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(inbox_id, options)
+      validate_options!(options, supported_options)
+      handle_response(client.post(forward_rules_path(inbox_id), options))
+    end
+
+    # Updates a forward rule
+    # @param inbox_id [Integer] The inbox ID
+    # @param forward_rule_id [Integer] The forward rule ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The rule name
+    # @option options [Array<Hash>] :conditions The rule conditions
+    # @option options [Array<Hash>] :destinations The rule destinations
+    # @return [InboundForwardRule] Updated forward rule
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(inbox_id, forward_rule_id, options)
+      validate_options!(options, supported_options)
+      handle_response(client.patch("#{forward_rules_path(inbox_id)}/#{forward_rule_id}", options))
+    end
+
+    # Deletes a forward rule
+    # @param inbox_id [Integer] The inbox ID
+    # @param forward_rule_id [Integer] The forward rule ID
+    # @return nil
+    # @!macro api_errors
+    def delete(inbox_id, forward_rule_id)
+      client.delete("#{forward_rules_path(inbox_id)}/#{forward_rule_id}")
+    end
+
+    private
+
+    def forward_rules_path(inbox_id)
+      "/api/inbound/inboxes/#{inbox_id}/forward_rules"
+    end
+
+    def handle_response(response)
+      build_rule(response[:data])
+    end
+
+    def build_rule(hash)
+      attrs = hash.slice(*InboundForwardRule.members)
+      attrs[:conditions] = build_conditions(attrs[:conditions]) if attrs[:conditions]
+      attrs[:destinations] = build_destinations(attrs[:destinations]) if attrs[:destinations]
+
+      InboundForwardRule.new(**attrs)
+    end
+
+    def build_conditions(conditions)
+      Array(conditions).map do |condition|
+        InboundForwardRuleCondition.new(**condition.slice(*InboundForwardRuleCondition.members))
+      end
+    end
+
+    def build_destinations(destinations)
+      Array(destinations).map do |destination|
+        InboundForwardRuleDestination.new(**destination.slice(*InboundForwardRuleDestination.members))
+      end
+    end
+  end
+end

data/lib/mailtrap/inbound_message.rb

@@ -25,6 +25,7 @@ module Mailtrap
   # @attr_reader raw_message_expires_at [String, nil] When the raw message URL expires (only when fetched by ID)
   # @attr_reader html_body [String, nil] Decoded HTML body (only when fetched by ID)
   # @attr_reader text_body [String, nil] Decoded text body (only when fetched by ID)
+  # @attr_reader forwards [Array<InboundForwardOutcome>] The forward outcomes
   # rubocop:disable Lint/StructNewOverride -- +size+ is an API field that shadows Struct#size
   InboundMessage = Struct.new(
     :id,
@@ -49,6 +50,7 @@ module Mailtrap
     :raw_message_expires_at,
     :html_body,
     :text_body,
+    :forwards,
     keyword_init: true
   )
   # rubocop:enable Lint/StructNewOverride

data/lib/mailtrap/inbound_messages_api.rb

@@ -3,6 +3,7 @@
 require_relative 'base_api'
 require_relative 'inbound_message'
 require_relative 'inbound_attachment'
+require_relative 'inbound_forward_outcome'
 require_relative 'inbound_messages_list_response'
 require_relative 'inbound_send_result'
 
@@ -100,6 +101,7 @@ module Mailtrap
     def build_message(hash)
       attrs = hash.slice(*InboundMessage.members)
       attrs[:attachments] = build_attachments(attrs[:attachments]) if attrs[:attachments]
+      attrs[:forwards] = build_forwards(attrs[:forwards]) if attrs[:forwards]
 
       InboundMessage.new(**attrs)
     end
@@ -109,5 +111,11 @@ module Mailtrap
         InboundAttachment.new(**attachment.slice(*InboundAttachment.members))
       end
     end
+
+    def build_forwards(forwards)
+      Array(forwards).map do |forward|
+        InboundForwardOutcome.new(**forward.slice(*InboundForwardOutcome.members))
+      end
+    end
   end
 end

data/lib/mailtrap/inbound_thread_message.rb

@@ -2,8 +2,7 @@
 
 module Mailtrap
   # Data Transfer Object for a message inside an inbound thread.
-  # Only +visibility_status+ and +direction+ are always present; +placeholder+ entries omit the rest,
-  # and the delivery lifecycle fields are only set on available outbound messages.
+  # Only +visibility_status+ and +direction+ are always present; +placeholder+ entries omit the rest.
   # @see https://docs.mailtrap.io/developers/inbound
   # @attr_reader visibility_status [String] available or placeholder
   # @attr_reader direction [String] inbound or outbound
@@ -23,9 +22,8 @@ module Mailtrap
   # @attr_reader text_body [String, nil] Decoded text body
   # @attr_reader html_body [String, nil] Decoded HTML body
   # @attr_reader attachments [Array<InboundAttachment>, nil] The message attachments
-  # @attr_reader delivery_status [String, nil] Delivery status (outbound messages only)
-  # @attr_reader delivered_at [String, nil] Delivery timestamp (outbound messages only)
-  # @attr_reader bounced_at [String, nil] Bounce timestamp (outbound messages only)
+  # @attr_reader delivery [InboundThreadMessageDelivery, nil] Delivery outcome (outbound messages only)
+  # @attr_reader forwards [Array<InboundForwardOutcome>, nil] Forward outcomes (inbound messages only)
   InboundThreadMessage = Struct.new(
     :visibility_status,
     :direction,
@@ -45,9 +43,8 @@ module Mailtrap
     :text_body,
     :html_body,
     :attachments,
-    :delivery_status,
-    :delivered_at,
-    :bounced_at,
+    :delivery,
+    :forwards,
     keyword_init: true
   )
 end

data/lib/mailtrap/inbound_thread_message_delivery.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for the delivery of an outbound message inside an inbound thread
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader to [String] The recipient address
+  # @attr_reader status [String] The delivery status
+  # @attr_reader delivered_at [String, nil] Delivery timestamp
+  # @attr_reader bounced_at [String, nil] Bounce timestamp
+  InboundThreadMessageDelivery = Struct.new(
+    :to,
+    :status,
+    :delivered_at,
+    :bounced_at,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_threads_api.rb

@@ -4,6 +4,8 @@ require_relative 'base_api'
 require_relative 'inbound_thread'
 require_relative 'inbound_thread_message'
 require_relative 'inbound_attachment'
+require_relative 'inbound_forward_outcome'
+require_relative 'inbound_thread_message_delivery'
 require_relative 'inbound_threads_list_response'
 
 module Mailtrap
@@ -20,10 +22,11 @@ module Mailtrap
     # Lists threads in an inbox (cursor-paginated)
     # @param inbox_id [Integer] The inbox ID
     # @param last_id [String, nil] Cursor from the previous response's +last_id+ for the next page
+    # @param search [String, nil] Search query
     # @return [InboundThreadsListResponse] data, total_count, and last_id
     # @!macro api_errors
-    def list(inbox_id, last_id: nil)
-      query_params = last_id ? { last_id: } : {}
+    def list(inbox_id, last_id: nil, search: nil)
+      query_params = { last_id:, search: }.compact
       response = client.get(threads_path(inbox_id), query_params)
 
       InboundThreadsListResponse.new(
@@ -69,6 +72,8 @@ module Mailtrap
       Array(messages).map do |message|
         attrs = message.slice(*InboundThreadMessage.members)
         attrs[:attachments] = build_attachments(attrs[:attachments]) if attrs[:attachments]
+        attrs[:delivery] = build_delivery(attrs[:delivery]) if attrs[:delivery]
+        attrs[:forwards] = build_forwards(attrs[:forwards]) if attrs[:forwards]
 
         InboundThreadMessage.new(**attrs)
       end
@@ -79,5 +84,15 @@ module Mailtrap
         InboundAttachment.new(**attachment.slice(*InboundAttachment.members))
       end
     end
+
+    def build_delivery(delivery)
+      InboundThreadMessageDelivery.new(**delivery.slice(*InboundThreadMessageDelivery.members))
+    end
+
+    def build_forwards(forwards)
+      Array(forwards).map do |forward|
+        InboundForwardOutcome.new(**forward.slice(*InboundForwardOutcome.members))
+      end
+    end
   end
 end

data/lib/mailtrap/template.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Template
+  # @attr_reader id [Integer] The template ID
+  # @attr_reader uuid [String] The template UUID
+  # @attr_reader name [String] The template name
+  # @attr_reader subject [String] The email subject
+  # @attr_reader category [String] The template category
+  # @attr_reader body_html [String] The HTML content
+  # @attr_reader body_text [String] The plain text content
+  # @attr_reader created_at [String] The creation timestamp
+  # @attr_reader updated_at [String] The last update timestamp
+  Template = Struct.new(
+    :id,
+    :uuid,
+    :name,
+    :subject,
+    :category,
+    :body_html,
+    :body_text,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  )
+
+  # Response from listing templates (paginated)
+  # @attr_reader data [Array<Template>] Page of templates
+  # @attr_reader pagination [Hash] Page-token pagination metadata
+  #   (+token+, +prev_token+, +next_token+, +first_url+, +prev_url+, +current_url+, +next_url+)
+  TemplatesListResponse = Struct.new(
+    :data,
+    :pagination,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/templates_api.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'template'
+
+module Mailtrap
+  # @note Experimental: the +/api/templates+ endpoints may change their request and response
+  #   shapes before general availability.
+  class TemplatesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name subject category body_html body_text]
+
+    self.response_class = Template
+
+    # Lists templates for the account, one page at a time. Unlike {EmailTemplatesAPI#list}, it does
+    # not return every template: pass +pagination[:next_token]+ with the same +per_page+ to get the
+    # next page.
+    # @param per_page [Integer, nil] Number of templates per page (max 100, default 50)
+    # @param token [Integer, nil] Page number to retrieve (page-token pagination, default 1)
+    # @return [TemplatesListResponse] The page of templates and pagination metadata
+    # @!macro api_errors
+    def list(per_page: nil, token: nil)
+      query_params = {}
+      query_params[:per_page] = per_page unless per_page.nil?
+      query_params[:token] = token unless token.nil?
+
+      response = client.get(base_path, query_params)
+
+      TemplatesListResponse.new(
+        data: Array(response[:data]).map { |item| build_entity(item, response_class) },
+        pagination: response[:pagination]
+      )
+    end
+
+    # Retrieves a specific template
+    # @param template_id [Integer] The template ID
+    # @return [Template] Template object
+    # @!macro api_errors
+    def get(template_id)
+      base_get(template_id)
+    end
+
+    # Creates a new template
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The template name (required)
+    # @option options [String] :subject The email subject (required)
+    # @option options [String] :category The template category (required)
+    # @option options [String, nil] :body_html The HTML content. Default: nil.
+    # @option options [String, nil] :body_text The plain text content. Default: nil.
+    # @return [Template] Created template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing template. Only the provided attributes are changed.
+    # @param template_id [Integer] The template ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The template name
+    # @option options [String] :subject The email subject
+    # @option options [String] :category The template category
+    # @option options [String, nil] :body_html The HTML content
+    # @option options [String, nil] :body_text The plain text content
+    # @return [Template] Updated template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(template_id, options)
+      base_update(template_id, options)
+    end
+
+    # Deletes a template
+    # @param template_id [Integer] The template ID
+    # @return [nil]
+    # @!macro api_errors
+    def delete(template_id)
+      base_delete(template_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/templates"
+    end
+
+    def handle_response(response)
+      build_entity(response[:data], response_class)
+    end
+  end
+end

data/lib/mailtrap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  VERSION = '2.16.0'
+  VERSION = '2.18.0'
 end

data/lib/mailtrap.rb

@@ -11,6 +11,7 @@ require_relative 'mailtrap/permissions_api'
 require_relative 'mailtrap/sub_accounts_api'
 require_relative 'mailtrap/billing_api'
 require_relative 'mailtrap/email_templates_api'
+require_relative 'mailtrap/templates_api'
 require_relative 'mailtrap/contacts_api'
 require_relative 'mailtrap/contact_lists_api'
 require_relative 'mailtrap/contact_fields_api'
@@ -34,6 +35,7 @@ require_relative 'mailtrap/inbound_folders_api'
 require_relative 'mailtrap/inbound_inboxes_api'
 require_relative 'mailtrap/inbound_messages_api'
 require_relative 'mailtrap/inbound_threads_api'
+require_relative 'mailtrap/inbound_forward_rules_api'
 
 module Mailtrap
   # @!macro api_errors

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.16.0
+  version: 2.18.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -85,6 +85,11 @@ files:
 - lib/mailtrap/inbound_attachment.rb
 - lib/mailtrap/inbound_folder.rb
 - lib/mailtrap/inbound_folders_api.rb
+- lib/mailtrap/inbound_forward_outcome.rb
+- lib/mailtrap/inbound_forward_rule.rb
+- lib/mailtrap/inbound_forward_rule_condition.rb
+- lib/mailtrap/inbound_forward_rule_destination.rb
+- lib/mailtrap/inbound_forward_rules_api.rb
 - lib/mailtrap/inbound_inbox.rb
 - lib/mailtrap/inbound_inboxes_api.rb
 - lib/mailtrap/inbound_message.rb
@@ -93,6 +98,7 @@ files:
 - lib/mailtrap/inbound_send_result.rb
 - lib/mailtrap/inbound_thread.rb
 - lib/mailtrap/inbound_thread_message.rb
+- lib/mailtrap/inbound_thread_message_delivery.rb
 - lib/mailtrap/inbound_threads_api.rb
 - lib/mailtrap/inbound_threads_list_response.rb
 - lib/mailtrap/inbox.rb
@@ -117,6 +123,8 @@ files:
 - lib/mailtrap/sub_accounts_api.rb
 - lib/mailtrap/suppression.rb
 - lib/mailtrap/suppressions_api.rb
+- lib/mailtrap/template.rb
+- lib/mailtrap/templates_api.rb
 - lib/mailtrap/tracking_opt_out.rb
 - lib/mailtrap/tracking_opt_outs_api.rb
 - lib/mailtrap/tracking_opt_outs_list_response.rb