DE-1313: Add support for Metrics endpoint (#326)

Signed-off-by: Alex Lebedev <6421109+alex-leb@users.noreply.github.com>

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

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

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

lib/mailgun.rb

@@ -18,6 +18,7 @@
 require 'mailgun/templates/templates'
 require 'mailgun/subaccounts/subaccounts'
 require 'mailgun/tags/tags'
+require 'mailgun/metrics/metrics'
 
 # Module for interacting with the sweet Mailgun API.
 #

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

lib/mailgun/version.rb

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