mailtrap 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3283b7e6c8af70b1ac8bb3a965868e3b312c01682615c86f7da5104add3bcb
-  data.tar.gz: 8bab417f54c310a6a92b93ed4a1c6ca6a4cd88dae2e0614e3d2f21cda05d8cf0
+  metadata.gz: c1d2ec6f013c1c734b375a56217c2ec6373904851fdc28f25147932bf7d44225
+  data.tar.gz: 3a7c2994b477de66e566ad9cc41c5ca39d70641fa096c92a47af4c0289de6808
 SHA512:
-  metadata.gz: 317490e679342d1c9ac8ae12162268c4102ee410a3d4a9896237894c2a5cd39063595c613d248938a1770cd8f24c7cb4dc72f109c1dabec48f920f92f47cd89d
-  data.tar.gz: 7da01e190af37689aff6aacdeb411f0858c7c75baf809b51266db920e2988021343e73f164728d9d9bf857139ee2f30cbf004b6c50782d7394685ef6513f05d8
+  metadata.gz: 1c2176601df89656a773772072952169caf35c0cff0d193cdab25c07956d09d9ab828b9e2995581512312f8e33f35605623b89052950752d8fc6a6c13cb3f0fc
+  data.tar.gz: 7661abf25236f9bec0a26f5463d92074a2e76b18bb9f5fc1067c3b2f810a7eed518e1a0d211ac61c11cde4eaaeb4542376ddd5ebd9785678adb225be3838092b

data/CHANGELOG.md

@@ -1,25 +1,36 @@
+## [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 
+## [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.8.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):
 

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/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.8.0'
+  VERSION = '2.9.0'
 end

data/lib/mailtrap.rb

@@ -18,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.8.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
@@ -79,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