Add Sandbox Attachments API

CHANGELOG.md

@@ -1,5 +1,6 @@
 - Add Sandbox Messages API
 - Add Sending Domains API
+- Add Sandbox Attachments API
 
 ## [2.6.0] - 2026-01-27
 - Add Inboxes API

README.md

@@ -183,6 +183,7 @@ Email Sandbox (Testing):
 - Projects CRUD – [`projects_api.rb`](examples/projects_api.rb)
 - Inboxes CRUD - [`inboxes_api.rb`](examples/inboxes_api.rb)
 - Sandbox Messages CRUD - [`sandbox_messages_api.rb`](examples/sandbox_messages_api.rb)
+- Sandbox Attachments API - [`sandbox_attachments_api.rb`](examples/sandbox_attachments_api.rb)
 
 Contact management:
 

examples/sandbox_attachments_api.rb

@@ -0,0 +1,19 @@
+require 'mailtrap'
+
+account_id = 3229
+inbox_id = 12
+message_id = 123
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+sandbox_attachments = Mailtrap::SandboxAttachmentsAPI.new(account_id, inbox_id, message_id, client)
+
+# List all attachments for a sandbox message (up to 30)
+sandbox_attachments.list
+# => [#<struct Mailtrap::SandboxAttachment id=1, filename="document.pdf", ...>, ...]
+
+# Get a specific attachment by ID
+attachment_id = 456
+sandbox_attachments.get(attachment_id)
+# => #<struct Mailtrap::SandboxAttachment id=456, message_id=123, filename="document.pdf",
+#     attachment_type="attachment", content_type="application/pdf", content_id=nil,
+#     transfer_encoding="base64", attachment_size=1024, created_at="...", updated_at="...",
+#     attachment_human_size="1 KB", download_path="/path/to/download", ...>

lib/mailtrap.rb

@@ -14,6 +14,7 @@
 require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sandbox_messages_api'
+require_relative 'mailtrap/sandbox_attachments_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/sandbox_attachment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for SandboxAttachment
+  # @see https://docs.mailtrap.io/developers/email-sandbox/email-sandbox-api/attachments
+  # @attr_reader id [Integer] The attachment ID
+  # @attr_reader message_id [Integer] The message ID
+  # @attr_reader filename [String] The attachment filename
+  # @attr_reader attachment_type [String] The attachment type
+  # @attr_reader content_type [String] The attachment content type
+  # @attr_reader content_id [String] The attachment content ID
+  # @attr_reader transfer_encoding [String] The attachment transfer encoding
+  # @attr_reader attachment_size [Integer] The attachment size in bytes
+  # @attr_reader created_at [String] The attachment creation timestamp
+  # @attr_reader updated_at [String] The attachment update timestamp
+  # @attr_reader attachment_human_size [String] The attachment size in human-readable format
+  # @attr_reader download_path [String] The attachment download path
+  #
+  SandboxAttachment = Struct.new(
+    :id,
+    :message_id,
+    :filename,
+    :attachment_type,
+    :content_type,
+    :content_id,
+    :transfer_encoding,
+    :attachment_size,
+    :created_at,
+    :updated_at,
+    :attachment_human_size,
+    :download_path,
+    keyword_init: true
+  )
+end

lib/mailtrap/sandbox_attachments_api.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'sandbox_attachment'
+
+module Mailtrap
+  class SandboxAttachmentsAPI
+    include BaseAPI
+
+    attr_reader :account_id, :inbox_id, :sandbox_message_id, :client
+
+    self.response_class = SandboxAttachment
+
+    # @param account_id [Integer] The account ID
+    # @param inbox_id [Integer] The inbox ID
+    # @param sandbox_message_id [Integer] The message ID
+    # @param client [Mailtrap::Client] The client instance
+    # @raise [ArgumentError] If account_id is nil
+    # @raise [ArgumentError] If inbox_id is nil
+    def initialize(account_id, inbox_id, sandbox_message_id, client = Mailtrap::Client.new)
+      raise ArgumentError, 'inbox_id is required' if inbox_id.nil?
+      raise ArgumentError, 'sandbox_message_id is required' if sandbox_message_id.nil?
+
+      @inbox_id = inbox_id
+      @sandbox_message_id = sandbox_message_id
+
+      super(account_id, client)
+    end
+
+    # Retrieves a specific sandbox attachment
+    # @param sandbox_attachment_id [Integer] The sandbox attachment ID
+    # @return [SandboxAttachment] Sandbox attachment object
+    # @!macro api_errors
+    def get(sandbox_attachment_id)
+      base_get(sandbox_attachment_id)
+    end
+
+    # Lists all sandbox attachments for a message, limited up to 30 at once
+    # @return [Array<SandboxAttachment>] Array of sandbox attachment objects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/inboxes/#{inbox_id}/messages/#{sandbox_message_id}/attachments"
+    end
+  end
+end

lib/mailtrap/sandbox_message.rb

@@ -50,5 +50,10 @@ module Mailtrap
     :blacklists_report_info,
     :smtp_information,
     keyword_init: true
-  )
+  ) do
+    # @return [Boolean] Whether the message has been read
+    def read?
+      is_read
+    end
+  end
 end