mailtrap 2.11.1 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6606da8d73e2112b813b87000d3aaa63c5490cf2d046dedf59eb5a4f56fc619
-  data.tar.gz: a7647dad5291d79758edd52e2b01c57e3e475d998a271ddcd5f6daf24455f59c
+  metadata.gz: 40fcde70d63616c345252736a68e3de8b1f0cfa7c1cf615cb0cace7e2158c752
+  data.tar.gz: 5e3ab5dd73034c6fc752f0d13b683e767d6f29f170c1f2aeed5fbffedc9bef1c
 SHA512:
-  metadata.gz: e8bca46ba63dfa33175e89b2fcdaba9cce1701d904b6eee25a4808e57524b17dd7f97f483e6289c889fdb6006d35ced29c857beacdc1d2431f8c43a26d878161
-  data.tar.gz: 7dbeaaf7198cc263e2ab8264113b0992836a2141745d96edd031f9ff33934649ab4b1cf5bf9a882016a63e243c77d129be61f8f9ab3957b8091019fdb90e2593
+  metadata.gz: b971a8cc52133ce0aed38ed202742fdb45e4be73256abe284e40a1d4ac94b729674cd4faea526397685f26d80fcd307669777941b29b1a28fcbd821adbf6beba
+  data.tar.gz: 00bc7f6c7db02b4d70f45070e250ad726b72150eb976dcf4476f72b58a44ad99d1f59a6ac89033cc5269d2a5f13987a10a8d1cd4d8d6dc0ed4d894e1134baade

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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

data/Gemfile.lock

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

data/README.md

@@ -187,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)

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.1'
+  VERSION = '2.12.0'
 end

data/lib/mailtrap.rb

@@ -28,6 +28,10 @@ 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.1
+  version: 2.12.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 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