mailgun-ruby 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56b457f9a512474de60aebfe220b4cb31bcfcfcc032972ce2c5a1aa0ad1322c2
-  data.tar.gz: 916852ea7483fe046b0d4c3c7883c79013b4378af43b2e6e978bf30f4dc9ef16
+  metadata.gz: 0f7b6ece85b0a809a90ea79e6836b55bc5a97cfe8cd036c1567acff92b8053c5
+  data.tar.gz: 277f0def30a104f86beef2c8ef3012b877fa94e35e415a9beff328cc76247280
 SHA512:
-  metadata.gz: 7d43f29a5a245d06253ae97e44830c9768f494597506ce6ff4e87f28cc9071f12a959d0d3102f2d6f85140e5f373c2eefdd491064f804c12669618feef929594
-  data.tar.gz: 3bbd64c03a2bad22f6d0853607e3bc97358ef7c55c35b2e0420c000fe7166422319c4a0f6bc80ddec2c6ad8aa99ba7a0bb5b6cd54e023de3a0491a0774e36143
+  metadata.gz: 3a419c6c2c8fbb7efa2ed08ad51da87441befe54e00e3a70db6626b82f353932827c5ebdd933f32edfe06ba043ea2dcba99cacd93a445f078ff089ad58af96ea
+  data.tar.gz: c910105de443193207c67c5afaa24b2d423dfb7b7e995466a95b8192d967f244f36e45142d78f97a46fb893809a633e793d75366ea206f83338b8f138a4ed3af

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/README.md

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

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,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # Mailgun::Address is a simple interface to the Email Validation API.

data/lib/mailgun/client.rb

@@ -1,7 +1,3 @@
-require 'mailgun/chains'
-require 'mailgun/suppressions'
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
   # A Mailgun::Client object is used to communicate with the Mailgun API. It is a
   # wrapper around Faraday so you don't have to worry about the HTTP aspect
@@ -15,7 +11,7 @@ module Mailgun
                    api_host = Mailgun.api_host || 'api.mailgun.net',
                    api_version = Mailgun.api_version  || 'v3',
                    ssl = true,
-                   test_mode = false,
+                   test_mode = !!Mailgun.test_mode,
                    timeout = nil,
                    proxy_url = Mailgun.proxy_url)
 
@@ -32,14 +28,7 @@ module Mailgun
       }
       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
@@ -173,8 +162,16 @@ 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, params, body_params = false)
+      response =
+        if body_params
+          @http_client.put(resource_path) do |request|
+            request['Content-Type'] = 'application/json'
+            request.params = params.to_json
+          end
+        else
+          @http_client.put(resource_path, params)
+        end
       Response.new(response)
     rescue => err
       raise communication_error err
@@ -185,12 +182,19 @@ 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
@@ -262,5 +266,16 @@ module Mailgun
         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

data/lib/mailgun/domains/domains.rb

@@ -1,6 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-require 'mailgun/helpers/api_version_checker'
-
 module Mailgun
 
   # A Mailgun::Domains object is a simple CRUD interface to Mailgun Domains.
@@ -26,11 +23,6 @@ module Mailgun
       @client.get('domains', options).to_h['items']
     end
 
-    def get_domains
-      warn('The `get_domains` method will be deprecated in future versions of Mailgun. Please use `list` instead.')
-      list
-    end
-
     # Public: Add domain
     #
     # domain  - [String] Name of the domain (ex. domain.com)
@@ -49,16 +41,6 @@ module Mailgun
       @client.post('domains', options).to_h
     end
 
-    def add(domain, options = {})
-      warn('The `add` method will be deprecated in future versions of Mailgun. Please use `create` instead.')
-      create(domain, options)
-    end
-
-    def add_domain(domain, options = {})
-      warn('The `add_domain` method will be deprecated in future versions of Mailgun. Please use `create` instead.')
-      create(domain, options)
-    end
-
     # Public: Get domain information
     #
     # domain - [String] Domain name to lookup
@@ -68,16 +50,6 @@ module Mailgun
       @client.get("domains/#{domain}").to_h!
     end
 
-    def info(domain)
-      warn('The `info` method will be deprecated in future versions of Mailgun. Please use `get` instead.')
-      get(domain)
-    end
-
-    def get_domain(domain)
-      warn('The `get_domain` method will be deprecated in future versions of Mailgun. Please use `get` instead.')
-      get(domain)
-    end
-
     # Public: Update domain
     #
     # domain  - [String] Name of the domain (ex. domain.com)
@@ -96,9 +68,7 @@ module Mailgun
     end
 
 
-    # Public: Verify domain, update domain records
-    #   Unknown status - this is not in the current Mailgun API
-    #   Do no rely on this being available in future releases.
+    # Public: Verify domain
     #
     # domain - [String] Domain name
     #
@@ -107,11 +77,6 @@ module Mailgun
       @client.put("domains/#{domain}/verify", nil).to_h!
     end
 
-    def verify_domain(domain)
-      warn('The `verify_domain` method will be deprecated in future versions of Mailgun. Please use `verify` instead.')
-      verify(domain)
-    end
-
     # Public: Delete Domain
     #
     # domain - [String] domain name to delete (ex. domain.com)
@@ -121,16 +86,6 @@ module Mailgun
       @client.delete("domains/#{domain}").to_h['message'] == 'Domain has been deleted'
     end
 
-    def delete(domain)
-      warn('The `delete` method will be deprecated in future versions of Mailgun. Please use `remove` instead.')
-      remove(domain)
-    end
-
-    def delete_domain(domain)
-      warn('The `delete_domain` method will be deprecated in future versions of Mailgun. Please use `remove` instead.')
-      remove(domain)
-    end
-
     # ==== End of Core Domains methods ====
 
     # ==== Domain::Keys methods ====
@@ -389,57 +344,17 @@ module Mailgun
 
     # ==== End of Reporting::Stats methods ====
 
-    # ==== Deprecated methods ====
-
-    # Public: Returns delivery connection settings for the defined domain.
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    #
-    # Returns [Hash] Information on the delivery connection settings
-    def get_domain_connection_settings(domain)
-      @client.get("domains/#{domain}/connection").to_h
-    end
-
-    # Public: Updates the specified delivery connection settings for the defined domain.d
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    # options - [Hash] of
-    #   require_tls  - [Boolean] true or false. If true - requires the message only be sent over a TLS connection
-    #   skip_verification  - [Boolean] true or false. If true - the certificate and hostname will not be verified
-    #     when trying to establish a TLS connection
-    #
-    # Returns [Hash] Information on the delivery connection settings
-    def update_domain_connection_settings(domain, options = {})
-      @client.put("domains/#{domain}/connection", options).to_h
-    end
-
-    # Public: Update the CNAME used for tracking opens and clicks
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    # options - [Hash] of
-    #   web_prefix  - [String] change the tracking CNAME for a domain.
-    #
-    # Returns [Hash] with message key
-    def update_domain_web_prefix(domain, options = {})
-      @client.put("domains/#{domain}/web_prefix", options).to_h
-    end
-
-    # ==== End of Deprecated methods ====
-
-
-
 
     enforces_api_version 'v1', :list_domain_keys, :create_domain_key, :delete_domain_key, :dkim_rotation,
                          :dkim_rotate
     enforces_api_version 'v2', :get_domain_tracking_certificate, :regenerate_domain_tracking_certificate,
                          :generate_domain_tracking_certificate
     enforces_api_version 'v3', :remove, :create_smtp_credentials, :update_smtp_credentials,
-                         :delete_smtp_credentials, :get_domain_connection_settings,
-                         :update_domain_connection_settings, :get_domain_tracking_settings,
+                         :delete_smtp_credentials, :get_domain_tracking_settings,
                          :update_domain_tracking_open_settings, :update_domain_tracking_click_settings,
                          :update_domain_tracking_unsubscribe_settings, :update_domain_dkim_authority,
-                         :update_domain_dkim_selector, :update_domain_web_prefix, :get_domain_stats
+                         :update_domain_dkim_selector, :get_domain_stats
     enforces_api_version 'v4', :get_domain_keys, :activate_domain_key, :deactivate_domain_key,
-                         :list, :info, :verify, :create, :update
+                         :list, :verify, :create, :update
   end
 end

data/lib/mailgun/events/events.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # A Mailgun::Events object makes it really simple to consume

data/lib/mailgun/exceptions/exceptions.rb

@@ -1,4 +1,6 @@
 module Mailgun
+  module Exceptions
+  end
 
   # Public: A basic class for mananging errors.
   # Inherits from StandardError (previously RuntimeError) as not all errors are

data/lib/mailgun/lists/opt_in_handler.rb

@@ -1,6 +1,3 @@
-require 'uri'
-require 'openssl'
-
 module Mailgun
 
   # Public: Provides methods for creating and handling opt-in URLs,

data/lib/mailgun/logs/logs.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
   # A Mailgun::Logs object is a simple interface to Mailgun Logs.
   # Uses Mailgun

data/lib/mailgun/messages/batch_message.rb

@@ -1,5 +1,3 @@
-require 'mailgun/messages/message_builder'
-
 module Mailgun
 
   # A Mailgun::BatchMessage object is used to create a valid payload

data/lib/mailgun/messages/message_builder.rb

@@ -1,7 +1,3 @@
-require 'mini_mime'
-require 'time'
-require 'faraday/multipart'
-
 module Mailgun
 
   # A Mailgun::MessageBuilder object is used to create a valid payload

data/lib/mailgun/metrics/metrics.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
   # A Mailgun::Metrics object is a simple interface to Mailgun Metrics.
   # Uses Mailgun

data/lib/mailgun/subaccounts/subaccounts.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # A Mailgun::Subaccounts object is a simple CRUD interface to Mailgun Subaccounts.

data/lib/mailgun/suppressions.rb

@@ -1,7 +1,3 @@
-require 'uri'
-
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # The Mailgun::Suppressions object makes it easy to manage "suppressions"
@@ -45,7 +41,7 @@ module Mailgun
     end
 
     def get_bounce(address)
-      @client.get("#{@domain}/bounces/#{escape_address(address)}", nil)
+      @client.get("#{@domain}/bounces/#{escape_address(address)}")
     end
 
     def create_bounce(params = {})
@@ -187,7 +183,7 @@ module Mailgun
     end
 
     def get_complaint(address)
-      @client.get("#{@domain}/complaints/#{escape_address(address)}", nil)
+      @client.get("#{@domain}/complaints/#{escape_address(address)}")
     end
 
     def create_complaint(params = {})

data/lib/mailgun/tags/analytics_tags.rb

@@ -0,0 +1,32 @@
+module Mailgun
+
+  # A Mailgun::AnalyticsTags object is a simple CRUD interface to Mailgun Tags.
+  # Uses Mailgun
+  class AnalyticsTags
+    include ApiVersionChecker
+
+    # Public: creates a new Mailgun::AnalyticsTags instance.
+    # Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v1'))
+      @client = client
+    end
+
+    def update(tag, description)
+      @client.put('analytics/tags', { tag: tag, description: description }, body_params: true ).to_h['message'] == 'Tag updated'
+    end
+
+    def list(options = {})
+      @client.post('analytics/tags', options).to_h['items']
+    end
+
+    def remove(tag)
+      @client.delete('analytics/tags', { tag: tag }, body_params: true).to_h['message'] == 'Tag deleted'
+    end
+
+    def limits
+      @client.get('analytics/tags/limits').to_h
+    end
+
+    enforces_api_version 'v1', :update, :list, :remove, :limits
+  end
+end

data/lib/mailgun/tags/tags.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # A Mailgun::Tags object is a simple CRUD interface to Mailgun Tags.
@@ -12,6 +10,9 @@ module Mailgun
       @client = client
     end
 
+    ### Deprecated Tags ###
+    # TODO: remove in v 1.5
+
     # Public: Get Tags
     #
     # domain - [String] Domain name where tag is stored
@@ -20,6 +21,7 @@ module Mailgun
     #
     # Returns [Array] A list of tags (hash)
     def get_tags(domain, options = {})
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to store template on', caller) unless domain
       @client.get("#{domain}/tags", options).to_h['items']
     end
@@ -31,6 +33,7 @@ module Mailgun
     #
     # Returns [Hash] Information on the requested tag.
     def get_tag(domain, tag)
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.get("#{domain}/tags/#{tag}").to_h!
@@ -45,6 +48,7 @@ module Mailgun
     #
     # Returns [Boolean] if successful or not
     def update(domain, tag, options = {})
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.put("#{domain}/tags/#{tag}", options).to_h['message'] == 'Tag updated'
@@ -63,6 +67,7 @@ module Mailgun
     #
     # Returns [Hash] of tag stats info
     def get_tag_stats(domain, tag, options = {})
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.get("#{domain}/tags/#{tag}/stats", options).to_h
@@ -76,6 +81,7 @@ module Mailgun
     #
     # Returns [Boolean] if successful or not
     def remove(domain, tag)
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
       fail(ParameterError, 'No template name given to find on provided domain', caller) unless tag
       @client.delete("#{domain}/tags/#{tag}").to_h['message'] == 'Tag deleted'
@@ -88,6 +94,7 @@ module Mailgun
     #
     # Returns [Hash] of countries of origin for a given domain
     def get_countries_aggregated_stats(domain, tag)
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.get("#{domain}/tags/#{tag}/stats/aggregates/countries").to_h
@@ -100,6 +107,7 @@ module Mailgun
     #
     # Returns [Hash] of email providers for a given domain
     def get_providers_aggregated_stats(domain, tag)
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.get("#{domain}/tags/#{tag}/stats/aggregates/providers").to_h
@@ -112,6 +120,7 @@ module Mailgun
     #
     # Returns [Hash] of devices for a given domain
     def get_devices_aggregated_stats(domain, tag)
+      warn('This API is deprecated in favor of our new analytics Tags API')
       fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       fail(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
       @client.get("#{domain}/tags/#{tag}/stats/aggregates/devices").to_h

data/lib/mailgun/templates/templates.rb

@@ -1,5 +1,3 @@
-require 'mailgun/exceptions/exceptions'
-
 module Mailgun
 
   # A Mailgun::Templates object is a simple CRUD interface to Mailgun Templates.

data/lib/mailgun/version.rb

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

data/lib/mailgun-ruby.rb

@@ -1,2 +1,2 @@
-require 'mailgun'
-require 'railgun' if defined?(Rails) && defined?(ActionMailer)
+require_relative 'mailgun'
+require_relative 'railgun' if defined?(Rails) && defined?(ActionMailer)