Add Sandbox messages API

lib/mailtrap.rb

@@ -11,6 +11,7 @@
 require_relative 'mailtrap/contact_imports_api'
 require_relative 'mailtrap/suppressions_api'
 require_relative 'mailtrap/projects_api'
+require_relative 'mailtrap/sandbox_messages_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/client.rb

@@ -168,14 +168,16 @@ def send(mail)
     # Performs a GET request to the specified path
     # @param path [String] The request path
     # @param query_params [Hash] Query parameters to append to the URL (optional)
+    # @param custom_parser [Proc] custom parsing function for the response body (optional)
     # @return [Hash, nil] The JSON response
     # @!macro api_errors
-    def get(path, query_params = {})
+    def get(path, query_params = {}, custom_parser: nil)
       perform_request(
         method: :get,
         host: general_api_host,
         path:,
-        query_params:
+        query_params:,
+        custom_parser:
       )
     end
 
@@ -243,15 +245,15 @@ def batch_request_path
       "/api/batch#{"/#{inbox_id}" if sandbox}"
     end
 
-    def perform_request(method:, host:, path:, query_params: {}, body: nil)
+    def perform_request(method:, host:, path:, query_params: {}, body: nil, custom_parser: nil)
       http_client = http_client_for(host)
 
       uri = URI::HTTPS.build(host:, path:)
       uri.query = URI.encode_www_form(query_params) if query_params.any?
 
       request = setup_request(method, uri, body)
       response = http_client.request(request)
-      handle_response(response)
+      handle_response(response, custom_parser:)
     end
 
     def setup_request(method, uri_or_path, body = nil)
@@ -276,10 +278,10 @@ def setup_request(method, uri_or_path, body = nil)
       request
     end
 
-    def handle_response(response) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def handle_response(response, custom_parser: nil) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
       case response
       when Net::HTTPOK, Net::HTTPCreated
-        json_response(response.body)
+        custom_parser.nil? ? json_response(response.body) : custom_parser.call(response.body)
       when Net::HTTPNoContent
         nil
       when Net::HTTPBadRequest

lib/mailtrap/sandbox_message.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Sandbox Message
+  # @see https://docs.mailtrap.io/developers/email-sandbox/email-sandbox-api/messages
+  # @attr_reader id [Integer] The message ID
+  # @attr_reader inbox_id [Integer] The inbox ID
+  # @attr_reader subject [String] The message subject
+  # @attr_reader sent_at [String] The timestamp when the message was sent
+  # @attr_reader from_email [String] The sender's email address
+  # @attr_reader from_name [String] The sender's name
+  # @attr_reader to_email [String] The recipient's email address
+  # @attr_reader to_name [String] The recipient's name
+  # @attr_reader email_size [Integer] The size of the email in bytes
+  # @attr_reader is_read [Boolean] Whether the message has been read
+  # @attr_reader created_at [String] The timestamp when the message was created
+  # @attr_reader updated_at [String] The timestamp when the message was last updated
+  # @attr_reader html_body_size [Integer] The size of the HTML body in bytes
+  # @attr_reader text_body_size [Integer] The size of the text body in bytes
+  # @attr_reader human_size [String] The human-readable size of the email
+  # @attr_reader html_path [String] The path to the HTML version of the email
+  # @attr_reader txt_path [String] The path to the text version of the email
+  # @attr_reader raw_path [String] The path to the raw version of the email
+  # @attr_reader download_path [String] The path to download the email
+  # @attr_reader html_source_path [String] The path to the HTML source of the email
+  # @attr_reader blacklists_report_info [Boolean] Information about blacklists report
+  # @attr_reader smtp_information [Hash] Information about SMTP
+  #
+  SandboxMessage = Struct.new(
+    :id,
+    :inbox_id,
+    :subject,
+    :sent_at,
+    :from_email,
+    :from_name,
+    :to_email,
+    :to_name,
+    :email_size,
+    :is_read,
+    :created_at,
+    :updated_at,
+    :html_body_size,
+    :text_body_size,
+    :human_size,
+    :html_path,
+    :txt_path,
+    :raw_path,
+    :download_path,
+    :html_source_path,
+    :blacklists_report_info,
+    :smtp_information,
+    keyword_init: true
+  ) do
+    # @return [Hash] The SendingDomain attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

lib/mailtrap/sandbox_messages_api.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'sandbox_message'
+
+module Mailtrap
+  class SandboxMessagesAPI
+    include BaseAPI
+
+    attr_reader :account_id, :inbox_id, :client
+
+    self.supported_options = %i[is_read]
+
+    self.response_class = SandboxMessage
+
+    # @param inbox_id [Integer] The inbox ID
+    # @param account_id [Integer] The account ID
+    # @param client [Mailtrap::Client] The client instance
+    # @raise [ArgumentError] If account_id is nil
+    def initialize(inbox_id, account_id = ENV.fetch('MAILTRAP_ACCOUNT_ID'), client = Mailtrap::Client.new)
+      raise ArgumentError, 'account_id is required' if account_id.nil?
+      raise ArgumentError, 'inbox_id is required' if inbox_id.nil?
+
+      @account_id = account_id
+      @inbox_id = inbox_id
+      @client = client
+    end
+
+    # Retrieves a specific sandbox message from inbox
+    # @param message_id [Integer] The sandbox message ID
+    # @return [SandboxMessage] Sandbox message object
+    # @!macro api_errors
+    def get(message_id)
+      base_get(message_id)
+    end
+
+    # Deletes a sandbox message
+    # @param message_id [Integer] The sandbox message ID
+    # @return [SandboxMessage] Deleted Sandbox message object
+    # @!macro api_errors
+    def delete(message_id)
+      base_delete(message_id)
+    end
+
+    # Updates an existing sandbox message
+    # @param message_id [Integer] The sandbox message ID
+    # @param [Hash] options The parameters to update
+    # @return [SandboxMessage] Updated Sandbox message object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(message_id, options)
+      base_update(message_id, options)
+    end
+
+    # Lists all sandbox messages for the account, limited up to 30 at once
+    # @param search [String] Search query string. Matches subject, to_email, and to_name.
+    # @param last_id [Integer] If specified, a page of records before last_id is returned.
+    # Overrides page if both are given.
+    # @param page [Integer] Page number for paginated results.
+    # @return [Array<SandboxMessage>] Array of sandbox message objects
+    # @!macro api_errors
+    def list(search: nil, last_id: nil, page: nil)
+      query_params = {}
+      query_params[:search] = search unless search.nil?
+      query_params[:last_id] = last_id unless last_id.nil?
+      query_params[:page] = page unless page.nil?
+
+      base_list(query_params)
+    end
+
+    # Forward message to an email address.
+    # @param message_id [Integer] The Sandbox message ID
+    # @param email [String] The email to forward sandbox message to
+    # @return [String] Forwarded message confirmation
+    # @!macro api_errors
+    def forward_message(message_id, email)
+      client.post("#{base_path}/#{message_id}/forward", { email: email })
+    end
+
+    # Get message spam score
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [Hash] Spam report
+    # @!macro api_errors
+    def get_spam_score(message_id)
+      client.get("#{base_path}/#{message_id}/spam_report")
+    end
+
+    # Get message HTML analysis
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [Hash] brief HTML report
+    # @!macro api_errors
+    def get_html_analysis(message_id)
+      client.get("#{base_path}/#{message_id}/analyze")
+    end
+
+    # Get text message
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [String] text email body
+    # @!macro api_errors
+    def get_text_message(message_id)
+      client.get("#{base_path}/#{message_id}/body.txt", custom_parser: ->(response) { response })
+    end
+
+    # Get raw message
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [String] raw email body
+    # @!macro api_errors
+    def get_raw_message(message_id)
+      client.get("#{base_path}/#{message_id}/body.raw", custom_parser: ->(response) { response })
+    end
+
+    # Get message source
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [String] HTML source of a message.
+    # @!macro api_errors
+    def get_html_source(message_id)
+      client.get("#{base_path}/#{message_id}/body.htmlsource", custom_parser: ->(response) { response })
+    end
+
+    # Get formatted HTML email body. Not applicable for plain text emails.
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [String] message body in html format.
+    # @!macro api_errors
+    def get_html_message(message_id)
+      client.get("#{base_path}/#{message_id}/body.html", custom_parser: ->(response) { response })
+    end
+
+    # Get mail headers
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [Hash] mail headers of the message.
+    # @!macro api_errors
+    def get_message_as_eml(message_id)
+      client.get("#{base_path}/#{message_id}/body.eml", custom_parser: ->(response) { response })
+    end
+
+    # Get mail headers
+    # @param message_id [Integer] The Sandbox message ID
+    # @return [Hash] mail headers of the message.
+    # @!macro api_errors
+    def get_mail_headers(message_id)
+      client.get("#{base_path}/#{message_id}/mail_headers")
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/inboxes/#{inbox_id}/messages"
+    end
+
+    def wrap_request(options)
+      { message: options }
+    end
+  end
+end