mailtrap 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b63e81a019d2e0e7e4361de7ca3c511ffc3d0c292dc8db17c1866e986f57f18
-  data.tar.gz: 1b1efad54b339d0271d8c36970c1c668a345e31611a22cb3782ebc6556bd6543
+  metadata.gz: 40fcde70d63616c345252736a68e3de8b1f0cfa7c1cf615cb0cace7e2158c752
+  data.tar.gz: 5e3ab5dd73034c6fc752f0d13b683e767d6f29f170c1f2aeed5fbffedc9bef1c
 SHA512:
-  metadata.gz: 8e03088d16735f15494b4eee20f6c58dd5a9ec0fb031836326b086687f5cc415d1c841744f27f6ca46c9203952d6abd989ed2f75c4b550fac53b58b62d314838
-  data.tar.gz: 63fc1ce090a0ee019693ed36794f5319f7b94caa29302ca9a2f7920b7db92dc611aeed74bd9ba0de4853e5626d108a520c11e0e1eb51dcf83418e1ff3b1105f7
+  metadata.gz: b971a8cc52133ce0aed38ed202742fdb45e4be73256abe284e40a1d4ac94b729674cd4faea526397685f26d80fcd307669777941b29b1a28fcbd821adbf6beba
+  data.tar.gz: 00bc7f6c7db02b4d70f45070e250ad726b72150eb976dcf4476f72b58a44ad99d1f59a6ac89033cc5269d2a5f13987a10a8d1cd4d8d6dc0ed4d894e1134baade

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [2.12.0] - 2026-07-24
+
+## What's Changed
+* MT-22678: Add name search filter to contact lists listing by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/116
+* Add Inbound Email v2 API support by @mklocek in https://github.com/mailtrap/mailtrap-ruby/pull/117
+
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.11.1...v2.12.0
+
+## [2.11.1] - 2026-07-02
+
+## What's Changed
+* Release v2.11.0 by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/109
+* MT-22022: Add webhook signature verification helper by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/110
+* Add draft-release workflow placeholder by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/111
+* Implement draft-release workflow by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/112
+
+## New Contributors
+* @Rabsztok made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/110
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.11.0...v2.11.1
+
 ## [2.11.0] - 2026-05-14
 ## What's Changed
 * Update sandboxes api by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/103

data/Gemfile.lock

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

data/README.md

@@ -8,7 +8,6 @@
 
 This client uses API v2, for v1 refer to [this documentation](https://mailtrap.docs.apiary.io/)
 
-
 ## Prerequisites
 
 To get the most out of this official Mailtrap.io Ruby SDK:
@@ -176,7 +175,7 @@ Email API:
 
 - Full Email Sending – [`full.rb`](examples/full.rb)
 - Batch Sending – [`batch.rb`](examples/batch.rb)
-- Sending Domains API  – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
+- Sending Domains API – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
 - Sending Stats API – [`stats_api.rb`](examples/stats_api.rb)
 - Email Logs API – [`email_logs_api.rb`](examples/email_logs_api.rb)
 - Webhooks API – [`webhooks_api.rb`](examples/webhooks_api.rb)
@@ -188,6 +187,13 @@ Email Sandbox (Testing):
 - Sandbox Messages CRUD - [`sandbox_messages_api.rb`](examples/sandbox_messages_api.rb)
 - Sandbox Attachments API - [`sandbox_attachments_api.rb`](examples/sandbox_attachments_api.rb)
 
+Inbound Email:
+
+- Inbound Folders API – [`inbound_folders_api.rb`](examples/inbound_folders_api.rb)
+- 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)
+
 Contact management:
 
 - Contacts CRUD & Listing – [`contacts_api.rb`](examples/contacts_api.rb)
@@ -199,6 +205,7 @@ General:
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
 - 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)
 
 ## Migration guide v1 → v2
 
@@ -213,14 +220,14 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/railswa
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive 
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 To release a new version, update the version number in `version.rb`, and then
 run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and the created tag, and push the `.gem` file to 
+push git commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
 To run the documentation server, first generate the documentation with
@@ -241,4 +248,4 @@ Everyone interacting in the Mailtrap project's codebases, issue trackers, chat r
 
 ## Compatibility with previous releases
 
-Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package. 
+Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package.

data/lib/mailtrap/contact_lists_api.rb

@@ -49,10 +49,14 @@ module Mailtrap
     end
 
     # Lists all contact lists for the account
+    # @param search [String] Filters contact lists by name (case-insensitive prefix match)
     # @return [Array<ContactList>] Array of contact list objects
     # @!macro api_errors
-    def list
-      base_list
+    def list(search: nil)
+      query_params = {}
+      query_params[:search] = search unless search.nil?
+
+      base_list(query_params)
     end
 
     private

data/lib/mailtrap/email_log_message.rb

@@ -6,6 +6,10 @@ module Mailtrap
   # @attr_reader message_id [String] Message UUID
   # @attr_reader status [String] delivered, not_delivered, enqueued, opted_out
   # @attr_reader subject [String, nil] Email subject
+  # @attr_reader rfc_message_id [String, nil] Value of the RFC 5322 Message-ID header
+  # @attr_reader in_reply_to [String, nil] Value of the RFC 5322 In-Reply-To header
+  # @attr_reader references [Array<String>] Values of the RFC 5322 References header
+  # @attr_reader thread_id [String, nil] ID of the inbound thread this message belongs to, if any
   # @attr_reader from [String] Sender address
   # @attr_reader to [String] Recipient address
   # @attr_reader sent_at [String] ISO 8601 timestamp
@@ -24,6 +28,10 @@ module Mailtrap
     :message_id,
     :status,
     :subject,
+    :rfc_message_id,
+    :in_reply_to,
+    :references,
+    :thread_id,
     :from,
     :to,
     :sent_at,

data/lib/mailtrap/inbound_attachment.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound message attachment
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader attachment_id [String] The attachment ID
+  # @attr_reader size [Integer, nil] The attachment size in bytes
+  # @attr_reader filename [String, nil] The attachment filename
+  # @attr_reader content_type [String, nil] The attachment MIME type
+  # @attr_reader content_disposition [String, nil] attachment or inline
+  # @attr_reader content_id [String, nil] The content ID for inline attachments
+  # @attr_reader download_url [String, nil] Signed URL to download the attachment (only when fetched by ID)
+  # @attr_reader download_url_expires_at [String, nil] When the download URL expires (only when fetched by ID)
+  # rubocop:disable Lint/StructNewOverride -- +size+ is an API field that shadows Struct#size
+  InboundAttachment = Struct.new(
+    :attachment_id,
+    :size,
+    :filename,
+    :content_type,
+    :content_disposition,
+    :content_id,
+    :download_url,
+    :download_url_expires_at,
+    keyword_init: true
+  )
+  # rubocop:enable Lint/StructNewOverride
+end

data/lib/mailtrap/inbound_folder.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound folder
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader id [Integer] The folder ID
+  # @attr_reader name [String] The folder name
+  InboundFolder = Struct.new(
+    :id,
+    :name,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_folders_api.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbound_folder'
+
+module Mailtrap
+  class InboundFoldersAPI
+    include BaseAPI
+
+    self.supported_options = %i[name]
+    self.response_class = InboundFolder
+
+    # Inbound is scoped to the token's account, so no account_id is required.
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # Lists all inbound folders in the account
+    # @return [Array<InboundFolder>] Array of folders
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Retrieves a specific inbound folder
+    # @param folder_id [Integer] The folder ID
+    # @return [InboundFolder] Folder object
+    # @!macro api_errors
+    def get(folder_id)
+      base_get(folder_id)
+    end
+
+    # Creates a new inbound folder
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The folder name
+    # @return [InboundFolder] Created folder
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an inbound folder
+    # @param folder_id [Integer] The folder ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The folder name
+    # @return [InboundFolder] Updated folder
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(folder_id, options)
+      base_update(folder_id, options)
+    end
+
+    # Deletes an inbound folder along with all of its inboxes
+    # @param folder_id [Integer] The folder ID
+    # @return nil
+    # @!macro api_errors
+    def delete(folder_id)
+      base_delete(folder_id)
+    end
+
+    private
+
+    def base_path
+      '/api/inbound/folders'
+    end
+  end
+end

data/lib/mailtrap/inbound_inbox.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound inbox
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader id [Integer] The inbox ID
+  # @attr_reader name [String] The inbox name
+  # @attr_reader address [String] The inbox's inbound address
+  # @attr_reader domain_id [Integer] The sending domain the inbox is attached to
+  InboundInbox = Struct.new(
+    :id,
+    :name,
+    :address,
+    :domain_id,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_inboxes_api.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbound_inbox'
+
+module Mailtrap
+  class InboundInboxesAPI
+    include BaseAPI
+
+    self.response_class = InboundInbox
+
+    CREATE_OPTIONS = %i[name domain_id].freeze
+    UPDATE_OPTIONS = %i[name].freeze
+
+    # Inbound is scoped to the token's account, so no account_id is required.
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # Lists all inboxes in a folder
+    # @param folder_id [Integer] The folder ID
+    # @return [Array<InboundInbox>] Array of inboxes
+    # @!macro api_errors
+    def list(folder_id)
+      client.get(inboxes_path(folder_id)).map { |item| handle_response(item) }
+    end
+
+    # Retrieves a specific inbox
+    # @param folder_id [Integer] The folder ID
+    # @param inbox_id [Integer] The inbox ID
+    # @return [InboundInbox] Inbox object
+    # @!macro api_errors
+    def get(folder_id, inbox_id)
+      handle_response(client.get("#{inboxes_path(folder_id)}/#{inbox_id}"))
+    end
+
+    # Creates a new inbox in a folder
+    # @param folder_id [Integer] The folder ID
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The inbox name
+    # @option options [Integer] :domain_id Attach to a custom domain; omit for a Mailtrap-hosted inbox
+    # @return [InboundInbox] Created inbox
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(folder_id, options)
+      validate_options!(options, CREATE_OPTIONS)
+      handle_response(client.post(inboxes_path(folder_id), options))
+    end
+
+    # Updates an inbox
+    # @param folder_id [Integer] The folder ID
+    # @param inbox_id [Integer] The inbox ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The inbox name
+    # @return [InboundInbox] Updated inbox
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(folder_id, inbox_id, options)
+      validate_options!(options, UPDATE_OPTIONS)
+      handle_response(client.patch("#{inboxes_path(folder_id)}/#{inbox_id}", options))
+    end
+
+    # Deletes an inbox
+    # @param folder_id [Integer] The folder ID
+    # @param inbox_id [Integer] The inbox ID
+    # @return nil
+    # @!macro api_errors
+    def delete(folder_id, inbox_id)
+      client.delete("#{inboxes_path(folder_id)}/#{inbox_id}")
+    end
+
+    private
+
+    def inboxes_path(folder_id)
+      "/api/inbound/folders/#{folder_id}/inboxes"
+    end
+  end
+end

data/lib/mailtrap/inbound_message.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound message (summary in list, full details when fetched by ID)
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader id [String] The Mailtrap object ID (not the RFC Message-ID header)
+  # @attr_reader inbox_id [Integer] The inbox the message was received in
+  # @attr_reader from [String, nil] Sender address
+  # @attr_reader to [Array<String>] Recipient addresses
+  # @attr_reader cc [Array<String>] Cc addresses
+  # @attr_reader bcc [Array<String>] Bcc addresses
+  # @attr_reader reply_to [String, nil] Reply-To address
+  # @attr_reader subject [String, nil] Email subject
+  # @attr_reader rfc_message_id [String, nil] Value of the RFC 5322 Message-ID header
+  # @attr_reader in_reply_to [String, nil] Value of the RFC 5322 In-Reply-To header
+  # @attr_reader references [Array<String>] Values of the RFC 5322 References header
+  # @attr_reader headers [Hash, nil] Raw message headers
+  # @attr_reader size [Integer, nil] Total message size in bytes
+  # @attr_reader html_size [Integer, nil] HTML body size in bytes
+  # @attr_reader text_size [Integer, nil] Text body size in bytes
+  # @attr_reader received_at [String] ISO 8601 timestamp when the message was received
+  # @attr_reader thread_id [String, nil] ID of the thread this message belongs to, if any
+  # @attr_reader attachments [Array<InboundAttachment>] The message attachments
+  # @attr_reader raw_message_url [String, nil] Signed URL to download raw .eml (only when fetched by ID)
+  # @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)
+  # rubocop:disable Lint/StructNewOverride -- +size+ is an API field that shadows Struct#size
+  InboundMessage = Struct.new(
+    :id,
+    :inbox_id,
+    :from,
+    :to,
+    :cc,
+    :bcc,
+    :reply_to,
+    :subject,
+    :rfc_message_id,
+    :in_reply_to,
+    :references,
+    :headers,
+    :size,
+    :html_size,
+    :text_size,
+    :received_at,
+    :thread_id,
+    :attachments,
+    :raw_message_url,
+    :raw_message_expires_at,
+    :html_body,
+    :text_body,
+    keyword_init: true
+  )
+  # rubocop:enable Lint/StructNewOverride
+end

data/lib/mailtrap/inbound_messages_api.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbound_message'
+require_relative 'inbound_attachment'
+require_relative 'inbound_messages_list_response'
+require_relative 'inbound_send_result'
+
+module Mailtrap
+  class InboundMessagesAPI
+    include BaseAPI
+
+    self.response_class = InboundMessage
+
+    SEND_OPTIONS = %i[from to cc bcc reply_to text html category attachments headers custom_variables].freeze
+
+    # Inbound is scoped to the token's account, so no account_id is required.
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # Lists messages 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
+    # @return [InboundMessagesListResponse] data, total_count, and last_id
+    # @!macro api_errors
+    def list(inbox_id, last_id: nil)
+      query_params = last_id ? { last_id: } : {}
+      response = client.get(messages_path(inbox_id), query_params)
+
+      InboundMessagesListResponse.new(
+        data: Array(response[:data]).map { |item| build_message(item) },
+        total_count: response[:total_count],
+        last_id: response[:last_id]
+      )
+    end
+
+    # Fetches a single message with its full body and attachment download URLs
+    # @param inbox_id [Integer] The inbox ID
+    # @param message_id [String] The message ID
+    # @return [InboundMessage] Message details
+    # @!macro api_errors
+    def get(inbox_id, message_id)
+      build_message(client.get("#{messages_path(inbox_id)}/#{message_id}"))
+    end
+
+    # Deletes a message
+    # @param inbox_id [Integer] The inbox ID
+    # @param message_id [String] The message ID
+    # @return nil
+    # @!macro api_errors
+    def delete(inbox_id, message_id)
+      client.delete("#{messages_path(inbox_id)}/#{message_id}")
+    end
+
+    # Replies to a message (sends to the original sender)
+    # @param inbox_id [Integer] The inbox ID
+    # @param message_id [String] The message ID
+    # @param [Hash] options The send parameters (see {SEND_OPTIONS})
+    # @return [InboundSendResult] The sent message IDs
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def reply(inbox_id, message_id, options)
+      send_action(inbox_id, message_id, 'reply', options)
+    end
+
+    # Replies to a message and copies the original's other recipients
+    # @param (see #reply)
+    # @return [InboundSendResult] The sent message IDs
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def reply_all(inbox_id, message_id, options)
+      send_action(inbox_id, message_id, 'reply_all', options)
+    end
+
+    # Forwards a message to new recipients
+    # @param (see #reply)
+    # @return [InboundSendResult] The sent message IDs
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided, or if no +to+ recipient is given
+    def forward(inbox_id, message_id, options)
+      raise ArgumentError, 'to is required for forward' if Array(options[:to]).empty?
+
+      send_action(inbox_id, message_id, 'forward', options)
+    end
+
+    private
+
+    def messages_path(inbox_id)
+      "/api/inbound/inboxes/#{inbox_id}/messages"
+    end
+
+    def send_action(inbox_id, message_id, action, options)
+      validate_options!(options, SEND_OPTIONS)
+      response = client.post("#{messages_path(inbox_id)}/#{message_id}/#{action}", options)
+
+      InboundSendResult.new(message_ids: response[:message_ids])
+    end
+
+    def build_message(hash)
+      attrs = hash.slice(*InboundMessage.members)
+      attrs[:attachments] = build_attachments(attrs[:attachments]) if attrs[:attachments]
+
+      InboundMessage.new(**attrs)
+    end
+
+    def build_attachments(attachments)
+      Array(attachments).map do |attachment|
+        InboundAttachment.new(**attachment.slice(*InboundAttachment.members))
+      end
+    end
+  end
+end

data/lib/mailtrap/inbound_messages_list_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for a paginated list of inbound messages
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader data [Array<InboundMessage>] The messages on this page
+  # @attr_reader total_count [Integer] Total number of messages in the inbox
+  # @attr_reader last_id [String, nil] Cursor for the next page, or nil if this is the last page
+  InboundMessagesListResponse = Struct.new(
+    :data,
+    :total_count,
+    :last_id,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_send_result.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for the result of a reply, reply-all, or forward.
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader message_ids [Array<String>] UUIDs of the sent messages, one per recipient
+  InboundSendResult = Struct.new(
+    :message_ids,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_thread.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for an inbound thread (summary in list, with embedded messages when fetched by ID)
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader id [String] The thread ID
+  # @attr_reader subject [String, nil] The thread subject
+  # @attr_reader message_count [Integer] Number of messages in the thread
+  # @attr_reader size [Integer] Total size of the thread in bytes
+  # @attr_reader first_message_at [String] ISO 8601 timestamp of the first message
+  # @attr_reader last_received_at [String, nil] ISO 8601 timestamp of the last received message
+  # @attr_reader last_sent_at [String, nil] ISO 8601 timestamp of the last sent message
+  # @attr_reader last_activity_at [String] ISO 8601 timestamp of the last activity
+  # @attr_reader last_message_id [String, nil] ID of the most recent message
+  # @attr_reader senders [Array<String>] Distinct sender addresses in the thread
+  # @attr_reader recipients [Array<String>] Distinct recipient addresses in the thread
+  # @attr_reader attachments [Array<InboundAttachment>] Attachments across the thread
+  # @attr_reader messages [Array<InboundThreadMessage>, nil] The thread's messages (only when fetched by ID)
+  # rubocop:disable Lint/StructNewOverride -- +size+ is an API field that shadows Struct#size
+  InboundThread = Struct.new(
+    :id,
+    :subject,
+    :message_count,
+    :size,
+    :first_message_at,
+    :last_received_at,
+    :last_sent_at,
+    :last_activity_at,
+    :last_message_id,
+    :senders,
+    :recipients,
+    :attachments,
+    :messages,
+    keyword_init: true
+  )
+  # rubocop:enable Lint/StructNewOverride
+end

data/lib/mailtrap/inbound_thread_message.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+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.
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader visibility_status [String] available or placeholder
+  # @attr_reader direction [String] inbound or outbound
+  # @attr_reader id [String, nil] The message ID
+  # @attr_reader message_group_id [String, nil] Groups messages sent together as one logical send
+  # @attr_reader subject [String, nil] Email subject
+  # @attr_reader rfc_message_id [String, nil] Value of the RFC 5322 Message-ID header
+  # @attr_reader in_reply_to [String, nil] Value of the RFC 5322 In-Reply-To header
+  # @attr_reader references [Array<String>, nil] Values of the RFC 5322 References header
+  # @attr_reader from [String, nil] Sender address
+  # @attr_reader to [Array<String>, nil] Recipient addresses
+  # @attr_reader cc [Array<String>, nil] Cc addresses
+  # @attr_reader bcc [Array<String>, nil] Bcc addresses
+  # @attr_reader reply_to [String, nil] Reply-To address
+  # @attr_reader created_at [String, nil] ISO 8601 timestamp
+  # @attr_reader email_size [Integer, nil] Message size in bytes
+  # @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)
+  InboundThreadMessage = Struct.new(
+    :visibility_status,
+    :direction,
+    :id,
+    :message_group_id,
+    :subject,
+    :rfc_message_id,
+    :in_reply_to,
+    :references,
+    :from,
+    :to,
+    :cc,
+    :bcc,
+    :reply_to,
+    :created_at,
+    :email_size,
+    :text_body,
+    :html_body,
+    :attachments,
+    :delivery_status,
+    :delivered_at,
+    :bounced_at,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inbound_threads_api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbound_thread'
+require_relative 'inbound_thread_message'
+require_relative 'inbound_attachment'
+require_relative 'inbound_threads_list_response'
+
+module Mailtrap
+  class InboundThreadsAPI
+    include BaseAPI
+
+    self.response_class = InboundThread
+
+    # Inbound is scoped to the token's account, so no account_id is required.
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # 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
+    # @return [InboundThreadsListResponse] data, total_count, and last_id
+    # @!macro api_errors
+    def list(inbox_id, last_id: nil)
+      query_params = last_id ? { last_id: } : {}
+      response = client.get(threads_path(inbox_id), query_params)
+
+      InboundThreadsListResponse.new(
+        data: Array(response[:data]).map { |item| build_thread(item) },
+        total_count: response[:total_count],
+        last_id: response[:last_id]
+      )
+    end
+
+    # Fetches a single thread with its messages embedded (oldest first)
+    # @param inbox_id [Integer] The inbox ID
+    # @param thread_id [String] The thread ID
+    # @return [InboundThread] Thread with messages
+    # @!macro api_errors
+    def get(inbox_id, thread_id)
+      build_thread(client.get("#{threads_path(inbox_id)}/#{thread_id}"))
+    end
+
+    # Deletes a thread
+    # @param inbox_id [Integer] The inbox ID
+    # @param thread_id [String] The thread ID
+    # @return nil
+    # @!macro api_errors
+    def delete(inbox_id, thread_id)
+      client.delete("#{threads_path(inbox_id)}/#{thread_id}")
+    end
+
+    private
+
+    def threads_path(inbox_id)
+      "/api/inbound/inboxes/#{inbox_id}/threads"
+    end
+
+    def build_thread(hash)
+      attrs = hash.slice(*InboundThread.members)
+      attrs[:attachments] = build_attachments(attrs[:attachments]) if attrs[:attachments]
+      attrs[:messages] = build_messages(attrs[:messages]) if attrs[:messages]
+
+      InboundThread.new(**attrs)
+    end
+
+    def build_messages(messages)
+      Array(messages).map do |message|
+        attrs = message.slice(*InboundThreadMessage.members)
+        attrs[:attachments] = build_attachments(attrs[:attachments]) if attrs[:attachments]
+
+        InboundThreadMessage.new(**attrs)
+      end
+    end
+
+    def build_attachments(attachments)
+      Array(attachments).map do |attachment|
+        InboundAttachment.new(**attachment.slice(*InboundAttachment.members))
+      end
+    end
+  end
+end

data/lib/mailtrap/inbound_threads_list_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for a paginated list of inbound threads
+  # @see https://docs.mailtrap.io/developers/inbound
+  # @attr_reader data [Array<InboundThread>] The threads on this page
+  # @attr_reader total_count [Integer] Total number of threads in the inbox
+  # @attr_reader last_id [String, nil] Cursor for the next page, or nil if this is the last page
+  InboundThreadsListResponse = Struct.new(
+    :data,
+    :total_count,
+    :last_id,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/sending_domain.rb

@@ -17,6 +17,8 @@ module Mailtrap
   # @attr_reader health_alerts_enabled [Boolean] Whether health alerts are enabled
   # @attr_reader critical_alerts_enabled [Boolean] Whether critical alerts are enabled
   # @attr_reader alert_recipient_email [String, nil] The email address for alert recipients
+  # @attr_reader inbound_enabled [Boolean] Whether inbound email is enabled for this domain
+  # @attr_reader inbound_verified [Boolean] Whether the domain's inbound MX records are verified
   # @attr_reader permissions [Hash] The permissions for the sending domain
   #
   SendingDomain = Struct.new(
@@ -34,6 +36,8 @@ module Mailtrap
     :health_alerts_enabled,
     :critical_alerts_enabled,
     :alert_recipient_email,
+    :inbound_enabled,
+    :inbound_verified,
     :permissions,
     :created_at,
     :updated_at,

data/lib/mailtrap/version.rb

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

data/lib/mailtrap/webhooks.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Mailtrap
+  # Helpers for working with inbound Mailtrap webhooks.
+  #
+  # @see https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#verifying-the-signature
+  module Webhooks
+    # Hex-encoded HMAC-SHA256 signature length.
+    SIGNATURE_HEX_LENGTH = 64
+
+    # Verifies the HMAC-SHA256 signature of a Mailtrap webhook payload.
+    #
+    # Mailtrap signs every outbound webhook by computing
+    # `HMAC-SHA256(signing_secret, raw_request_body)` and sending the lowercase
+    # hex digest in the `Mailtrap-Signature` HTTP header. Compute the same
+    # digest on your side and compare it in constant time.
+    #
+    # The comparison is performed with {OpenSSL.fixed_length_secure_compare} to
+    # avoid timing side-channels.
+    #
+    # The method never raises on inputs that could plausibly arrive over the
+    # wire (empty strings, wrong-length signatures, non-hex characters, missing
+    # secret) — it simply returns `false`. This makes it safe to call directly
+    # from a controller without rescuing.
+    #
+    # @param payload [String] The raw request body, exactly as received.
+    #   **Do not** parse and re-serialize the JSON — re-encoding may reorder
+    #   keys or alter whitespace and invalidate the signature.
+    # @param signature [String] The value of the `Mailtrap-Signature` HTTP
+    #   header (lowercase hex string).
+    # @param signing_secret [String] The webhook's `signing_secret`, returned
+    #   by {WebhooksAPI#create} on webhook creation.
+    # @return [Boolean] `true` if the signature is valid for the given payload
+    #   and secret, `false` otherwise.
+    def self.verify_signature(payload:, signature:, signing_secret:)
+      return false unless [payload, signature, signing_secret].all? { |v| v.is_a?(String) && !v.empty? }
+      return false if signature.bytesize != SIGNATURE_HEX_LENGTH
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', signing_secret, payload)
+
+      OpenSSL.fixed_length_secure_compare(expected, signature)
+    rescue ArgumentError
+      # fixed_length_secure_compare raises ArgumentError on length mismatch
+      false
+    end
+  end
+end

data/lib/mailtrap.rb

@@ -27,6 +27,11 @@ require_relative 'mailtrap/sandbox_messages_api'
 require_relative 'mailtrap/sandbox_attachments_api'
 require_relative 'mailtrap/stats_api'
 require_relative 'mailtrap/webhooks_api'
+require_relative 'mailtrap/webhooks'
+require_relative 'mailtrap/inbound_folders_api'
+require_relative 'mailtrap/inbound_inboxes_api'
+require_relative 'mailtrap/inbound_messages_api'
+require_relative 'mailtrap/inbound_threads_api'
 
 module Mailtrap
   # @!macro api_errors

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.12.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -80,6 +80,19 @@ files:
 - lib/mailtrap/email_template.rb
 - lib/mailtrap/email_templates_api.rb
 - lib/mailtrap/errors.rb
+- lib/mailtrap/inbound_attachment.rb
+- lib/mailtrap/inbound_folder.rb
+- lib/mailtrap/inbound_folders_api.rb
+- lib/mailtrap/inbound_inbox.rb
+- lib/mailtrap/inbound_inboxes_api.rb
+- lib/mailtrap/inbound_message.rb
+- lib/mailtrap/inbound_messages_api.rb
+- lib/mailtrap/inbound_messages_list_response.rb
+- lib/mailtrap/inbound_send_result.rb
+- lib/mailtrap/inbound_thread.rb
+- lib/mailtrap/inbound_thread_message.rb
+- lib/mailtrap/inbound_threads_api.rb
+- lib/mailtrap/inbound_threads_list_response.rb
 - lib/mailtrap/inbox.rb
 - lib/mailtrap/inboxes_api.rb
 - lib/mailtrap/mail.rb
@@ -104,6 +117,7 @@ files:
 - lib/mailtrap/suppressions_api.rb
 - lib/mailtrap/version.rb
 - lib/mailtrap/webhook.rb
+- lib/mailtrap/webhooks.rb
 - lib/mailtrap/webhooks_api.rb
 - mailtrap.gemspec
 homepage: https://github.com/mailtrap/mailtrap-ruby
@@ -129,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Official mailtrap.io API client