Add Stats API

CHANGELOG.md

@@ -1,25 +1,34 @@
+## Unreleased
+
+- Add Sending Stats API
+
 ## [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

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):
 

examples/stats_api.rb

@@ -0,0 +1,48 @@
+require 'mailtrap'
+require 'date'
+require 'time'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+stats = Mailtrap::StatsAPI.new(account_id, client)
+
+# Get aggregated sending stats
+stats.get(start_date: '2026-01-01', end_date: '2026-01-31')
+# => #<struct Mailtrap::SendingStats
+#      delivery_count=150, delivery_rate=0.95,
+#      bounce_count=8, bounce_rate=0.05,
+#      open_count=120, open_rate=0.8,
+#      click_count=60, click_rate=0.5,
+#      spam_count=2, spam_rate=0.013>
+
+# Get stats grouped by domain
+stats.by_domain(start_date: '2026-01-01', end_date: '2026-01-31')
+# => [#<struct Mailtrap::SendingStatGroup
+#      name=:sending_domain_id, value=1,
+#      stats=#<struct Mailtrap::SendingStats delivery_count=100, ...>>, ...]
+
+# Get stats grouped by category
+stats.by_category(start_date: Date.today.prev_day(30), end_date: Date.today)
+# => [#<struct Mailtrap::SendingStatGroup
+#      name=:category, value="Transactional",
+#      stats=#<struct Mailtrap::SendingStats delivery_count=100, ...>>, ...]
+
+# Get stats grouped by email service provider
+stats.by_email_service_provider(start_date: Time.new(2026, 1, 1), end_date: Time.new(2026, 1, 31))
+# => [#<struct Mailtrap::SendingStatGroup
+#      name=:email_service_provider, value="Gmail",
+#      stats=#<struct Mailtrap::SendingStats delivery_count=80, ...>>, ...]
+
+# Get stats grouped by date
+stats.by_date(start_date: '2026-01-01', end_date: '2026-01-31')
+# => [#<struct Mailtrap::SendingStatGroup
+#      name=:date, value="2026-01-01",
+#      stats=#<struct Mailtrap::SendingStats delivery_count=5, ...>>, ...]
+
+# With optional filters
+stats.get(
+  start_date: '2026-01-01',
+  end_date: '2026-01-31',
+  sending_domain_ids: [1, 2],
+  categories: ['Transactional']
+)

lib/mailtrap.rb

@@ -18,6 +18,7 @@
 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

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

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

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