mailtrap 2.7.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a56e52ebde096ddaa019f4c16e15f63fe37ace69d91892f4c92044c0727b3c3f
-  data.tar.gz: 79a7aca8251526389c4faa2f643ca8f7e58182de4dcbada0af2d8f9a5afe6464
+  metadata.gz: c1d2ec6f013c1c734b375a56217c2ec6373904851fdc28f25147932bf7d44225
+  data.tar.gz: 3a7c2994b477de66e566ad9cc41c5ca39d70641fa096c92a47af4c0289de6808
 SHA512:
-  metadata.gz: df5e86fd7a0d31a5b717e189ae9637f6e0f413dad2d4fd2c9adbc56e7be5197ef5a59a759dc6eee9ff19a98c9196c7d5f1a984b3ee5f75ef69a5ca0f376a5519
-  data.tar.gz: 516e66780366eaf9f76b07f0957092b345fdd0262cd15dd997dcde5887276b7b37ba9c5c29971c6e7e53082e74db4deb5575ba1b4e0ebab4341fae05d7accc98
+  metadata.gz: 1c2176601df89656a773772072952169caf35c0cff0d193cdab25c07956d09d9ab828b9e2995581512312f8e33f35605623b89052950752d8fc6a6c13cb3f0fc
+  data.tar.gz: 7661abf25236f9bec0a26f5463d92074a2e76b18bb9f5fc1067c3b2f810a7eed518e1a0d211ac61c11cde4eaaeb4542376ddd5ebd9785678adb225be3838092b

data/CHANGELOG.md

@@ -1,21 +1,36 @@
-## [2.7.0] - 2026-02-24 
+## [2.9.0] - 2026-03-13
+
+- Add Sending Stats API
+- Parse `reply_to` as a structured address field instead of passing it as a raw
+  header when sending with Action Mailer
+
+## [2.8.0] - 2026-03-03
+
+- Add Account Accesses API
+- Add Billing API
+
+## [2.7.0] - 2026-02-24
+
 - Add Sandbox Messages API
 - Add Sending Domains API
 - Add Sandbox Attachments API
 - Add Accounts API
 
 ## [2.6.0] - 2026-01-27
+
 - Add Inboxes API
 - Add Projects API
 - Models' `to_h` now returns all fields without compacting
 
 ## [2.5.0] - 2025-11-10
+
 - Add Contact Imports API
 - Add Suppressions API
 - Write the message IDs to the message when sending with Action Mailer
 - Fix versioning :)
 
 ## [2.4.1] - 2025-08-21
+
 - Set `template_uuid` and `template_variables` when building mail from `Mail::Message`
 
 ## [2.4.0] - 2025-08-04

data/Gemfile.lock

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

data/README.md

@@ -177,6 +177,7 @@ Email API:
 - Full Email Sending – [`full.rb`](examples/full.rb)
 - Batch Sending – [`batch.rb`](examples/batch.rb)
 - Sending Domains API  – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
+- Sending Stats API – [`stats_api.rb`](examples/stats_api.rb)
 
 Email Sandbox (Testing):
 
@@ -191,9 +192,11 @@ Contact management:
 
 General:
 
-- Templates CRUD – [`email_templates_api.rb`](examples/email_templates_api.rb)
-- Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 - Accounts API – [`accounts_api.rb`](examples/accounts_api.rb)
+- Account Accesses API – [`account_accesses_api.rb`](examples/account_accesses_api.rb)
+- Billing API – [`billing_api.rb`](examples/billing_api.rb)
+- Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
+- Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 
 ## Migration guide v1 → v2
 

data/lib/mailtrap/account_access.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for AccountAccess
+  # @see https://docs.mailtrap.io/developers/account-management/access-control
+  # @attr_reader id [Integer] The access ID
+  # @attr_reader specifier_type [String] The type of the specifier
+  # @attr_reader specifier [Hash] The specifier for the access
+  # @attr_reader resources [Array<Hash>] The resources this access applies to
+  # @attr_reader permissions [Hash] The permissions granted
+  #
+  AccountAccess = Struct.new(
+    :id,
+    :specifier_type,
+    :specifier,
+    :resources,
+    :permissions,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/account_accesses_api.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'account_access'
+
+module Mailtrap
+  class AccountAccessesAPI
+    include BaseAPI
+
+    attr_reader :account_id
+
+    self.response_class = AccountAccess
+
+    # Retrieves a list of account accesses with optional filtering by domain, inbox, or project IDs
+    # @param domain_ids [Array<Integer>] Optional array of domain IDs to filter by
+    # @param inbox_ids [Array<Integer>] Optional array of inbox IDs to filter by
+    # @param project_ids [Array<Integer>] Optional array of project IDs to filter by
+    # @return [Array<AccountAccess>] List of account access objects
+    # @!macro api_errors
+    def list(domain_ids: [], inbox_ids: [], project_ids: [])
+      query_params = {}
+      query_params[:domain_ids] = domain_ids unless domain_ids.empty?
+      query_params[:inbox_ids] = inbox_ids unless inbox_ids.empty?
+      query_params[:project_ids] = project_ids unless project_ids.empty?
+
+      base_list(query_params)
+    end
+
+    # Deletes an account access
+    # @param account_access_id [Integer] The account access ID
+    # @return [Hash]
+    # @!macro api_errors
+    def delete(account_access_id)
+      base_delete(account_access_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/account_accesses"
+    end
+  end
+end

data/lib/mailtrap/billing_api.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'billing_usage'
+
+module Mailtrap
+  class BillingAPI
+    include BaseAPI
+
+    # Get current billing cycle usage
+    # @return [BillingUsage] Billing usage data for account
+    # @!macro api_errors
+    def usage
+      response = client.get("/api/accounts/#{account_id}/billing/usage")
+      build_entity(response, BillingUsage)
+    end
+  end
+end

data/lib/mailtrap/billing_usage.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Billing Usage data
+  # @see https://docs.mailtrap.io/developers/account-management/billing
+  # @attr_reader billing [Hash] The billing cycle details
+  # @attr_reader testing [Hash] Testing subscription usage
+  # @attr_reader sending [Hash] Sending subscription usage
+  #
+  BillingUsage = Struct.new(
+    :billing,
+    :testing,
+    :sending,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/mail.rb

@@ -17,6 +17,7 @@ module Mailtrap
       category
       customvariables
       contenttype
+      replyto
     ].freeze
     private_constant :SPECIAL_HEADERS
 
@@ -189,12 +190,13 @@ module Mailtrap
       # Builds a mail object from Mail::Message
       # @param message [Mail::Message]
       # @return [Mailtrap::Mail::Base]
-      def from_message(message)
+      def from_message(message) # rubocop:disable Metrics/AbcSize
         Mailtrap::Mail::Base.new(
           from: prepare_addresses(message['from']).first,
           to: prepare_addresses(message['to']),
           cc: prepare_addresses(message['cc']),
           bcc: prepare_addresses(message['bcc']),
+          reply_to: prepare_addresses(message['reply-to']).first,
           subject: message.subject,
           text: prepare_text_part(message),
           html: prepare_html_part(message),

data/lib/mailtrap/project.rb

@@ -2,7 +2,7 @@
 
 module Mailtrap
   # Data Transfer Object for Project
-  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/ee252e413d78a-create-project
+  # @see https://docs.mailtrap.io/developers/email-sandbox/projects
   # @attr_reader id [Integer] The project ID
   # @attr_reader name [String] The project name
   # @attr_reader share_links [Hash] Admin and viewer share links

data/lib/mailtrap/sending_stat_group.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for grouped Sending Stats data
+  # @attr_reader name [Symbol] Group type (:category, :date, :sending_domain_id, :email_service_provider)
+  # @attr_reader value [String, Integer] Group value (e.g., "Transactional", "2026-01-01", 1, "Gmail")
+  # @attr_reader stats [SendingStats] Sending stats for this group
+  #
+  SendingStatGroup = Struct.new(
+    :name,
+    :value,
+    :stats,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/sending_stats.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Sending Stats data
+  # @see https://docs.mailtrap.io/developers/email-sending-stats
+  # @attr_reader delivery_count [Integer] Number of delivered emails
+  # @attr_reader delivery_rate [Float] Delivery rate
+  # @attr_reader bounce_count [Integer] Number of bounced emails
+  # @attr_reader bounce_rate [Float] Bounce rate
+  # @attr_reader open_count [Integer] Number of opened emails
+  # @attr_reader open_rate [Float] Open rate
+  # @attr_reader click_count [Integer] Number of clicked emails
+  # @attr_reader click_rate [Float] Click rate
+  # @attr_reader spam_count [Integer] Number of spam reports
+  # @attr_reader spam_rate [Float] Spam rate
+  #
+  SendingStats = Struct.new(
+    :delivery_count,
+    :delivery_rate,
+    :bounce_count,
+    :bounce_rate,
+    :open_count,
+    :open_rate,
+    :click_count,
+    :click_rate,
+    :spam_count,
+    :spam_rate,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/stats_api.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'base_api'
+require_relative 'sending_stats'
+require_relative 'sending_stat_group'
+
+module Mailtrap
+  class StatsAPI
+    include BaseAPI
+
+    ARRAY_FILTERS = %i[sending_domain_ids sending_streams categories email_service_providers].freeze
+    GROUP_KEYS = {
+      'domains' => :sending_domain_id,
+      'categories' => :category,
+      'email_service_providers' => :email_service_provider,
+      'date' => :date
+    }.freeze
+
+    # Get aggregated sending stats
+    # @param start_date [String, Date, Time] Start date for the stats period (required)
+    # @param end_date [String, Date, Time] End date for the stats period (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sending_streams [Array<String>] Filter by sending streams
+    # @param categories [Array<String>] Filter by categories
+    # @param email_service_providers [Array<String>] Filter by email service providers
+    # @return [SendingStats] Aggregated sending stats
+    # @!macro api_errors
+    def get(start_date:, end_date:, sending_domain_ids: nil, sending_streams: nil, categories: nil, # rubocop:disable Metrics/ParameterLists
+            email_service_providers: nil)
+      query_params = build_query_params(
+        start_date, end_date,
+        { sending_domain_ids:, sending_streams:, categories:, email_service_providers: }
+      )
+      response = client.get(base_path, query_params)
+      build_entity(response, SendingStats)
+    end
+
+    # Get sending stats grouped by domain
+    # @param start_date [String, Date, Time] Start date for the stats period (required)
+    # @param end_date [String, Date, Time] End date for the stats period (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sending_streams [Array<String>] Filter by sending streams
+    # @param categories [Array<String>] Filter by categories
+    # @param email_service_providers [Array<String>] Filter by email service providers
+    # @return [Array<SendingStatGroup>] Array of SendingStatGroup structs with sending_domain_id and stats
+    # @!macro api_errors
+    def by_domain(start_date:, end_date:, sending_domain_ids: nil, sending_streams: nil, categories: nil, # rubocop:disable Metrics/ParameterLists
+                  email_service_providers: nil)
+      grouped_stats('domains', start_date, end_date,
+                    { sending_domain_ids:, sending_streams:, categories:, email_service_providers: })
+    end
+
+    # Get sending stats grouped by category
+    # @param start_date [String, Date, Time] Start date for the stats period (required)
+    # @param end_date [String, Date, Time] End date for the stats period (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sending_streams [Array<String>] Filter by sending streams
+    # @param categories [Array<String>] Filter by categories
+    # @param email_service_providers [Array<String>] Filter by email service providers
+    # @return [Array<SendingStatGroup>] Array of SendingStatGroup structs with category and stats
+    # @!macro api_errors
+    def by_category(start_date:, end_date:, sending_domain_ids: nil, sending_streams: nil, categories: nil, # rubocop:disable Metrics/ParameterLists
+                    email_service_providers: nil)
+      grouped_stats('categories', start_date, end_date,
+                    { sending_domain_ids:, sending_streams:, categories:, email_service_providers: })
+    end
+
+    # Get sending stats grouped by email service provider
+    # @param start_date [String, Date, Time] Start date for the stats period (required)
+    # @param end_date [String, Date, Time] End date for the stats period (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sending_streams [Array<String>] Filter by sending streams
+    # @param categories [Array<String>] Filter by categories
+    # @param email_service_providers [Array<String>] Filter by email service providers
+    # @return [Array<SendingStatGroup>] Array of SendingStatGroup structs with email_service_provider and stats
+    # @!macro api_errors
+    def by_email_service_provider(start_date:, end_date:, sending_domain_ids: nil, sending_streams: nil, # rubocop:disable Metrics/ParameterLists
+                                  categories: nil, email_service_providers: nil)
+      grouped_stats('email_service_providers', start_date, end_date,
+                    { sending_domain_ids:, sending_streams:, categories:, email_service_providers: })
+    end
+
+    # Get sending stats grouped by date
+    # @param start_date [String, Date, Time] Start date for the stats period (required)
+    # @param end_date [String, Date, Time] End date for the stats period (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sending_streams [Array<String>] Filter by sending streams
+    # @param categories [Array<String>] Filter by categories
+    # @param email_service_providers [Array<String>] Filter by email service providers
+    # @return [Array<SendingStatGroup>] Array of SendingStatGroup structs with date and stats
+    # @!macro api_errors
+    def by_date(start_date:, end_date:, sending_domain_ids: nil, sending_streams: nil, categories: nil, # rubocop:disable Metrics/ParameterLists
+                email_service_providers: nil)
+      grouped_stats('date', start_date, end_date,
+                    { sending_domain_ids:, sending_streams:, categories:, email_service_providers: })
+    end
+
+    private
+
+    def grouped_stats(group, start_date, end_date, filters)
+      query_params = build_query_params(start_date, end_date, filters)
+      response = client.get("#{base_path}/#{group}", query_params)
+      group_key = GROUP_KEYS.fetch(group)
+
+      response.map do |item|
+        SendingStatGroup.new(
+          name: group_key,
+          value: item[group_key],
+          stats: build_entity(item[:stats], SendingStats)
+        )
+      end
+    end
+
+    def build_query_params(start_date, end_date, filters)
+      params = { start_date: normalize_date(start_date), end_date: normalize_date(end_date) }
+
+      ARRAY_FILTERS.each do |filter_key|
+        values = filters[filter_key]
+        params["#{filter_key}[]"] = values if values
+      end
+
+      params
+    end
+
+    def normalize_date(value)
+      case value
+      when Date
+        value.iso8601
+      when Time
+        value.strftime('%F')
+      when String
+        unless /\A\d{4}-\d{2}-\d{2}\z/.match?(value)
+          raise ArgumentError,
+                "Invalid date: #{value.inspect}. Expected a Date, Time, or String in YYYY-MM-DD format."
+        end
+
+        Date.iso8601(value).iso8601
+      else
+        raise ArgumentError,
+              "Invalid date: #{value.inspect}. Expected a Date, Time, or String in YYYY-MM-DD format."
+      end
+    rescue Date::Error
+      raise ArgumentError, "Invalid date: #{value.inspect}. Expected a Date, Time, or String in YYYY-MM-DD format."
+    end
+
+    def base_path
+      "/api/accounts/#{account_id}/stats"
+    end
+  end
+end

data/lib/mailtrap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  VERSION = '2.7.0'
+  VERSION = '2.9.0'
 end

data/lib/mailtrap.rb

@@ -5,6 +5,8 @@ require_relative 'mailtrap/mail'
 require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
 require_relative 'mailtrap/accounts_api'
+require_relative 'mailtrap/account_accesses_api'
+require_relative 'mailtrap/billing_api'
 require_relative 'mailtrap/email_templates_api'
 require_relative 'mailtrap/contacts_api'
 require_relative 'mailtrap/contact_lists_api'
@@ -16,6 +18,7 @@ require_relative 'mailtrap/projects_api'
 require_relative 'mailtrap/inboxes_api'
 require_relative 'mailtrap/sandbox_messages_api'
 require_relative 'mailtrap/sandbox_attachments_api'
+require_relative 'mailtrap/stats_api'
 
 module Mailtrap
   # @!macro api_errors

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
@@ -43,12 +43,16 @@ files:
 - Rakefile
 - lib/mailtrap.rb
 - lib/mailtrap/account.rb
+- lib/mailtrap/account_access.rb
+- lib/mailtrap/account_accesses_api.rb
 - lib/mailtrap/accounts_api.rb
 - lib/mailtrap/action_mailer.rb
 - lib/mailtrap/action_mailer/delivery_method.rb
 - lib/mailtrap/action_mailer/railtie.rb
 - lib/mailtrap/attachment.rb
 - lib/mailtrap/base_api.rb
+- lib/mailtrap/billing_api.rb
+- lib/mailtrap/billing_usage.rb
 - lib/mailtrap/client.rb
 - lib/mailtrap/contact.rb
 - lib/mailtrap/contact_field.rb
@@ -75,6 +79,9 @@ files:
 - lib/mailtrap/sandbox_messages_api.rb
 - lib/mailtrap/sending_domain.rb
 - lib/mailtrap/sending_domains_api.rb
+- lib/mailtrap/sending_stat_group.rb
+- lib/mailtrap/sending_stats.rb
+- lib/mailtrap/stats_api.rb
 - lib/mailtrap/suppression.rb
 - lib/mailtrap/suppressions_api.rb
 - lib/mailtrap/version.rb