mailgun-ruby 1.3.6 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d95de7e9d0beb5c9abeafdef8f05c7413566102807dedc3d8aa47236eeecf100
-  data.tar.gz: f1678c985501ecc657c2163f55f1a8073bca3990a84894ed4b914886d9a0f5d2
+  metadata.gz: 0041dce1e0fc1dc9f5166d4095a8d39dadf26be5b5b7892f1b8005b60a471a1f
+  data.tar.gz: 4356cf2e9093a066e28ff7fab036af94294eb4515137d0f802f001093b2d477f
 SHA512:
-  metadata.gz: 46af44b97dd11918113681f366489b8640de80efa05e08dea0102f4e97635634d241739be47d63107342400af8712b079d8360326697e81a78ca94cb6526e42f
-  data.tar.gz: 9b72d7230d1c14f9f9515f9e740e7c002436675e14dda9302234ad263ff586cd3a7d1cd9759913a14e1a180f692b505a197308fa78299446906c57a9c007da55
+  metadata.gz: 3420a656e1d4ef615a665743190b593a46a5ea13f778bf65a2b1d32746a30fb2ed08adde9d6651aeaacfa7fc8e815cc0cf51a510fd7c2b83e8a20c8b3cb34391
+  data.tar.gz: 864f0bfc57d6e06112eb410870bd88d6a7aa81a1b8f71bbb88206a6b768fcc1346635d76c2ffa059469911baed7e911e4f96e3cb6793192794511719e31dba99

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.6] - 2025-05-30
+
+### Fixed
+
+- Fix Suppressions paging not working (https://github.com/mailgun/mailgun-ruby/pull/355)
+- CI improvements
+
 ## [1.3.5] - 2025-04-07
 
 ### Fixed

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.3.6'
+gem 'mailgun-ruby', '~>1.3.7'
 ```
 
 Usage
@@ -87,9 +87,9 @@ and replace `api-myapikey` and `mydomain.com` with your secret API key and domai
 
 To specify Mailgun options such as campaign or tags:
 ```ruby
-class UserMailer < ApplicationMailer
-  def welcome_email
-    mail(to: params[:to], subject: "Welcome!").tap do |message|
+class UserNotifier < ApplicationMailer
+  def welcome_email(current_user)
+    mail(to: current_user.email, subject: "Welcome!").tap do |message|
       message.mailgun_options = {
         "tag" => ["abtest-option-a", "beta-user"],
         "tracking-opens" => true,
@@ -193,6 +193,7 @@ This SDK includes the following components:
 - [Templates](docs/Templates.md)
 - [EmailValidation](docs/EmailValidation.md)
 - [Metrics](docs/Metrics.md)
+- [Logs](docs/Logs.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/Events.md

@@ -1,6 +1,8 @@
 Mailgun - Events
 ====================
 
+_WARNING: This API is deprecated in favor of our Logs API._
+
 This is the Mailgun Ruby *Events* utility.
 
 The below assumes you've already installed the Mailgun Ruby SDK in your project.

data/docs/Logs.md

@@ -0,0 +1,67 @@
+Mailgun - Logs
+====================
+
+This is the Mailgun Ruby *Logs* 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 logs which are available
+in your Control Panel. This data is also available via our analytics logs API endpoint.
+
+You can view additional samples in the [logs_spec.rb](/spec/integration/logs_spec.rb)
+or the Logs client API in [logs.rb](/lib/logs/logs.rb).
+
+Usage
+-----
+
+To get an instance of the Logs client:
+
+```ruby
+require 'mailgun'
+
+mg_client = Mailgun::Client.new('your-api-key', 'mailgun-api-host', 'v1')
+logs = Mailgun::Logs.new(mg_client)
+````
+---
+Get filtered logs for an account:
+```ruby
+options = {
+  {
+    start: 'Mon, 08 Jul 2024 00:00:00 -0000',
+    end: 'Fri, 12 Jul 2024 00:00:00 -0000',
+    filter: {
+      AND: [
+        {
+          attribute: 'domain',
+          comparator: '=',
+          values: [
+            {
+              label: 'example.com',
+              value: 'example.com'
+            }
+          ]
+        }
+      ]
+    },
+    include_subaccounts: true,
+    pagination: {
+      sort: 'timestamp:asc',
+      token: 'cjsijbijewbu78t678tVTYUYU76754fyuiksin865g',
+      limit: 50
+    }
+  }
+}
+
+logs.account_logs(options)
+```
+
+---
+
+More Documentation
+------------------
+See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Logs/)
+for more information

data/lib/mailgun/address.rb

@@ -4,8 +4,8 @@ module Mailgun
 
   # Mailgun::Address is a simple interface to the Email Validation API.
   class Address
-    def initialize
-      @client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v4')
+    def initialize(api_key = Mailgun.api_key, api_host = Mailgun.api_host)
+      @client = Mailgun::Client.new(api_key, api_host || 'api.mailgun.net', 'v4')
     end
 
     # Given an arbitrary address, validates it based on defined checks.

data/lib/mailgun/client.rb

@@ -4,7 +4,7 @@ require 'mailgun/exceptions/exceptions'
 
 module Mailgun
   # A Mailgun::Client object is used to communicate with the Mailgun API. It is a
-  # wrapper around RestClient so you don't have to worry about the HTTP aspect
+  # wrapper around Faraday so you don't have to worry about the HTTP aspect
   # of communicating with our API.
   #
   # See the Github documentation for full examples.
@@ -23,7 +23,7 @@ module Mailgun
 
       request_options = {
         url: endpoint,
-        proxy: Mailgun.proxy_url,
+        proxy: proxy_url,
         ssl: {verify: ssl},
         headers: {
                    'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}",

data/lib/mailgun/events/events.rb

@@ -76,6 +76,7 @@ module Mailgun
     #
     # Returns a Mailgun.Response object.
     def get_events(params = {}, paging = nil)
+      warn('WARN: This API is deprecated in favor of our Logs API')
       response = @client.get(construct_url(paging), params)
       extract_paging(response)
       response

data/lib/mailgun/lists/opt_in_handler.rb

@@ -1,5 +1,4 @@
 require 'uri'
-require 'base64'
 require 'openssl'
 
 module Mailgun
@@ -20,14 +19,14 @@ module Mailgun
     def self.generate_hash(mailing_list, secret_app_id, recipient_address)
       inner_payload = { 'l' => mailing_list, 'r' => recipient_address }
 
-      inner_payload_encoded = Base64.encode64(JSON.generate(inner_payload))
+      inner_payload_encoded = base64_encode(JSON.generate(inner_payload))
 
       sha1_digest = OpenSSL::Digest.new('sha1')
       digest = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, inner_payload_encoded)
 
       outer_payload = { 'h' => digest, 'p' => inner_payload_encoded }
 
-      outer_payload_encoded = Base64.encode64(JSON.generate(outer_payload))
+      outer_payload_encoded = base64_encode(JSON.generate(outer_payload))
 
       CGI.escape(outer_payload_encoded)
     end
@@ -38,12 +37,12 @@ module Mailgun
     # @param [Hash] unique_hash The hash from the user. Likely via link click.
     # @return [Hash or Boolean] A hash with 'recipient_address' and 'mailing_list', if validates. Otherwise, boolean false.
     def self.validate_hash(secret_app_id, unique_hash)
-      outer_payload = JSON.parse(Base64.decode64(CGI.unescape(unique_hash)))
+      outer_payload = JSON.parse(base64_decode(CGI.unescape(unique_hash)))
 
       sha1_digest = OpenSSL::Digest.new('sha1')
       generated_hash = OpenSSL::HMAC.hexdigest(sha1_digest, secret_app_id, outer_payload['p'])
 
-      inner_payload = JSON.parse(Base64.decode64(CGI.unescape(outer_payload['p'])))
+      inner_payload = JSON.parse(base64_decode(CGI.unescape(outer_payload['p'])))
 
       hash_provided = outer_payload['h']
 
@@ -53,6 +52,22 @@ module Mailgun
       false
     end
 
+    # Equivalent to Base64.encode64
+    def self.base64_encode(input)
+      [input].pack('m')
+    end
+
+    # Equivalent to Base64.decode64
+    def self.base64_decode(input)
+      # TODO: Condition can be droped if Ruby >= 2.4.0
+      if input.respond_to?(:unpack1)
+        input.unpack1('m')
+      else
+        input.unpack('m').first
+      end
+    end
+
+    private_class_method :base64_encode, :base64_decode
   end
 
 end

data/lib/mailgun/logs/logs.rb

@@ -0,0 +1,39 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+  # A Mailgun::Logs object is a simple interface to Mailgun Logs.
+  # Uses Mailgun
+  class Logs
+    # Public: creates a new Mailgun::Logs 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 logs
+    #
+    # options - [Hash] of
+    #     start - [String] The start date (default: 1 day before current time). Must be in RFC 2822 format.
+    #     end - [String] The end date (default: current time). Must be in RFC 2822 format.
+    #     events - [Array] The set of events to include.
+    #     metric_events - [Array] Optional set of analytics metric events. Will be converted into corresponding events.
+    #     filter - [Object]
+    #         AND: - [Array] of objects
+    #             attribute - [String]
+    #             comparator - [String]
+    #             values - [Array] of objects
+    #                 label - [String]
+    #                 value - [String]
+    #     include_subaccounts - [Boolean] Include logs from all subaccounts.
+    #     include_totals - [Boolean] Include total number of log entries.
+    #     pagination - [Object]
+    #         sort - [String] Colon-separated value indicating column name and sort direction e.g. 'timestamp:desc'.
+    #         token - [String] A token to the requested page.
+    #         limit - [Integer] The maximum number of items returned (100 max).
+    #
+    # Returns [Hash] Logs
+    def account_logs(options={})
+      @client.post('analytics/logs', options.to_json, { "Content-Type" => "application/json" }).to_h!
+    end
+  end
+end

data/lib/mailgun/version.rb

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

data/lib/mailgun.rb

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

data/spec/integration/logs_spec.rb

@@ -0,0 +1,103 @@
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { cassette_name: 'logs' }
+
+describe Mailgun::Logs, vcr: vcr_opts do
+  let(:logs) { Mailgun::Logs.new(Mailgun::Client.new(APIKEY, APIHOST, 'v1')) }
+
+  describe '#account_logs' do
+    let(:options) do
+      {
+        start: 'Wed, 25 Jun 2025 00:00:00 -0000',
+        end: 'Wed, 25 Jun 2025 23:00:00 -0000',
+        filter: {
+          AND: [
+            {
+              attribute: 'domain',
+              comparator: '!=',
+              values: [
+                {
+                  label: 'example.com',
+                  value: 'example.com'
+                }
+              ]
+            }
+          ]
+        },
+        include_subaccounts: true,
+        pagination: {
+          sort: 'timestamp:asc',
+          token: '123',
+          limit: 50
+        }
+      }
+    end
+
+    it 'responds with account logs' do
+      expect(logs.account_logs(options)).to eq(
+        {
+          "start" => "Wed, 25 Jun 2025 00:00:00 -0000",
+          "end" => "Wed, 25 Jun 2025 23:00:00 -0000",
+          "items" => [
+            {
+              "id" => "123",
+              "event" => "accepted",
+              "@timestamp" => "2025-06-25T17:19:51.166Z",
+              "account" => {
+                "id" => "123"
+              },
+              "method" => "HTTP",
+              "originating-ip" => "123.123.12.123",
+              "api-key-id" => "xxx",
+              "domain" => {
+                "name" => "example.mailgun.org"
+              },
+              "recipient" => "alex@example.com",
+              "recipient-domain" => "example.com",
+              "envelope" => {
+                "sender" => "example.mailgun.org",
+                "transport" => "smtp",
+                "targets" => "alex@example.com"
+              },
+              "storage" => {
+                "region" => "us-east4",
+                "env" => "production",
+                "key" => "xxx",
+                "url" => ["https://storage.api.mailgun.net/v3/domains/example.mailgun.org/messages/123"]
+              },
+              "log-level" => "info",
+              "user-variables" => "{}",
+              "message" => {
+                "headers" => {
+                  "to" => "alex@example.com",
+                  "message-id" => "123@example.mailgun.org",
+                  "from" => "bob@sending_domain.com+4",
+                  "subject" => "The Ruby SDK is awesome!"
+                },
+                "attachments" => [
+                  {
+                    "filename" => "image.jpg",
+                    "content-type" => "image/jpeg",
+                    "size" => 16712
+                  }
+                ],
+                "size" => 23476
+              },
+              "flags" => {
+                "is-authenticated" => true,
+                "is-system-test" => false,
+                "is-routed" => false,
+                "is-test-mode" => false,
+                "is-delayed-bounce" => false,
+                "is-callback" => false
+              }
+            }
+          ],
+          "pagination" => {},
+          "aggregates" => {}
+        }
+      )
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,5 +1,4 @@
 require 'rubygems'
-require 'base64'
 require 'bundler'
 require 'bundler/setup'
 Bundler.setup(:development)

data/vcr_cassettes/logs.yml

@@ -0,0 +1,53 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.mailgun.net/v1/analytics/logs
+    body:
+      encoding: UTF-8
+      string: '{"start":"Wed, 25 Jun 2025 00:00:00 -0000","end":"Wed, 25 Jun 2025
+        23:00:00 -0000","filter":{"AND":[{"attribute":"domain","comparator":"!=","values":[{"label":"example.com","value":"example.com"}]}]},"include_subaccounts":true,"pagination":{"sort":"timestamp:asc","limit":50}}'
+    headers:
+      User-Agent:
+      - mailgun-sdk-ruby/1.3.7
+      Accept:
+      - "*/*"
+      Content-Type:
+      - application/json
+      Authorization:
+      - Basic xxx
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Credentials:
+      - 'true'
+      Access-Control-Allow-Origin:
+      - "*"
+      Cache-Control:
+      - no-store
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Wed, 25 Jun 2025 17:47:38 GMT
+      Strict-Transport-Security:
+      - max-age=63072000; includeSubDomains
+      X-Mailgun-Key-Id:
+      - XXX
+      X-Xss-Protection:
+      - 1; mode=block
+      Transfer-Encoding:
+      - chunked
+    body:
+      encoding: UTF-8
+      string: '{"start":"Wed, 25 Jun 2025 00:00:00 -0000","end":"Wed, 25 Jun 2025
+        23:00:00 -0000","items":[{"id":"123","event":"accepted","@timestamp":"2025-06-25T17:19:51.166Z","account":{"id":"123"},"method":"HTTP","originating-ip":"123.123.12.123","api-key-id":"xxx","domain":{"name":"example.mailgun.org"},"recipient":"alex@example.com","recipient-domain":"example.com","envelope":{"sender":"example.mailgun.org","transport":"smtp","targets":"alex@example.com"},"storage":{"region":"us-east4","env":"production","key":"xxx","url":["https://storage.api.mailgun.net/v3/domains/example.mailgun.org/messages/123"]},"log-level":"info","user-variables":"{}","message":{"headers":{"to":"alex@example.com","message-id":"123@example.mailgun.org","from":"bob@sending_domain.com+4","subject":"The
+        Ruby SDK is awesome!"},"attachments":[{"filename":"image.jpg","content-type":"image/jpeg","size":16712}],"size":23476},"flags":{"is-authenticated":true,"is-system-test":false,"is-routed":false,"is-test-mode":false,"is-delayed-bounce":false,"is-callback":false}}],"pagination":{},"aggregates":{}}
+
+        '
+    http_version:
+  recorded_at: Wed, 25 Jun 2025 17:47:38 GMT
+recorded_with: VCR 3.0.3

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailgun-ruby
 version: !ruby/object:Gem::Version
-  version: 1.3.6
+  version: 1.3.7
 platform: ruby
 authors:
 - Mailgun
 - Travis Swientek
 bindir: bin
 cert_chain: []
-date: 2025-05-29 00:00:00.000000000 Z
+date: 2025-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -197,6 +197,7 @@ files:
 - docs/Domains.md
 - docs/EmailValidation.md
 - docs/Events.md
+- docs/Logs.md
 - docs/MessageBuilder.md
 - docs/Metrics.md
 - docs/OptInHandler.md
@@ -217,6 +218,7 @@ files:
 - lib/mailgun/events/events.rb
 - lib/mailgun/exceptions/exceptions.rb
 - lib/mailgun/lists/opt_in_handler.rb
+- lib/mailgun/logs/logs.rb
 - lib/mailgun/messages/batch_message.rb
 - lib/mailgun/messages/message_builder.rb
 - lib/mailgun/metrics/metrics.rb
@@ -242,6 +244,7 @@ files:
 - spec/integration/events_spec.rb
 - spec/integration/list_members_spec.rb
 - spec/integration/list_spec.rb
+- spec/integration/logs_spec.rb
 - spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt
@@ -279,6 +282,7 @@ files:
 - vcr_cassettes/exceptions-not-allowed.yml
 - vcr_cassettes/exceptions.yml
 - vcr_cassettes/list_members.yml
+- vcr_cassettes/logs.yml
 - vcr_cassettes/mailer_invalid_domain.yml
 - vcr_cassettes/mailing_list.todo.yml
 - vcr_cassettes/mailing_list.yml
@@ -325,6 +329,7 @@ test_files:
 - spec/integration/events_spec.rb
 - spec/integration/list_members_spec.rb
 - spec/integration/list_spec.rb
+- spec/integration/logs_spec.rb
 - spec/integration/mailer_spec.rb
 - spec/integration/mailgun_spec.rb
 - spec/integration/messages/sample_data/mime.txt