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'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sending_domains_api'
 

lib/mailtrap/client.rb

@@ -221,8 +221,11 @@ def delete(path)
 
     private
 
-    def http_client_for(host)
-      @http_clients[host] ||= Net::HTTP.new(host, api_port).tap { |client| client.use_ssl = true }
+    def validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
+      raise ArgumentError, 'api_key is required' if api_key.nil?
+      raise ArgumentError, 'api_port is required' if api_port.nil?
+      raise ArgumentError, 'bulk stream is not applicable for sandbox API' if bulk && sandbox
+      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
     end
 
     def select_api_host(bulk:, sandbox:)
@@ -235,14 +238,6 @@ def select_api_host(bulk:, sandbox:)
       end
     end
 
-    def send_path
-      "/api/send#{"/#{inbox_id}" if sandbox}"
-    end
-
-    def batch_request_path
-      "/api/batch#{"/#{inbox_id}" if sandbox}"
-    end
-
     def perform_request(method:, host:, path:, query_params: {}, body: nil)
       http_client = http_client_for(host)
 
@@ -254,6 +249,10 @@ def perform_request(method:, host:, path:, query_params: {}, body: nil)
       handle_response(response)
     end
 
+    def http_client_for(host)
+      @http_clients[host] ||= Net::HTTP.new(host, api_port).tap { |client| client.use_ssl = true }
+    end
+
     def setup_request(method, uri_or_path, body = nil)
       request = case method
                 when :get
@@ -279,17 +278,17 @@ def setup_request(method, uri_or_path, body = nil)
     def handle_response(response) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
       case response
       when Net::HTTPOK, Net::HTTPCreated
-        json_response(response.body)
+        parse_response(response)
       when Net::HTTPNoContent
         nil
       when Net::HTTPBadRequest
         raise Mailtrap::Error, ['bad request'] if response.body.empty?
 
-        raise Mailtrap::Error, response_errors(response.body)
+        raise Mailtrap::Error, response_errors(response)
       when Net::HTTPUnauthorized
-        raise Mailtrap::AuthorizationError, response_errors(response.body)
+        raise Mailtrap::AuthorizationError, response_errors(response)
       when Net::HTTPForbidden
-        raise Mailtrap::RejectionError, response_errors(response.body)
+        raise Mailtrap::RejectionError, response_errors(response)
       when Net::HTTPPayloadTooLarge
         raise Mailtrap::MailSizeError, ['message too large']
       when Net::HTTPTooManyRequests
@@ -303,20 +302,37 @@ def handle_response(response) # rubocop:disable Metrics/CyclomaticComplexity, Me
       end
     end
 
-    def response_errors(body)
-      parsed_body = json_response(body)
-      Array(parsed_body[:errors] || parsed_body[:error])
+    def parse_response(response)
+      if json_response?(response)
+        json_response(response.body)
+      else
+        response.body
+      end
+    end
+
+    def response_errors(response)
+      if json_response?(response)
+        parsed_body = json_response(response.body)
+        Array(parsed_body[:errors] || parsed_body[:error])
+      else
+        [response.body]
+      end
+    end
+
+    def json_response?(response)
+      response.content_type == 'application/json'
     end
 
     def json_response(body)
       JSON.parse(body, symbolize_names: true)
     end
 
-    def validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
-      raise ArgumentError, 'api_key is required' if api_key.nil?
-      raise ArgumentError, 'api_port is required' if api_port.nil?
-      raise ArgumentError, 'bulk stream is not applicable for sandbox API' if bulk && sandbox
-      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
+    def send_path
+      "/api/send#{"/#{inbox_id}" if sandbox}"
+    end
+
+    def batch_request_path
+      "/api/batch#{"/#{inbox_id}" if sandbox}"
     end
   end
 end

lib/mailtrap/sandbox_message.rb

@@ -0,0 +1,54 @@
+# 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
+  )
+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")
+    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")
+    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")
+    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")
+    end
+
+    # Get message as EML
+    # @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")
+    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