mailgun-ruby 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56b457f9a512474de60aebfe220b4cb31bcfcfcc032972ce2c5a1aa0ad1322c2
-  data.tar.gz: 916852ea7483fe046b0d4c3c7883c79013b4378af43b2e6e978bf30f4dc9ef16
+  metadata.gz: 45aed85ba39b57f41a049e86f7e4aa86e04092c2fc04c86f4a948857cea182c1
+  data.tar.gz: 4588e70de8bf2836028858adc294e1c1f1b5a8d07de6623a14a1c9797049eecd
 SHA512:
-  metadata.gz: 7d43f29a5a245d06253ae97e44830c9768f494597506ce6ff4e87f28cc9071f12a959d0d3102f2d6f85140e5f373c2eefdd491064f804c12669618feef929594
-  data.tar.gz: 3bbd64c03a2bad22f6d0853607e3bc97358ef7c55c35b2e0420c000fe7166422319c4a0f6bc80ddec2c6ad8aa99ba7a0bb5b6cd54e023de3a0491a0774e36143
+  metadata.gz: 346f281a71259601f0215f33a2e7e65d2c76f5f90601522ecf06ff5f9c8c25daff473b1d8a8fc6a71474fdf6ac37c8c89c815831c74b9d1e09238392be139db7
+  data.tar.gz: 3e00ab15f716a2381735b12a792c6ddc333d32f1574c3d7b50640e293ca4c1f5a60b796c241d3e7c1447cb7b455a162a179c4167d8020bec11f21b6fa03920f1

data/.github/workflows/ci.yml

@@ -11,14 +11,13 @@ permissions:
 
 jobs:
   test:
-
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: [ '2.6', '2.7', '3.0', '3.1', '3.4' ]
+        ruby-version: [ '3.0', '3.1', '3.2', '3.3', '3.4', '4.0' ]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/Gemfile

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in mailgun.gemspec
 gemspec
 
-gem 'mini_mime'
 gem 'json', '~> 2.1', platform: :mri_19
+gem 'mini_mime'

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.4.0'
+gem 'mailgun-ruby', '~>1.4.2'
 ```
 
 Usage

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rake'
 require 'rspec/core/rake_task'
@@ -9,7 +11,7 @@ end
 
 desc 'Run unit specs'
 RSpec::Core::RakeTask.new('spec:unit') do |t|
-  t.rspec_opts = %w(--colour --format documentation)
+  t.rspec_opts = %w[--colour --format documentation]
   t.pattern = 'spec/unit/*_spec.rb', 'spec/unit/*/*_spec.rb'
 end
 
@@ -17,13 +19,13 @@ desc 'Run integration specs'
 # Before running integration tests, you need to specify
 # a valid API KEY in the spec/spec_helper.rb file.
 RSpec::Core::RakeTask.new('spec:integration') do |t|
-  t.rspec_opts = %w(--colour --format documentation)
+  t.rspec_opts = %w[--colour --format documentation]
   t.pattern = 'spec/integration/*_spec.rb'
 end
 
 desc 'Run all tests'
 RSpec::Core::RakeTask.new('spec:all') do |t|
-  t.rspec_opts = %w(--colour --format documentation)
+  t.rspec_opts = %w[--colour --format documentation]
   t.pattern = 'spec/**/*_spec.rb'
 end
 

data/docs/AnalyticsTags.md

@@ -0,0 +1,63 @@
+Mailgun - Analytics Tags
+====================
+
+This is the Mailgun Ruby *Analytics Tags* 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 allows you to tag your email with unique identifiers. Tags are visible via our analytics tags API endpoint.
+
+You can view additional samples in the [analytics_tags_spec.rb](/spec/integration/analytics_tags_spec.rb)
+or the Analytics Tags client API in [analytics_tags.rb](/lib/mailgun/tags/analytics_tags.rb).
+
+Usage
+-----
+
+To get an instance of the Analytics Tags client:
+
+```ruby
+require 'mailgun'
+
+mg_client = Mailgun::Client.new('your-api-key', 'mailgun-api-host', 'v1')
+tags = Mailgun::AnalyticsTags.new(mg_client)
+````
+---
+Update account tag:
+```ruby
+tags.update('name-of-tag-to-update', 'updated tag description')
+```
+---
+
+Post query to list account tags or search for single tag:
+```ruby
+options = {
+  pagination: {
+    sort: 'lastseen:desc',
+    limit: 10
+  },
+  include_subaccounts: true
+}
+
+tags.list(options)
+```
+
+Delete account tag:
+```ruby
+tags.remove('name-of-tag-to-remove')
+```
+
+Get account tag limit information:
+```ruby
+tags.limits
+```
+
+---
+
+More Documentation
+------------------
+See the official [Mailgun Tags New Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/tags-new)
+for more information

data/docs/Domains.md

@@ -9,49 +9,102 @@ all calls except credentials.
 
 Usage - Domains
 -----------------------
-
+First, instantiate the Mailgun Client with your API key
 ```ruby
-# First, instantiate the Mailgun Client with your API key
 mg_client = Mailgun::Client.new('your-api-key')
 domainer = Mailgun::Domains.new(mg_client)
+```
+
+Core Domain methods:
 
+```ruby
 # Get a list of current domains.
 domainer.list
 
-# View details of a domain
-domainer.info 'my.perfect.domain'
-
 # Add a new domain
 domainer.create 'my.new.moreness'
 # or with options
 domainer.create 'my.new.moreness', { some: 'options' }
 
-# Remove a domain
-domainer.remove 'this.one.is.not.needed.'
+# View details of a domain
+domainer.get 'my.perfect.domain'
 
 # Update a domain
 domainer.update 'my.new.moreness', { some: 'options' }
+
+# Verify a domain
+domainer.verify 'my.perfect.domain'
+
+# Remove a domain
+domainer.remove 'this.one.is.not.needed.'
+
+
 ```
 
-Suppressions for a Domain
--------------------------
+Domain Keys methods:
+
+```ruby
+# List keys for all domains
+domainer.list_domain_keys { some: 'options' }
+
+# Create a domain key
+domainer.create_domain_key { some: 'options' }
+
+# Delete a domain key
+domainer.delete_domain_key { some: 'options' }
+
+# Activate a domain key
+domainer.activate_domain_key 'my.perfect.domain', 'selector'
+
+# List domain keys
+domainer.get_domain_keys 'my.perfect.domain'
+
+# Deactivate a domain key
+domainer.deactivate_domain_key 'my.perfect.domain', 'selector'
 
-You can manage domain suppressions (bounces, unsubscribes, complaints) using the
-[`Mailgun::Suppressions`](/docs/Suppressions.md) client:
+# Update DKIM authority
+domainer.update_domain_dkim_authority 'my.perfect.domain', { some: 'options' }
+
+# Update a DKIM selector
+domainer.update_domain_dkim_selector 'my.perfect.domain', { some: 'options' }
+```
+
+Domain Tracking methods:
 
 ```ruby
-# Instantiate the Mailgun Client with your API key
-mg_client = Mailgun::Client.new('your-api-key')
-supp_client = mg_client.suppressions('example.org')
+# Get tracking settings
+domainer.get_domain_tracking_settings 'my.perfect.domain'
 
-# ...
+# Update click tracking settings
+domainer.update_domain_tracking_click_settings 'my.perfect.domain', { some: 'options' }
+
+# Update open tracking settings
+domainer.update_domain_tracking_open_settings 'my.perfect.domain', { some: 'options' }
+
+# Update unsubscribe tracking settings
+domainer.update_domain_tracking_unsubscribe_settings  'my.perfect.domain', { some: 'options' }
+
+# Tracking Certificate: Get certificate and status
+domainer.get_domain_tracking_certificate 'my.perfect.domain'
+
+# Tracking Certificate: Regenerate expired certificate
+domainer.regenerate_domain_tracking_certificate 'my.perfect.domain', { some: 'options' }
+
+# Tracking Certificate: Generate
+domainer.generate_domain_tracking_certificate 'my.perfect.domain', { some: 'options' }
 ```
 
-See the [Suppressions](/docs/Suppressions.md) for usage samples and
-[suppressions.rb](/lib/mailgun/suppressions.rb) for suppressions client API.
+DKIM Security methods:
+
+```ruby
+# Update Automatic Sender Security DKIM key rotation for a domain
+domainer.dkim_rotation 'my.perfect.domain', true, { some: 'options' }
 
+# Rotate Automatic Sender Security DKIM key for a domain
+domainer.dkim_rotate 'my.perfect.domain'
+```
 
 More Documentation
 ------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/en/latest/api-domains.html)
+See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains)
 for more information

data/docs/MessageBuilder.md

@@ -50,7 +50,7 @@ mb_obj.message_id("<20141014000000.11111.11111@example.com>")
 mb_obj.message_id(nil)
 mb_obj.message_id('')
 
-# Set the Message-tags at most 3.
+# Set the Message-tags at most 10.
 mb_obj.add_tag("You can track mails as tag-units!")
 
 # Campaigns and headers.

data/lib/mailgun/address.rb

@@ -1,7 +1,6 @@
-require 'mailgun/exceptions/exceptions'
+# frozen_string_literal: true
 
 module Mailgun
-
   # Mailgun::Address is a simple interface to the Email Validation API.
   class Address
     def initialize(api_key = Mailgun.api_key, api_host = Mailgun.api_host)
@@ -12,12 +11,11 @@ module Mailgun
     #
     # @param [String] address Email address to validate (max 512 chars.)
     def validate(address, mailbox_verification = false)
-      params = {address:  address}
+      params = { address: address }
       params[:mailbox_verification] = true if mailbox_verification
 
-      res = @client.get "address/validate", params
-      return res.to_h!
+      res = @client.get 'address/validate', params
+      res.to_h!
     end
   end
-
 end

data/lib/mailgun/chains.rb

@@ -1,8 +1,8 @@
-module Mailgun
+# frozen_string_literal: true
 
+module Mailgun
   # Public constants used throughout
   class Chains
-
     # maximum campaign ids per message
     MAX_CAMPAIGN_IDS = 3
 
@@ -11,6 +11,5 @@ module Mailgun
 
     # maximum recipients per message or batch
     MAX_RECIPIENTS = 1000
-
   end
 end

data/lib/mailgun/client.rb

@@ -1,6 +1,4 @@
-require 'mailgun/chains'
-require 'mailgun/suppressions'
-require 'mailgun/exceptions/exceptions'
+# frozen_string_literal: true
 
 module Mailgun
   # A Mailgun::Client object is used to communicate with the Mailgun API. It is a
@@ -9,37 +7,29 @@ module Mailgun
   #
   # See the Github documentation for full examples.
   class Client
-    SUBACCOUNT_HEADER = 'X-Mailgun-On-Behalf-Of'.freeze
+    SUBACCOUNT_HEADER = 'X-Mailgun-On-Behalf-Of'
 
     def initialize(api_key = Mailgun.api_key,
                    api_host = Mailgun.api_host || 'api.mailgun.net',
-                   api_version = Mailgun.api_version  || 'v3',
+                   api_version = Mailgun.api_version || 'v3',
                    ssl = true,
-                   test_mode = false,
+                   test_mode = !Mailgun.test_mode.nil?,
                    timeout = nil,
                    proxy_url = Mailgun.proxy_url)
-
       endpoint = endpoint_generator(api_host, api_version, ssl)
 
       request_options = {
         url: endpoint,
         proxy: proxy_url,
-        ssl: {verify: ssl},
+        ssl: { verify: ssl },
         headers: {
-                   'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}",
-                   'Accept' =>'*/*'
-                  }
+          'User-Agent' => "mailgun-sdk-ruby/#{Mailgun::VERSION}",
+          'Accept' => '*/*'
+        }
       }
-      request_options.merge!(request: {timeout: timeout}) if timeout
+      request_options.merge!(request: { timeout: timeout }) if timeout
 
-      @http_client =  Faraday.new(request_options) do |conn|
-        conn.request :multipart
-        conn.request :authorization, :basic, 'api', api_key
-        conn.request :url_encoded
-        conn.response :raise_error, include_request: true
-        conn.adapter Faraday.default_adapter
-        conn.options.params_encoder = Faraday::FlatParamsEncoder
-      end
+      @http_client = build_http_client(api_key, request_options)
 
       @test_mode = test_mode
       @api_version = api_version
@@ -66,7 +56,7 @@ module Mailgun
 
     # Add subaccount id to headers
     def set_subaccount(subaccount_id)
-      @http_client.headers = @http_client.headers.merge!({ SUBACCOUNT_HEADER => subaccount_id })
+      @http_client.headers.merge!({ SUBACCOUNT_HEADER => subaccount_id })
     end
 
     # Reset subaccount for primary usage
@@ -82,9 +72,7 @@ module Mailgun
     end
 
     # @return [String] client api version
-    def api_version
-      @api_version
-    end
+    attr_reader :api_version
 
     # Provides a store of all the emails sent in test mode so you can check them.
     #
@@ -102,12 +90,12 @@ module Mailgun
     def send_message(working_domain, data)
       perform_data_validation(working_domain, data)
 
-      if test_mode? then
+      if test_mode?
         Mailgun::Client.deliveries << data.dup
         return Response.from_hash(
           {
-            :body => "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
-            :status => 200,
+            body: "{\"id\": \"test-mode-mail-#{SecureRandom.uuid}@localhost\", \"message\": \"Queued. Thank you.\"}",
+            status: 200
           }
         )
       end
@@ -117,7 +105,7 @@ module Mailgun
         # Remove nil values from the data hash
         # Submitting nils to the API will likely cause an error.
         #  See also: https://github.com/mailgun/mailgun-ruby/issues/32
-        data = data.select { |k, v| v != nil }
+        data = data.reject { |_k, v| v.nil? }
 
         if data.key?(:message)
           if data[:message].is_a?(String)
@@ -130,7 +118,7 @@ module Mailgun
       when MessageBuilder
         post("#{working_domain}/messages", data.message)
       else
-        fail ParameterError.new('Unknown data type for data parameter.', data)
+        raise ParameterError.new('Unknown data type for data parameter.', data)
       end
     end
 
@@ -145,8 +133,8 @@ module Mailgun
     def post(resource_path, data, headers = {})
       response = @http_client.post(resource_path, data, headers)
       Response.new(response)
-    rescue => err
-      raise communication_error err
+    rescue StandardError => e
+      raise communication_error e
     end
 
     # Generic Mailgun GET Handler
@@ -162,8 +150,8 @@ module Mailgun
       response = @http_client.get(resource_path, params, headers)
 
       Response.new(response)
-    rescue => err
-      raise communication_error(err)
+    rescue StandardError => e
+      raise communication_error(e)
     end
 
     # Generic Mailgun PUT Handler
@@ -173,11 +161,11 @@ module Mailgun
     # @param [Hash] data This should be a standard Hash
     # containing required parameters for the requested resource.
     # @return [Mailgun::Response] A Mailgun::Response object.
-    def put(resource_path, data)
-      response = @http_client.put(resource_path, data)
+    def put(resource_path, data, headers = {})
+      response = @http_client.put(resource_path, data, headers)
       Response.new(response)
-    rescue => err
-      raise communication_error err
+    rescue StandardError => e
+      raise communication_error e
     end
 
     # Generic Mailgun DELETE Handler
@@ -185,15 +173,22 @@ module Mailgun
     # @param [String] resource_path This is the API resource you wish to interact
     # with. Be sure to include your domain, where necessary.
     # @return [Mailgun::Response] A Mailgun::Response object.
-    def delete(resource_path, params = nil)
-      if params
-        response = @http_client.delete(resource_path, params: params)
-      else
-        response = @http_client.delete(resource_path)
-      end
+    def delete(resource_path, params = nil, body_params = false)
+      response =
+        if params
+          if body_params
+            @http_client.delete(resource_path) do |request|
+              request.body = params.to_json
+            end
+          else
+            @http_client.delete(resource_path, params: params)
+          end
+        else
+          @http_client.delete(resource_path)
+        end
       Response.new(response)
-    rescue => err
-      raise communication_error err
+    rescue StandardError => e
+      raise communication_error e
     end
 
     # Constructs a Suppressions client for the given domain.
@@ -225,7 +220,7 @@ module Mailgun
     # @param [Boolean] ssl True, SSL. False, No SSL.
     # @return [string] concatenated URL string
     def endpoint_generator(api_host, api_version, ssl)
-      ssl ? scheme = 'https' : scheme = 'http'
+      scheme = ssl ? 'https' : 'http'
       if api_version
         "#{scheme}://#{api_host}/#{api_version}"
       else
@@ -239,28 +234,44 @@ module Mailgun
     def communication_error(e)
       if e.respond_to?(:response) && e.response
         return case e.response_status
-        when Unauthorized::CODE
-          Unauthorized.new(e.message, e.response)
-        when BadRequest::CODE
-          BadRequest.new(e.message, e.response)
-        else
-          CommunicationError.new(e.message, e.response)
-        end
+               when Unauthorized::CODE
+                 Unauthorized.new(e.message, e.response)
+               when BadRequest::CODE
+                 BadRequest.new(e.message, e.response)
+               else
+                 CommunicationError.new(e.message, e.response)
+               end
       end
       CommunicationError.new(e.message)
     end
 
     def perform_data_validation(working_domain, data)
       message = data.respond_to?(:message) ? data.message : data
-      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
-      fail ParameterError.new(
-        'Missing `to` recipient, message should contain at least 1 recipient',
-        working_domain
-      ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
-      fail ParameterError.new(
+      raise ParameterError.new('Missing working domain', working_domain) unless working_domain
+
+      if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
+        raise ParameterError.new(
+          'Missing `to` recipient, message should contain at least 1 recipient',
+          working_domain
+        )
+      end
+      return unless message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+
+      raise ParameterError.new(
         'Missing a `from` sender, message should contain at least 1 `from` sender',
         working_domain
-      ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+      )
+    end
+
+    def build_http_client(api_key, request_options)
+      Faraday.new(request_options) do |conn|
+        conn.request :multipart
+        conn.request :authorization, :basic, 'api', api_key
+        conn.request :url_encoded
+        conn.response :raise_error, include_request: true
+        conn.adapter Faraday.default_adapter
+        conn.options.params_encoder = Faraday::FlatParamsEncoder
+      end
     end
   end
 end