mailtrap 2.5.0 → 2.7.0

data/lib/mailtrap/contact_import.rb

@@ -14,10 +14,5 @@ module Mailtrap
     :updated_contacts_count,
     :contacts_over_limit_count,
     keyword_init: true
-  ) do
-    # @return [Hash] The contact attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
+  )
 end

data/lib/mailtrap/contact_list.rb

@@ -5,10 +5,5 @@ module Mailtrap
   # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/6ec7a37234af2-contact-list
   # @attr_reader id [Integer] The contact list ID
   # @attr_reader name [String] The name of the contact list
-  ContactList = Struct.new(:id, :name, keyword_init: true) do
-    # @return [Hash] The contact list attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
+  ContactList = Struct.new(:id, :name, keyword_init: true)
 end

data/lib/mailtrap/email_template.rb

@@ -26,10 +26,5 @@ module Mailtrap
     :created_at,
     :updated_at,
     keyword_init: true
-  ) do
-    # @return [Hash] The template attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
+  )
 end

data/lib/mailtrap/inbox.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Inbox
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/ee252e413d78a-create-project
+  # @attr_reader id [Integer] The inbox ID
+  # @attr_reader name [String] The inbox name
+  # @attr_reader username [String] The inbox username
+  # @attr_reader password [String, nil] The inbox password
+  # @attr_reader max_size [Integer] The maximum inbox size in MB
+  # @attr_reader status [String] The inbox status
+  # @attr_reader email_username [String] The email username
+  # @attr_reader email_username_enabled [Boolean] Whether the email username is enabled
+  # @attr_reader sent_messages_count [Integer] The count of sent messages
+  # @attr_reader forwarded_messages_count [Integer] The count of forwarded messages
+  # @attr_reader used [Integer] The used inbox size in MB
+  # @attr_reader forward_from_email_address [String] The forwarding email address
+  # @attr_reader project_id [Integer] The associated project ID
+  # @attr_reader domain [String] The inbox domain
+  # @attr_reader pop3_domain [String] The POP3 domain
+  # @attr_reader email_domain [String] The email domain
+  # @attr_reader api_domain [String] The API domain
+  # @attr_reader emails_count [Integer] The total number of emails
+  # @attr_reader emails_unread_count [Integer] The number of unread emails
+  # @attr_reader last_message_sent_at [String, nil] The timestamp of the last sent message
+  # @attr_reader smtp_ports [Array<Integer>] The list of SMTP ports
+  # @attr_reader pop3_ports [Array<Integer>] The list of POP3 ports
+  # @attr_reader max_message_size [Integer] The maximum message size in MB
+  # @attr_reader permissions [Hash] List of permissions
+  Inbox = Struct.new(
+    :id,
+    :name,
+    :username,
+    :password,
+    :max_size,
+    :status,
+    :email_username,
+    :email_username_enabled,
+    :sent_messages_count,
+    :forwarded_messages_count,
+    :used,
+    :forward_from_email_address,
+    :project_id,
+    :domain,
+    :pop3_domain,
+    :email_domain,
+    :api_domain,
+    :emails_count,
+    :emails_unread_count,
+    :last_message_sent_at,
+    :smtp_ports,
+    :pop3_ports,
+    :max_message_size,
+    :permissions,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/inboxes_api.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'inbox'
+
+module Mailtrap
+  class InboxesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name]
+    self.response_class = Inbox
+
+    # Lists all Inboxes for the account
+    # @return [Array<Inbox>] Array of Inboxes
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Retrieves a specific inbox
+    # @param inbox_id [Integer] The inbox identifier
+    # @return [Inbox] Inbox object
+    # @!macro api_errors
+    def get(inbox_id)
+      base_get(inbox_id)
+    end
+
+    # Creates a new inbox
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The inbox name
+    # @return [Inbox] Created inbox object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      validate_options!(options, supported_options + [:project_id])
+      response = client.post("/api/accounts/#{account_id}/projects/#{options[:project_id]}/inboxes",
+                             wrap_request(options))
+      handle_response(response)
+    end
+
+    # Deletes an inbox
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return nil
+    # @!macro api_errors
+    def delete(inbox_id)
+      base_delete(inbox_id)
+    end
+
+    # Updates an existing Inbox
+    # @param inbox_id [Integer] The Inbox identifier
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The inbox name
+    # @option options [String] :email_username The inbox email username
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(inbox_id, options)
+      base_update(inbox_id, options, supported_options + [:email_username])
+    end
+
+    # Delete all messages (emails) from Inbox
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    def clean(inbox_id)
+      response = client.patch("#{base_path}/#{inbox_id}/clean")
+      handle_response(response)
+    end
+
+    # Mark all messages in the inbox as read
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    def mark_as_read(inbox_id)
+      response = client.patch("#{base_path}/#{inbox_id}/all_read")
+      handle_response(response)
+    end
+
+    # Reset SMTP credentials of the inbox
+    # @param inbox_id [Integer] The Inbox identifier
+    # @return [Inbox] Updated Inbox object
+    # @!macro api_errors
+    def reset_credentials(inbox_id)
+      response = client.patch("#{base_path}/#{inbox_id}/reset_credentials")
+      handle_response(response)
+    end
+
+    private
+
+    def wrap_request(options)
+      { inbox: options }
+    end
+
+    def base_path
+      "/api/accounts/#{account_id}/inboxes"
+    end
+  end
+end

data/lib/mailtrap/project.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Project
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/ee252e413d78a-create-project
+  # @attr_reader id [Integer] The project ID
+  # @attr_reader name [String] The project name
+  # @attr_reader share_links [Hash] Admin and viewer share links
+  # @attr_reader inboxes [Array<Mailtrap::Inbox>] Array of inboxes
+  # @attr_reader permissions [Hash] List of permissions
+  #
+  Project = Struct.new(
+    :id,
+    :name,
+    :share_links,
+    :inboxes,
+    :permissions,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/projects_api.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'project'
+require_relative 'inbox'
+
+module Mailtrap
+  class ProjectsAPI
+    include BaseAPI
+
+    self.supported_options = %i[name]
+
+    self.response_class = Project
+
+    # Lists all projects for the account
+    # @return [Array<Project>] Array of projects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    # Retrieves a specific project
+    # @param project_id [Integer] The project ID
+    # @return [Project] Project object
+    # @!macro api_errors
+    def get(project_id)
+      base_get(project_id)
+    end
+
+    # Creates a new project
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The project name
+    # @return [Project] Created project object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing project
+    # @param project_id [Integer] The project ID
+    # @param [Hash] options The parameters to update
+    # @return [Project] Updated project object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(project_id, options)
+      base_update(project_id, options)
+    end
+
+    # Deletes a project
+    # @param project_id [Integer] The project ID
+    # @return nil
+    # @!macro api_errors
+    def delete(project_id)
+      base_delete(project_id)
+    end
+
+    private
+
+    def handle_response(response)
+      build_entity(
+        response.merge(
+          inboxes: response[:inboxes]&.map { |inbox| build_entity(inbox, Mailtrap::Inbox) }
+        ),
+        response_class
+      )
+    end
+
+    def base_path
+      "/api/accounts/#{account_id}/projects"
+    end
+
+    def wrap_request(options)
+      { project: options }
+    end
+  end
+end

data/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

data/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

data/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 [Boolean] Whether the message has been read
+    def read?
+      is_read
+    end
+  end
+end

data/lib/mailtrap/sandbox_messages_api.rb

@@ -0,0 +1,155 @@
+# 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 account_id [Integer] The account ID
+    # @param inbox_id [Integer] The inbox 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, client = Mailtrap::Client.new)
+      raise ArgumentError, 'inbox_id is required' if inbox_id.nil?
+
+      @inbox_id = inbox_id
+
+      super(account_id, 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 is_read [Boolean]
+    # @return [SandboxMessage] Updated Sandbox message object
+    # @!macro api_errors
+    def mark_as_read(message_id, is_read: true)
+      base_update(message_id, { is_read: is_read })
+    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)
+      raise ArgumentError, 'Provide either last_id or page, not both' unless 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 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 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 text_body(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 raw_body(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 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 html_body(message_id)
+      client.get("#{base_path}/#{message_id}/body.html")
+    end
+
+    # Get message as EML
+    # @param message_id [Integer] The sandbox message ID
+    # @return [String] mail message body in EML format.
+    # @!macro api_errors
+    def eml_body(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 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

data/lib/mailtrap/sending_domain.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Sending Domain
+  # @see https://docs.mailtrap.io/developers/management/sending-domains
+  # @attr_reader id [Integer] The sending domain ID
+  # @attr_reader domain_name [String] The sending domain name
+  # @attr_reader demo [Boolean] Whether the sending domain is a demo domain
+  # @attr_reader compliance_status [String] The compliance status of the sending domain
+  # @attr_reader dns_verified [Boolean] Whether the DNS records are verified
+  # @attr_reader dns_verified_at [String, nil] The timestamp when DNS was verified
+  # @attr_reader dns_records [Array] The DNS records for the sending domain
+  # @attr_reader open_tracking_enabled [Boolean] Whether open tracking is enabled
+  # @attr_reader click_tracking_enabled [Boolean] Whether click tracking is enabled
+  # @attr_reader auto_unsubscribe_link_enabled [Boolean] Whether auto unsubscribe link is enabled
+  # @attr_reader custom_domain_tracking_enabled [Boolean] Whether custom domain tracking is enabled
+  # @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 permissions [Hash] The permissions for the sending domain
+  #
+  SendingDomain = Struct.new(
+    :id,
+    :domain_name,
+    :demo,
+    :compliance_status,
+    :dns_verified,
+    :dns_verified_at,
+    :dns_records,
+    :open_tracking_enabled,
+    :click_tracking_enabled,
+    :auto_unsubscribe_link_enabled,
+    :custom_domain_tracking_enabled,
+    :health_alerts_enabled,
+    :critical_alerts_enabled,
+    :alert_recipient_email,
+    :permissions,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  )
+end