mailgun-ruby 1.2.15 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88449bde0909456b09f66ea57e253fbfe06f2de6fddb2640f9b5571479d9cedc
-  data.tar.gz: 3ed8f2ace6300271251bedab59ffc118acd3fb570a7a361b5c26d6c2a98352e8
+  metadata.gz: f18ece3e95078672f58a188ff310d572559ac05aa442080a8a76ec357fa563b9
+  data.tar.gz: 30a957419c41fa13342db90ca3ee386d1c312da20daa41c06229801e6c07ec95
 SHA512:
-  metadata.gz: 2159184a986dae450bec7069c8420671a860c7e06abe9ab660cf3a9af594ce62e67428c85782a25c242e99fc2bb250e172caa0e616e296332bf7f0f9fe7f8dc1
-  data.tar.gz: 2cf4aa439edfaf850e0151b43edbce7722701db5ec55ab087dbaffed70a64a1f8d99975cda71bc1e303284b5f6ce6865706a1414299fe554bbfdbc6f7e77669e
+  metadata.gz: '0309b13c1dda7a95224776c9bb1e0a04a3bfef7945f9a92c24ea566742f183ff544294d9a8dd6af006856fa7c97d2175cf01fe84c72e85712c1da34ec08bc723'
+  data.tar.gz: 90db979ec789797886fa5210ea3b2ec9bac048dbb440facd9f356324093cc98ce657ecc589f719efe4b4c2b51251153071b936db0cd34877370debe02912b66b

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.16] - 2024-11-29
+
+### Added
+
+- Metrics API support (https://github.com/mailgun/mailgun-ruby/pull/326)
+
 ## [1.2.15] - 2024-02-13
 
 ### Fixed
@@ -19,7 +25,6 @@ All notable changes to this project will be documented in this file.
 - Additional Domain Endpoints (https://github.com/mailgun/mailgun-ruby/pull/314)
 - Webhooks Update Method (https://github.com/mailgun/mailgun-ruby/pull/305)
 - Add support for AMP HTML (https://github.com/mailgun/mailgun-ruby/pull/304)
-- Add support for AMP HTML (https://github.com/mailgun/mailgun-ruby/pull/304)
 
 ### Fixed
 
@@ -40,4 +45,4 @@ All notable changes to this project will be documented in this file.
 ### Fixed
 
 - transform_for_mailgun block iteration issue (https://github.com/mailgun/mailgun-ruby/pull/298).
-- Typos in several files (https://github.com/mailgun/mailgun-ruby/pull/297).
+- Typos in several files (https://github.com/mailgun/mailgun-ruby/pull/297).

data/Gemfile

@@ -3,4 +3,5 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mailgun.gemspec
 gemspec
 
+gem 'mime-types'
 gem 'json', '~> 2.1', platform: :mri_19

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.2.15'
+gem 'mailgun-ruby', '~>1.2.16'
 ```
 
 Usage
@@ -193,6 +193,7 @@ This SDK includes the following components:
 - [Suppressions](docs/Suppressions.md)
 - [Templates](docs/Templates.md)
 - [EmailValidation](docs/EmailValidation.md)
+- [Metrics](docs/Metrics.md)
 
 Message Builder allows you to quickly create the array of parameters, required
 to send a message, by calling a methods for each parameter.

data/docs/Metrics.md

@@ -0,0 +1,108 @@
+Mailgun - Metrics
+====================
+
+This is the Mailgun Ruby *Metrics* utilities.
+
+The below assumes you've already installed the Mailgun Ruby SDK in to your
+project. If not, go back to the master README for instructions. It currently supports
+all calls except credentials.
+
+---
+
+Mailgun collects many different events and generates event metrics which are available
+in your Control Panel. This data is also available via our analytics metrics API endpoint.
+
+You can view additional samples in the [metrics_spec.rb](/spec/integration/metrics_spec.rb)
+or the Metrics client API in [metrics.rb](/lib/metrics/metrics.rb).
+
+Usage
+-----
+
+To get an instance of the Metrics client:
+
+```ruby
+require 'mailgun'
+
+mg_client = Mailgun::Client.new('your-api-key', 'mailgun-api-host', 'v1')
+metrics = Mailgun::Metrics.new(mg_client)
+````
+---
+Get filtered metrics for an account:
+```ruby
+options = {
+  {
+    resolution: 'hour',
+    metrics: [
+      'accepted_count',
+      'delivered_count',
+      'clicked_rate',
+      'opened_rate'
+    ],
+    include_aggregates: true,
+    start: 'Tue, 26 Nov 2024 20:56:50 -0500',
+    duration: '1m',
+    filter: {
+      AND: [
+        {
+          attribute: 'domain',
+          comparator: '!=',
+          values: [
+            {
+              label: 'example.com',
+              value: 'example.com'
+            }
+          ]
+        }
+      ]
+    },
+    dimensions: ['time'],
+    end: 'Tue, 30 Nov 2024 20:56:50 -0500',
+    include_subaccounts: true
+  }
+}
+
+metrics.account_metrics(options)
+```
+---
+
+Get filtered usage metrics for an account:
+```ruby
+options = {
+  resolution: 'hour',
+  metrics: [
+    'accepted_count',
+    'delivered_count',
+    'clicked_rate',
+    'opened_rate'
+  ],
+  include_aggregates: true,
+  start: 'Tue, 26 Nov 2024 20:56:50 -0500',
+  duration: '1m',
+  filter: {
+    AND: [
+      {
+        attribute: 'domain',
+        comparator: '!=',
+        values: [
+          {
+            label: 'example.com',
+            value: 'example.com'
+          }
+        ]
+      }
+    ]
+  },
+  dimensions: ['time'],
+  end: 'Tue, 30 Nov 2024 20:56:50 -0500',
+  include_subaccounts: true
+}
+
+metrics.account_usage_metrics(options)
+```
+
+---
+
+More Documentation
+------------------
+See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Metrics/)
+for more information

data/docs/Webhooks.md

@@ -4,8 +4,7 @@ Mailgun - Webhooks
 This is the Mailgun Ruby *Webhook* utilities.
 
 The below assumes you've already installed the Mailgun Ruby SDK in to your
-project. If not, go back to the master README for instructions. It currently supports
-all calls except updating webhooks.
+project. If not, go back to the master README for instructions.
 
 Usage - Webhooks
 -----------------------
@@ -27,6 +26,9 @@ hook.create_all 'my.perfect.domain', 'https://the.webhook.url/'
 # Add a url for a specific webhook
 hook.create 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
 
+# Update the url for a specific webhook
+hook.update 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
+
 # Remove a url for a specific webhook
 hook.remove 'my.perfect.domain', 'deliver'
 

data/lib/mailgun/client.rb

@@ -19,16 +19,26 @@ module Mailgun
                    timeout = nil,
                    proxy_url = Mailgun.proxy_url)
 
-      rest_client_params = {
-        user: 'api',
-        password: api_key,
-        user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}"
+      endpoint = endpoint_generator(api_host, api_version, ssl)
+
+      request_options = {
+        url: endpoint,
+        proxy: Mailgun.proxy_url,
+        ssl: {verify: ssl},
+        headers: {
+                   'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}",
+                   'Accept' =>'*/*'
+                  }
       }
-      rest_client_params[:timeout] = timeout if timeout
+      request_options.merge!(request: {timeout: timeout}) if timeout
+
+      @http_client =  Faraday.new(request_options) do |conn|
+        conn.request :authorization, :basic, 'api', api_key
+        conn.request :url_encoded
+        conn.response :raise_error, include_request: true
+        conn.adapter Faraday.default_adapter
+      end
 
-      endpoint = endpoint_generator(api_host, api_version, ssl)
-      RestClient.proxy = proxy_url
-      @http_client = RestClient::Resource.new(endpoint, rest_client_params)
       @test_mode = test_mode
       @api_version = api_version
     end
@@ -49,17 +59,17 @@ module Mailgun
 
     # Change API key
     def set_api_key(api_key)
-      @http_client.options[:password] = api_key
+      @http_client.set_basic_auth('api', api_key)
     end
 
     # Add subaccount id to headers
     def set_subaccount(subaccount_id)
-      @http_client.options[:headers] = { SUBACCOUNT_HEADER => subaccount_id }
+      @http_client.headers = @http_client.headers.merge!({ SUBACCOUNT_HEADER => subaccount_id })
     end
 
     # Reset subaccount for primary usage
     def reset_subaccount
-      @http_client.options[:headers].delete(SUBACCOUNT_HEADER)
+      @http_client.headers.delete(SUBACCOUNT_HEADER)
     end
 
     # Client is in test mode?
@@ -95,7 +105,7 @@ module Mailgun
         return Response.from_hash(
           {
             :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
-            :code => 200,
+            :status => 200,
           }
         )
       end
@@ -130,7 +140,7 @@ module Mailgun
     # @param [Hash] headers Additional headers to pass to the resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def post(resource_path, data, headers = {})
-      response = @http_client[resource_path].post(data, headers)
+      response = @http_client.post(resource_path, data, headers)
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -138,21 +148,19 @@ module Mailgun
 
     # Generic Mailgun GET Handler
     #
-    # @param [String] resource_path This is the API resource you wish to interact
-    # with. Be sure to include your domain, where necessary.
-    # @param [Hash] params This should be a standard Hash
-    # containing required parameters for the requested resource.
-    # @param [String] accept Acceptable Content-Type of the response body.
-    # @return [Mailgun::Response] A Mailgun::Response object.
-    def get(resource_path, params = nil, accept = '*/*')
-      if params
-        response = @http_client[resource_path].get(params: params, accept: accept)
-      else
-        response = @http_client[resource_path].get(accept: accept)
-      end
+    # @param [String] resource_path The API resource path to request, including the domain if required.
+    # @param [Hash] params Optional request parameters, including query parameters and headers.
+    #   - `:headers` [Hash] (optional) Custom headers for the request.
+    # @param [String] accept The expected Content-Type of the response. Defaults to '*/*'.
+    # @return [Mailgun::Response] A response object containing the API response data.
+    # @raise [CommunicationError] If the request fails, raises a communication error.
+    def get(resource_path, params = {}, accept = '*/*')
+      headers = (params[:headers] || {}).merge(accept: accept)
+      response = @http_client.get(resource_path, params, headers)
+
       Response.new(response)
     rescue => err
-      raise communication_error err
+      raise communication_error(err)
     end
 
     # Generic Mailgun PUT Handler
@@ -163,7 +171,7 @@ module Mailgun
     # containing required parameters for the requested resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
     def put(resource_path, data)
-      response = @http_client[resource_path].put(data)
+      response = @http_client.put(resource_path, data)
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -176,9 +184,9 @@ module Mailgun
     # @return [Mailgun::Response] A Mailgun::Response object.
     def delete(resource_path, params = nil)
       if params
-        response = @http_client[resource_path].delete(params: params)
+        response = @http_client.delete(resource_path, params: params)
       else
-        response = @http_client[resource_path].delete
+        response = @http_client.delete(resource_path)
       end
       Response.new(response)
     rescue => err
@@ -227,7 +235,7 @@ module Mailgun
     # @param [StandardException] e upstream exception object
     def communication_error(e)
       if e.respond_to?(:response) && e.response
-        return case e.response.code
+        return case e.response_status
         when Unauthorized::CODE
           Unauthorized.new(e.message, e.response)
         when BadRequest::CODE

data/lib/mailgun/exceptions/exceptions.rb

@@ -29,10 +29,10 @@ module Mailgun
   # Public: Class for managing communications (eg http) response errors
   # Inherits from Mailgun::Error
   class CommunicationError < Error
-    # Public: gets HTTP status code
-    attr_reader :code
+    # Public: gets HTTP status status
+    attr_reader :status
 
-    # Public: fallback if there is no response code on the object
+    # Public: fallback if there is no response status on the object
     NOCODE = 000
     FORBIDDEN = 'Forbidden'
 
@@ -43,17 +43,17 @@ module Mailgun
     #
     def initialize(message = nil, response = nil)
       @response = response
-      @code = if response.nil?
+      @status = if response.nil?
                 NOCODE
               else
-                response.code
+                response.status
               end
 
       begin
         json = JSON.parse(response.body)
         api_message = json['message'] || json['Error'] || json['error']
       rescue JSON::ParserError
-        api_message = response.body
+        api_message = response.response_body
       rescue NoMethodError
         api_message = "Unknown API error"
       rescue
@@ -65,7 +65,7 @@ module Mailgun
 
       super(message, response)
     rescue NoMethodError, JSON::ParserError
-      @code = NOCODE
+      @status = NOCODE
       super(message, response)
     end
   end

data/lib/mailgun/metrics/metrics.rb

@@ -0,0 +1,61 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+  # A Mailgun::Metrics object is a simple interface to Mailgun Metrics.
+  # Uses Mailgun
+  class Metrics
+    # Public: creates a new Mailgun::Metrics instance.
+    # Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v1'))
+      @client = client
+    end
+
+    # Public: Post query to get account metrics
+    #
+    # options - [Hash] of
+    #     start - [String] A start date (default: 7 days before current time). Must be in RFC 2822 format.
+    #     end - [String] An end date (default: current time). Must be in RFC 2822 format.
+    #     resolution - [String] A resolution in the format of 'day' 'hour' 'month'. Default is day.
+    #     duration - [String] A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
+    #     dimensions - [Array] Attributes of the metric data such as 'subaccount'.
+    #     metrics - [Array] Name of the metrics to receive the stats for such as 'processed_count'
+    #     filter - [Object]
+    #         AND: - [Array] of objects
+    #             attribute - [String]
+    #             comparator - [String]
+    #             values - [Array] of objects
+    #                 label - [String]
+    #                 value - [String]
+    #     include_subaccounts - [Boolean] Include stats from all subaccounts.
+    #     include_aggregates - [Boolean] Include top-level aggregate metrics.
+    #
+    # Returns [Hash] Metrics
+    def account_metrics(options={})
+      @client.post('analytics/metrics', options.to_json, { "Content-Type" => "application/json" }).to_h!
+    end
+
+    # Public: Post query to get account usage metrics
+    #
+    # options - [Hash] of
+    #     start - [String] A start date (default: 7 days before current time). Must be in RFC 2822 format.
+    #     end - [String] An end date (default: current time). Must be in RFC 2822 format.
+    #     resolution - [String] A resolution in the format of 'day' 'hour' 'month'. Default is day.
+    #     duration - [String] A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
+    #     dimensions - [Array] Attributes of the metric data such as 'subaccount'.
+    #     metrics - [Array] Name of the metrics to receive the stats for such as 'processed_count'
+    #     filter - [Object]
+    #         AND: - [Array] of objects
+    #             attribute - [String]
+    #             comparator - [String]
+    #             values - [Array] of objects
+    #                 label - [String]
+    #                 value - [String]
+    #     include_subaccounts - [Boolean] Include stats from all subaccounts.
+    #     include_aggregates - [Boolean] Include top-level aggregate metrics.
+    #
+    # Returns [Hash] Metrics
+    def account_usage_metrics(options={})
+      @client.post('analytics/usage/metrics', options.to_json, { "Content-Type" => "application/json" }).to_h!
+    end
+  end
+end

data/lib/mailgun/response.rb

@@ -6,19 +6,20 @@ module Mailgun
   #
   # See the Github documentation for full examples.
   class Response
-    # All responses have a payload and a code corresponding to http, though
+    # All responses have a payload and a status corresponding to http, though
     #   slightly different
-    attr_accessor :body, :code
+    attr_accessor :body, :status, :code
 
-    ResponseHash = Struct.new(:body, :code)
+    ResponseHash = Struct.new(:body, :status)
     def self.from_hash(h)
       # Create a "fake" response object with the data passed from h
-      self.new ResponseHash.new(h[:body], h[:code])
+      self.new ResponseHash.new(h[:body], h[:status])
     end
 
     def initialize(response)
       @body = response.body
-      @code = response.code
+      @status = response.status
+      @code = response.status
     end
 
     # Return response as Ruby Hash
@@ -57,12 +58,12 @@ module Mailgun
     rescue => err
       raise ParseError.new(err), err
     end
-    
-    # Returns true if response code is 2xx
-    # 
-    # @return [Boolean] A boolean that binarizes the response code result.
+
+    # Returns true if response status is 2xx
+    #
+    # @return [Boolean] A boolean that binarizes the response status result.
     def success?
-      (200..299).include?(code)
+      (200..299).include?(status)
     end
   end
 end

data/lib/mailgun/version.rb

@@ -1,4 +1,4 @@
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.2.15'
+  VERSION = '1.3.0'
 end

data/lib/mailgun.rb

@@ -1,5 +1,5 @@
 require 'tempfile'
-require 'rest_client'
+require 'faraday'
 require 'yaml'
 require 'json'
 
@@ -18,6 +18,7 @@ require 'mailgun/webhooks/webhooks'
 require 'mailgun/templates/templates'
 require 'mailgun/subaccounts/subaccounts'
 require 'mailgun/tags/tags'
+require 'mailgun/metrics/metrics'
 
 # Module for interacting with the sweet Mailgun API.
 #

data/mailgun.gemspec

@@ -30,11 +30,12 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '>= 1.16.2'
   spec.add_development_dependency 'rspec', '~> 3.8.0'
   spec.add_development_dependency 'rake', '~> 12.3.2'
+  spec.add_development_dependency 'mime-types'
   spec.add_development_dependency 'webmock', '~> 3.7'
   spec.add_development_dependency 'pry', '~> 0.11.3'
   spec.add_development_dependency 'vcr', '~> 3.0.3'
   spec.add_development_dependency 'simplecov', '~> 0.16.1'
   spec.add_development_dependency 'rails'
-  spec.add_dependency 'rest-client', '>= 2.0.2'
+  spec.add_dependency 'faraday', "~> 2.1"
 
 end

data/spec/integration/mailgun_spec.rb

@@ -51,7 +51,7 @@ describe 'Client exceptions', vcr: vcr_opts do
           :text => 'INTEGRATION TESTING'
       })
     rescue Mailgun::Unauthorized => err
-      expect(err.message).to eq('401 Unauthorized - Invalid Domain or API key: Forbidden')
+      expect(err.message).to eq('the server responded with status 401 - Invalid Domain or API key')
     else
       fail
     end
@@ -75,7 +75,7 @@ describe 'Client exceptions', vcr: vcr_opts do
           :text => 'INTEGRATION TESTING'
       })
     rescue Mailgun::BadRequest => err
-      expect(err.message).to eq('400 Bad Request: to parameter is not a valid address. please check documentation')
+      expect(err.message).to eq('the server responded with status 400')
     else
       fail
     end
@@ -99,7 +99,7 @@ describe 'Client exceptions', vcr: vcr_opts do
           :text => 'INTEGRATION TESTING'
       })
     rescue Mailgun::CommunicationError => err
-      expect(err.message).to include('403 Forbidden')
+      expect(err.message).to include('403')
     else
       fail
     end
@@ -192,7 +192,7 @@ Testing some Mailgun awesomness!'
     expect(result.body).to include("message")
     expect(result.body).to include("id")
   end
-  
+
   it 'receives success response code' do
     @mg_obj.enable_test_mode!
 
@@ -205,7 +205,7 @@ Testing some Mailgun awesomness!'
 
     result = @mg_obj.send_message(@domain, data)
     result.to_h!
-    
+
     expect(result.success?).to be(true)
   end
 end

data/spec/integration/metrics_spec.rb

@@ -0,0 +1,218 @@
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { cassette_name: 'metrics' }
+
+describe Mailgun::Metrics, vcr: vcr_opts do
+  let(:metrics) { Mailgun::Metrics.new(Mailgun::Client.new(APIKEY, APIHOST, 'v1')) }
+
+  describe '#account_metrics' do
+    let(:options) do
+      {
+        resolution: 'hour',
+        metrics: [
+          'accepted_count',
+          'delivered_count',
+          'clicked_rate',
+          'opened_rate'
+        ],
+        include_aggregates: true,
+        start: 'Tue, 26 Nov 2024 20:56:50 -0500',
+        duration: '1m',
+        filter: {
+          AND: [
+            {
+              attribute: 'domain',
+              comparator: '!=',
+              values: [
+                {
+                  label: 'example.com',
+                  value: 'example.com'
+                }
+              ]
+            }
+          ]
+        },
+        dimensions: ['time'],
+        end: 'Tue, 30 Nov 2024 20:56:50 -0500',
+        include_subaccounts: true
+      }
+    end
+
+    it 'responds with account metrics' do
+      expect(metrics.account_metrics(options)).to eq(
+        {
+          "start" => "Fri, 01 Nov 2024 01:00:00 +0000",
+          "end" => "Sun, 01 Dec 2024 01:00:00 +0000",
+          "resolution" => "hour",
+          "duration" => "1m",
+          "dimensions" => ["time"],
+          "pagination" => {
+            "sort" => "", "skip" => 0, "limit" => 1500, "total" => 3
+          },
+          "items" => [{
+              "dimensions" => [{
+                "dimension" => "time",
+                "value" => "Wed, 27 Nov 2024 12:00:00 +0000",
+                "display_value" => "Wed, 27 Nov 2024 12:00:00 +0000"
+              }],
+              "metrics" => {
+                "accepted_count" => 1, "delivered_count" => 1, "opened_rate" => "0.0000", "clicked_rate" => "0.0000"
+              }
+            },
+            {
+              "dimensions" => [{
+                "dimension" => "time",
+                "value" => "Wed, 27 Nov 2024 13:00:00 +0000",
+                "display_value" => "Wed, 27 Nov 2024 13:00:00 +0000"
+              }],
+              "metrics" => {
+                "accepted_count" => 1, "delivered_count" => 1, "opened_rate" => "0.0000", "clicked_rate" => "0.0000"
+              }
+            },
+            {
+              "dimensions" => [{
+                "dimension" => "time",
+                "value" => "Thu, 28 Nov 2024 15:00:00 +0000",
+                "display_value" => "Thu, 28 Nov 2024 15:00:00 +0000"
+              }],
+              "metrics" => {
+                "accepted_count" => 1, "delivered_count" => 1, "opened_rate" => "0.0000", "clicked_rate" => "0.0000"
+              }
+            }
+          ],
+          "aggregates" => {
+            "metrics" => {
+              "accepted_count" => 3, "delivered_count" => 3, "opened_rate" => "0.0000", "clicked_rate" => "0.0000"
+            }
+          }
+        }
+      )
+    end
+  end
+
+  describe '#account_usage_metrics' do
+    let(:options) do
+      {
+        resolution: 'hour',
+        metrics: [
+          'email_preview_count',
+          'email_preview_failed_count',
+          'email_validation_bulk_count',
+          'email_validation_count',
+          'email_validation_list_count',
+          'email_validation_mailgun_count',
+          'email_validation_mailjet_count',
+          'email_validation_public_count',
+          'email_validation_single_count',
+          'email_validation_valid_count',
+          'link_validation_count',
+          'link_validation_failed_count',
+          'processed_count',
+          'seed_test_count'
+        ],
+        include_aggregates: true,
+        start: 'Tue, 26 Nov 2024 20:56:50 -0500',
+        duration: '1m',
+        filter: {
+          AND: [
+            {
+              attribute: 'subaccount',
+              comparator: '!=',
+              values: [
+                {
+                  label: '12345',
+                  value: '12345'
+                }
+              ]
+            }
+          ]
+        },
+        dimensions: ['time'],
+        end: 'Tue, 28 Nov 2024 20:56:50 -0500',
+        include_subaccounts: true
+      }
+    end
+
+    it 'responds with account usage metrics' do
+      expect(metrics.account_usage_metrics(options)).to eq(
+        {
+          "start" => "Tue, 29 Oct 2024 01:00:00 +0000",
+          "end" => "Fri, 29 Nov 2024 01:00:00 +0000",
+          "resolution" => "hour",
+          "duration" => "1m",
+          "dimensions" => ["time"],
+          "pagination" => {
+            "sort" => "", "skip" => 0, "limit" => 1500, "total" => 2
+          },
+          "items" => [{
+              "dimensions" => [{
+                "dimension" => "time",
+                "value" => "Wed, 27 Nov 2024 00:00:00 +0000",
+                "display_value" => "Wed, 27 Nov 2024 00:00:00 +0000"
+              }],
+              "metrics" => {
+                "processed_count" => 2,
+                "email_validation_count" => 0,
+                "email_validation_public_count" => 0,
+                "email_validation_valid_count" => 0,
+                "email_validation_single_count" => 0,
+                "email_validation_bulk_count" => 0,
+                "email_validation_list_count" => 0,
+                "email_validation_mailgun_count" => 0,
+                "email_validation_mailjet_count" => 0,
+                "email_preview_count" => 0,
+                "email_preview_failed_count" => 0,
+                "link_validation_count" => 0,
+                "link_validation_failed_count" => 0,
+                "seed_test_count" => 0
+              }
+            },
+            {
+              "dimensions" => [{
+                "dimension" => "time",
+                "value" => "Thu, 28 Nov 2024 00:00:00 +0000",
+                "display_value" => "Thu, 28 Nov 2024 00:00:00 +0000"
+              }],
+              "metrics" => {
+                "processed_count" => 1,
+                "email_validation_count" => 0,
+                "email_validation_public_count" => 0,
+                "email_validation_valid_count" => 0,
+                "email_validation_single_count" => 0,
+                "email_validation_bulk_count" => 0,
+                "email_validation_list_count" => 0,
+                "email_validation_mailgun_count" => 0,
+                "email_validation_mailjet_count" => 0,
+                "email_preview_count" => 0,
+                "email_preview_failed_count" => 0,
+                "link_validation_count" => 0,
+                "link_validation_failed_count" => 0,
+                "seed_test_count" => 0
+              }
+            }
+          ],
+          "aggregates" => {
+            "metrics" => {
+              "permanent_failed_count" => 0,
+              "processed_count" => 3,
+              "email_validation_count" => 0,
+              "email_validation_public_count" => 0,
+              "email_validation_valid_count" => 0,
+              "email_validation_single_count" => 0,
+              "email_validation_bulk_count" => 0,
+              "email_validation_list_count" => 0,
+              "email_validation_mailgun_count" => 0,
+              "email_validation_mailjet_count" => 0,
+              "email_preview_count" => 0,
+              "email_preview_failed_count" => 0,
+              "link_validation_count" => 0,
+              "link_validation_failed_count" => 0,
+              "seed_test_count" => 0
+            }
+          }
+        }
+      )
+    end
+  end
+end

data/spec/unit/connection/test_client.rb

@@ -99,7 +99,7 @@ module Mailgun
         return Response.from_hash({ body: JSON.generate({"message" => "Queued. Thank you.", "id" => id}) })
       end
       if resource_endpoint == "bounces"
-        return Response.from_hash({ body: JSON.generate({"total_count" => 1, "items" => {"created_at" => "Fri, 21 Oct 2011 11:02:55 GMT", "code" => 550, "address" => "baz@example.com", "error" => "Message was not accepted -- invalid mailbox. Local mailbox baz@example.com is unavailable: user not found"}}) })
+        return Response.from_hash({ body: JSON.generate({"total_count" => 1, "items" => {"created_at" => "Fri, 21 Oct 2011 11:02:55 GMT", "status" => 550, "address" => "baz@example.com", "error" => "Message was not accepted -- invalid mailbox. Local mailbox baz@example.com is unavailable: user not found"}}) })
       end
       if resource_endpoint == "lists"
         return Response.from_hash({ body: JSON.generate({"member" => {"vars" => {"age" => 26}, "name" => "Foo Bar", "subscribed" => false, "address" => "bar@example.com"}, "message" => "Mailing list member has been updated"}) })

data/spec/unit/exceptions/exceptions_spec.rb

@@ -5,13 +5,13 @@ RSpec.describe Mailgun::CommunicationError do
     context "when the Response body doesn't have a `message` property" do
       it "doesn't raise an error" do
         expect do
-          described_class.new('Boom!', Mailgun::Response.from_hash({ code: 401, body: '{}' }))
+          described_class.new('Boom!', Mailgun::Response.from_hash({ status: 401, body: '{}' }))
         end.not_to raise_error
       end
 
       context "when the Response body has an `Error` property" do
         it "uses the `Error` property as the API message" do
-          subject = described_class.new('Boom!', Mailgun::Response.from_hash({ code: 401, body: '{"Error":"unauthorized"}' }))
+          subject = described_class.new('Boom!', Mailgun::Response.from_hash({ status: 401, body: '{"Error":"unauthorized"}' }))
 
           expect(subject.message).to eq("Boom!: unauthorized")
         end
@@ -19,7 +19,7 @@ RSpec.describe Mailgun::CommunicationError do
 
       context "when the Response body has an `error` property" do
         it "uses the `Error` property as the API message" do
-          subject = described_class.new('Boom!', Mailgun::Response.from_hash({ code: 401, body: '{"error":"not found"}' }))
+          subject = described_class.new('Boom!', Mailgun::Response.from_hash({ status: 401, body: '{"error":"not found"}' }))
 
           expect(subject.message).to eq("Boom!: not found")
         end

data/vcr_cassettes/metrics.yml

@@ -0,0 +1,116 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.mailgun.net/v1/analytics/metrics
+    body:
+      encoding: UTF-8
+      string: '{"resolution":"hour","metrics":["accepted_count","delivered_count","clicked_rate","opened_rate"],"include_aggregates":true,"start":"Tue,
+        26 Nov 2024 20:56:50 -0500","duration":"1m","filter":{"AND":[{"attribute":"domain","comparator":"!=","values":[{"label":"example.com","value":"example.com"}]}]},"dimensions":["time"],"end":"Tue,
+        30 Nov 2024 20:56:50 -0500","include_subaccounts":true}'
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin23 x86_64) ruby/3.1.4p223
+      Content-Type:
+      - application/json
+      Content-Length:
+      - '387'
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic xxx
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Length:
+      - '1006'
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Thu, 28 Nov 2024 18:20:22 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - c02fd0ba-d8dbad66
+      X-Xss-Protection:
+      - 1; mode=block
+    body:
+      encoding: UTF-8
+      string: '{"start":"Fri, 01 Nov 2024 01:00:00 +0000","end":"Sun, 01 Dec 2024
+        01:00:00 +0000","resolution":"hour","duration":"1m","dimensions":["time"],"pagination":{"sort":"","skip":0,"limit":1500,"total":3},"items":[{"dimensions":[{"dimension":"time","value":"Wed,
+        27 Nov 2024 12:00:00 +0000","display_value":"Wed, 27 Nov 2024 12:00:00 +0000"}],"metrics":{"accepted_count":1,"delivered_count":1,"opened_rate":"0.0000","clicked_rate":"0.0000"}},{"dimensions":[{"dimension":"time","value":"Wed,
+        27 Nov 2024 13:00:00 +0000","display_value":"Wed, 27 Nov 2024 13:00:00 +0000"}],"metrics":{"accepted_count":1,"delivered_count":1,"opened_rate":"0.0000","clicked_rate":"0.0000"}},{"dimensions":[{"dimension":"time","value":"Thu,
+        28 Nov 2024 15:00:00 +0000","display_value":"Thu, 28 Nov 2024 15:00:00 +0000"}],"metrics":{"accepted_count":1,"delivered_count":1,"opened_rate":"0.0000","clicked_rate":"0.0000"}}],"aggregates":{"metrics":{"accepted_count":3,"delivered_count":3,"opened_rate":"0.0000","clicked_rate":"0.0000"}}}
+
+        '
+    http_version:
+  recorded_at: Thu, 28 Nov 2024 18:20:22 GMT
+- request:
+    method: post
+    uri: https://api.mailgun.net/v1/analytics/usage/metrics
+    body:
+      encoding: UTF-8
+      string: '{"resolution":"hour","metrics":["email_preview_count","email_preview_failed_count","email_validation_bulk_count","email_validation_count","email_validation_list_count","email_validation_mailgun_count","email_validation_mailjet_count","email_validation_public_count","email_validation_single_count","email_validation_valid_count","link_validation_count","link_validation_failed_count","processed_count","seed_test_count"],"include_aggregates":true,"start":"Tue,
+        26 Nov 2024 20:56:50 -0500","duration":"1m","filter":{"AND":[{"attribute":"subaccount","comparator":"!=","values":[{"label":"12345","value":"12345"}]}]},"dimensions":["time"],"end":"Tue,
+        28 Nov 2024 20:56:50 -0500","include_subaccounts":true}'
+    headers:
+      Accept:
+      - "*/*"
+      User-Agent:
+      - rest-client/2.1.0 (darwin23 x86_64) ruby/3.1.4p223
+      Content-Type:
+      - application/json
+      Content-Length:
+      - '703'
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Host:
+      - api.mailgun.net
+      Authorization:
+      - Basic xxx
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Length:
+      - '1795'
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Thu, 28 Nov 2024 18:20:23 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - c02fd0ba-d8dbad66
+      X-Xss-Protection:
+      - 1; mode=block
+    body:
+      encoding: UTF-8
+      string: '{"start":"Tue, 29 Oct 2024 01:00:00 +0000","end":"Fri, 29 Nov 2024
+        01:00:00 +0000","resolution":"hour","duration":"1m","dimensions":["time"],"pagination":{"sort":"","skip":0,"limit":1500,"total":2},"items":[{"dimensions":[{"dimension":"time","value":"Wed,
+        27 Nov 2024 00:00:00 +0000","display_value":"Wed, 27 Nov 2024 00:00:00 +0000"}],"metrics":{"processed_count":2,"email_validation_count":0,"email_validation_public_count":0,"email_validation_valid_count":0,"email_validation_single_count":0,"email_validation_bulk_count":0,"email_validation_list_count":0,"email_validation_mailgun_count":0,"email_validation_mailjet_count":0,"email_preview_count":0,"email_preview_failed_count":0,"link_validation_count":0,"link_validation_failed_count":0,"seed_test_count":0}},{"dimensions":[{"dimension":"time","value":"Thu,
+        28 Nov 2024 00:00:00 +0000","display_value":"Thu, 28 Nov 2024 00:00:00 +0000"}],"metrics":{"processed_count":1,"email_validation_count":0,"email_validation_public_count":0,"email_validation_valid_count":0,"email_validation_single_count":0,"email_validation_bulk_count":0,"email_validation_list_count":0,"email_validation_mailgun_count":0,"email_validation_mailjet_count":0,"email_preview_count":0,"email_preview_failed_count":0,"link_validation_count":0,"link_validation_failed_count":0,"seed_test_count":0}}],"aggregates":{"metrics":{"permanent_failed_count":0,"processed_count":3,"email_validation_count":0,"email_validation_public_count":0,"email_validation_valid_count":0,"email_validation_single_count":0,"email_validation_bulk_count":0,"email_validation_list_count":0,"email_validation_mailgun_count":0,"email_validation_mailjet_count":0,"email_preview_count":0,"email_preview_failed_count":0,"link_validation_count":0,"link_validation_failed_count":0,"seed_test_count":0}}}
+
+        '
+    http_version:
+  recorded_at: Thu, 28 Nov 2024 18:20:23 GMT
+recorded_with: VCR 3.0.3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailgun-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.15
+  version: 1.3.0
 platform: ruby
 authors:
 - Mailgun
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2025-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 12.3.2
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -124,19 +138,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: '2.1'
 description: Mailgun's Official Ruby SDK for interacting with the Mailgun API.
 email: support@mailgunhq.com
 executables: []
@@ -158,15 +172,16 @@ files:
 - docs/Events.md
 - docs/MessageBuilder.md
 - docs/Messages.md
+- docs/Metrics.md
 - docs/OptInHandler.md
 - docs/Snippets.md
 - docs/Subaccounts.md
 - docs/Suppressions.md
+- docs/Templates.md
 - docs/Webhooks.md
 - docs/railgun/EmailValidation.md
 - docs/railgun/Overview.md
 - docs/railgun/Parameters.md
-- docs/railgun/Templates.md
 - lib/mailgun-ruby.rb
 - lib/mailgun.rb
 - lib/mailgun/address.rb
@@ -178,6 +193,7 @@ files:
 - lib/mailgun/lists/opt_in_handler.rb
 - lib/mailgun/messages/batch_message.rb
 - lib/mailgun/messages/message_builder.rb
+- lib/mailgun/metrics/metrics.rb
 - lib/mailgun/response.rb
 - lib/mailgun/subaccounts/subaccounts.rb
 - lib/mailgun/suppressions.rb
@@ -203,6 +219,7 @@ files:
 - spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt
+- spec/integration/metrics_spec.rb
 - spec/integration/routes_spec.rb
 - spec/integration/stats_spec.rb
 - spec/integration/subaccounts_spec.rb
@@ -240,6 +257,7 @@ files:
 - vcr_cassettes/mailing_list.todo.yml
 - vcr_cassettes/mailing_list.yml
 - vcr_cassettes/message_deliver.yml
+- vcr_cassettes/metrics.yml
 - vcr_cassettes/routes.yml
 - vcr_cassettes/send_message.yml
 - vcr_cassettes/stats.yml
@@ -270,7 +288,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Mailgun's Official Ruby SDK
@@ -286,6 +304,7 @@ test_files:
 - spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt
+- spec/integration/metrics_spec.rb
 - spec/integration/routes_spec.rb
 - spec/integration/stats_spec.rb
 - spec/integration/subaccounts_spec.rb