mailtrap 2.18.0 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df2746012d3720b47808a3bd7b8f44f473b49f53bf30b0b758d4467e0b8a578d
-  data.tar.gz: ba58958bb95d0344e5107c82b76a2a3a1586ea9bfe16211e07d39e167c119d82
+  metadata.gz: 2749218455a3db4dce0286b7c6aacda197ac2fa7e97547def63703d5df982aa9
+  data.tar.gz: c324fcd9a6d8b788609ae48f5a4a1ca68aaf74887a036c6625631b1e643f79b6
 SHA512:
-  metadata.gz: b3e163c56c0f08fc0be204e73a471fa451d5d8ae2eb87700f223c9e44a8a14161b88f916ac6d0d88b37b14c19807fd4d49424aa71b8075b4d7cbd8c87edbe487
-  data.tar.gz: f7cde5772e9b716761678f4d230b8f8e2d0ed6ba7b0f4afb5546377f36add5a991cc0f4e4e7cb2a44ee0f7c97419f56f732f31cb4f771ef698f154920007b3d5
+  metadata.gz: 2c739fdf5614960c3e36a239ab922d879a91fe6063652f8bf3ef7dfd2b22f145a969fd72cbd2c6b0dcdf977481e1fa5f35d37104fad2d6fc2d71f83eed136fa2
+  data.tar.gz: cfd90df52872218ddfbb80082a885ccb07898e7e1fc42fef8da12361d9e614e58bfe0e8672a75c5e4238974dd22615000a997001b9c78eac19709e09396aa45b

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [2.19.0] - 2026-10-29
+
+## What's Changed
+* Add MarketingStatsAPI for GET /api/marketing/stats by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/136
+* Fix CI on Ubuntu 26.04 by testing Ruby series, not exact patches by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/137
+
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.18.0...v2.19.0
+
 ## [2.18.0] - 2026-10-07
 
 ## What's Changed

data/Gemfile.lock

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

data/README.md

@@ -204,6 +204,7 @@ Contact management:
 Email marketing:
 
 - Email Campaigns CRUD, Lifecycle Actions & Stats – [`email_campaigns_api.rb`](examples/email_campaigns_api.rb)
+- Email Marketing Stats API – [`marketing_stats_api.rb`](examples/marketing_stats_api.rb)
 
 General:
 

data/lib/mailtrap/marketing_stats.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Email Marketing Stats
+  #
+  # Aggregated metrics of the account's Email Marketing traffic (campaigns and automations) for
+  # the requested period and filters. Rates are fractions from 0 to 1. Every count and rate is +0+
+  # when nothing matched.
+  # @see https://docs.mailtrap.io/developers/email-marketing/marketing-stats
+  # @attr_reader delivery_count [Integer] Number of delivered messages
+  # @attr_reader delivery_rate [Float, Integer] Share of sent messages that were delivered (0–1)
+  # @attr_reader bounce_count [Integer] Number of bounced messages
+  # @attr_reader bounce_rate [Float, Integer] Share of sent messages that bounced (0–1)
+  # @attr_reader open_count [Integer] Number of opened messages
+  # @attr_reader open_rate [Float, Integer] Share of delivered messages that were opened (0–1)
+  # @attr_reader click_count [Integer] Number of clicked messages
+  # @attr_reader click_rate [Float, Integer] Share of delivered messages that were clicked (0–1)
+  # @attr_reader spam_count [Integer] Number of spam complaints
+  # @attr_reader spam_rate [Float, Integer] Share of delivered messages marked as spam (0–1)
+  # @attr_reader unsubscription_count [Integer] Number of unsubscriptions
+  # @attr_reader unsubscription_rate [Float, Integer] Share of delivered messages that unsubscribed (0–1)
+  # @attr_reader sent_count [Integer] Number of sent messages (delivered plus bounced)
+  MarketingStats = Struct.new(
+    :delivery_count,
+    :delivery_rate,
+    :bounce_count,
+    :bounce_rate,
+    :open_count,
+    :open_rate,
+    :click_count,
+    :click_rate,
+    :spam_count,
+    :spam_rate,
+    :unsubscription_count,
+    :unsubscription_rate,
+    :sent_count,
+    keyword_init: true
+  )
+end

data/lib/mailtrap/marketing_stats_api.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'stats_query_params'
+require_relative 'marketing_stats'
+
+module Mailtrap
+  class MarketingStatsAPI
+    include BaseAPI
+    include StatsQueryParams
+
+    # @param client [Mailtrap::Client] The client instance
+    def initialize(client = Mailtrap::Client.new)
+      @client = client
+    end
+
+    # Get aggregated Email Marketing stats: campaigns and automations together, the same numbers
+    # as Email Marketing > Stats Overview in the app. Email API/SMTP traffic is reported by {StatsAPI}.
+    # @param start_date [String, Date, Time] Start of the period, inclusive (required)
+    # @param end_date [String, Date, Time] End of the period, inclusive (required)
+    # @param sending_domain_ids [Array<Integer>] Filter by sending domain IDs
+    # @param sources [Array<String>] Filter by source: +campaigns+ or +automations+;
+    #   omit it, or pass both, to include campaigns and automations together
+    # @param email_service_providers [Array<String>] Filter by recipient email service providers
+    # @return [MarketingStats] Aggregated Email Marketing stats
+    # @!macro api_errors
+    # @raise [ArgumentError] If a date is not a Date, Time, or String in +YYYY-MM-DD+ format
+    def get(start_date:, end_date:, sending_domain_ids: nil, sources: nil, email_service_providers: nil)
+      query_params = build_query_params(
+        start_date, end_date,
+        { sending_domain_ids:, sources:, email_service_providers: }
+      )
+      response = client.get(base_path, query_params)
+      build_entity(response[:data], MarketingStats)
+    end
+
+    private
+
+    def base_path
+      '/api/marketing/stats'
+    end
+  end
+end

data/lib/mailtrap/stats_api.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require 'date'
 require_relative 'base_api'
+require_relative 'stats_query_params'
 require_relative 'sending_stats'
 require_relative 'sending_stat_group'
 
 module Mailtrap
   class StatsAPI
     include BaseAPI
+    include StatsQueryParams
 
-    ARRAY_FILTERS = %i[sending_domain_ids sending_streams categories email_service_providers].freeze
     GROUP_KEYS = {
       'domains' => :sending_domain_id,
       'categories' => :category,
@@ -112,38 +112,6 @@ module Mailtrap
       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

data/lib/mailtrap/stats_query_params.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Mailtrap
+  # Query parameters of the sending stats and Email Marketing stats endpoints: the period as
+  # +YYYY-MM-DD+ dates and every array filter as a repeated +key[]+ parameter. A +nil+ or empty
+  # filter is left out.
+  module StatsQueryParams
+    private
+
+    def build_query_params(start_date, end_date, filters)
+      params = { start_date: normalize_date(start_date), end_date: normalize_date(end_date) }
+      filters.each { |filter_key, values| params["#{filter_key}[]"] = values unless Array(values).empty? }
+      params
+    end
+
+    def normalize_date(value)
+      case value
+      when Date, Time # DateTime is a Date, but its #iso8601 includes the time of day
+        return value.strftime('%F')
+      when String
+        return value if /\A\d{4}-\d{2}-\d{2}\z/.match?(value) && Date.valid_date?(*value.split('-').map(&:to_i))
+      end
+
+      raise ArgumentError, "Invalid date: #{value.inspect}. Expected a Date, Time, or String in YYYY-MM-DD format."
+    end
+  end
+end

data/lib/mailtrap/version.rb

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

data/lib/mailtrap.rb

@@ -21,6 +21,7 @@ require_relative 'mailtrap/contact_events_api'
 require_relative 'mailtrap/suppressions_api'
 require_relative 'mailtrap/tracking_opt_outs_api'
 require_relative 'mailtrap/email_campaigns_api'
+require_relative 'mailtrap/marketing_stats_api'
 require_relative 'mailtrap/sending_domains_api'
 require_relative 'mailtrap/company_info_api'
 require_relative 'mailtrap/email_logs_api'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.18.0
+  version: 2.19.0
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -106,6 +106,8 @@ files:
 - lib/mailtrap/mail.rb
 - lib/mailtrap/mail/base.rb
 - lib/mailtrap/mail/from_template.rb
+- lib/mailtrap/marketing_stats.rb
+- lib/mailtrap/marketing_stats_api.rb
 - lib/mailtrap/permission_resource.rb
 - lib/mailtrap/permissions_api.rb
 - lib/mailtrap/project.rb
@@ -119,6 +121,7 @@ files:
 - lib/mailtrap/sending_stat_group.rb
 - lib/mailtrap/sending_stats.rb
 - lib/mailtrap/stats_api.rb
+- lib/mailtrap/stats_query_params.rb
 - lib/mailtrap/sub_account.rb
 - lib/mailtrap/sub_accounts_api.rb
 - lib/mailtrap/suppression.rb