mailgun-ruby 1.4.3 → 1.4.5

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.4.3'
+gem 'mailgun-ruby', '~>1.4.5'
 ```
 
 Usage
@@ -186,6 +186,8 @@ This SDK includes the following components:
 - [Opt-In Handler](docs/OptInHandler.md)
 - [Domains](docs/Domains.md)
 - [Webhooks](docs/Webhooks.md)
+- [Account Webhooks](docs/AccountWebhooks.md)
+- [API Keys](docs/ApiKeys.md)
 - [Events](docs/Events.md)
 - [Snippets](docs/Snippets.md)
 - [Subaccounts](docs/Subaccounts.md)

data/docs/AccountWebhooks.md

@@ -0,0 +1,55 @@
+Mailgun - Account Webhooks
+====================
+
+This is the Mailgun Ruby *Account 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.
+
+Usage - Account Webhooks
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key')
+hook = Mailgun::AccountWebhooks.new(mg_client)
+
+```
+
+Account Webhooks methods:
+
+```ruby
+# List account-level webhooks
+hook.list
+hook.list('id1, id2')
+
+# Create an account-level webhook
+hook.create(
+  description: 'desc',
+  event_types: 'accepted',
+  url: 'https://the.webhook.url/'
+)
+
+# Delete account-level webhooks
+hook.remove(all: true)
+hook.remove('id1, id2')
+
+# Get account-level webhook by ID
+hook.get('id1')
+
+# Update an account-level webhook
+hook.update(
+  'hook',
+  description: 'desc',
+  event_types: 'accepted',
+  url: 'https://the.webhook.url/'
+)
+
+# Delete account-level webhook by ID
+hook.remove_by_id('id1')
+```
+
+More Documentation
+------------------
+See the official [Mailgun Account Webhooks Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/account-webhooks)
+for more information

data/docs/ApiKeys.md

@@ -0,0 +1,65 @@
+Mailgun - API Keys
+====================
+
+This is the Mailgun Ruby *API Keys* 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.
+
+Usage - API Keys
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key', 'api.mailgun.net', 'v1')
+api_keys = Mailgun::ApiKeys.new(mg_client)
+```
+
+API Keys methods:
+
+```ruby
+# List API keys
+api_keys.list
+
+# List API keys filtered by kind and domain
+api_keys.list(kind: 'domain', domain_name: 'my.perfect.domain')
+
+# Create a user API key
+api_keys.create(
+  kind: 'user',
+  role: 'admin',
+  description: 'desc'
+)
+
+# Create a sending key for a domain, expiring in 1 day
+api_keys.create(
+  kind: 'domain',
+  domain_name: 'my.perfect.domain',
+  role: 'sending',
+  expiration: 86_400
+)
+
+# Delete an API key
+api_keys.remove('key-id')
+
+# Regenerate the public API key
+api_keys.regenerate
+```
+
+Supported `create` options:
+
+| Option        | Description |
+|---------------|-------------|
+| `kind`        | Type of API key: `domain`, `user` or `web`. Defaults to `user` |
+| `role`        | Key role: `admin`, `basic`, `sending` (for `domain` keys) or `developer` |
+| `domain_name` | Domain to associate with the key, for `domain` keys |
+| `description` | Key description |
+| `expiration`  | Key lifetime in seconds, must be greater than 0 if set |
+| `user_id`     | API key user's ID, should be provided for `web` keys |
+| `user_name`   | API key user's name |
+| `email`       | API key user's email address, should be provided for `web` keys |
+
+More Documentation
+------------------
+See the official [Mailgun API Keys Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/keys)
+for more information

data/docs/DomainKeys.md

@@ -0,0 +1,49 @@
+Mailgun - DomainKeys
+====================
+
+This is the Mailgun Ruby *DomainKeys* 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.
+
+Usage - DomainKeys
+-----------------------
+First, instantiate the Mailgun Client with your API key
+```ruby
+mg_client = Mailgun::Client.new('your-api-key')
+domainer = Mailgun::DomainKeys.new(mg_client)
+```
+
+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'
+
+# 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' }
+```
+
+More Documentation
+------------------
+See the official [Mailgun Domain Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys)
+for more information

data/docs/Domains.md

@@ -41,34 +41,6 @@ domainer.remove 'this.one.is.not.needed.'
 
 ```
 
-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'
-
-# 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

data/docs/Webhooks.md

@@ -18,25 +18,48 @@ hook = Mailgun::Webhooks.new(mg_client)
 hook.list 'my.perfect.domain'
 
 # View a single webhook detail
-hook.info 'my.perfect.domain', 'deliver'
+hook.info 'my.perfect.domain', 'delivered'
 
 # Add a single url for all webhooks
 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/'
+hook.create 'my.perfect.domain', 'delivered', 'https://the.webhook.url/'
 
 # Update the url for a specific webhook
-hook.update 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
+hook.update 'my.perfect.domain', 'delivered', 'https://the.webhook.url/'
 
 # Remove a url for a specific webhook
-hook.remove 'my.perfect.domain', 'deliver'
+hook.remove 'my.perfect.domain', 'delivered'
 
 # Remove all webhooks for a domain
 hook.remove_all 'my.perfect.domain'
 ```
 
+Usage - Webhooks (v4)
+-----------------------
+
+The v4 endpoints work with a URL across multiple event types in a single request.
+They require a client configured for the `v4` API.
+
+```ruby
+mg_client = Mailgun::Client.new('your-api-key', 'api.mailgun.net', 'v4')
+hook = Mailgun::Webhooks.new(mg_client)
+
+# Associate a url with one or more event types
+hook.create_v4 'my.perfect.domain', url: 'https://the.webhook.url/', event_types: %w[delivered opened]
+
+# Replace the event types associated with a url
+hook.update_v4 'my.perfect.domain', url: 'https://the.webhook.url/', event_types: %w[clicked]
+
+# Remove one or more urls from all event types they are associated with
+hook.remove_v4 'my.perfect.domain', url: 'https://the.webhook.url/'
+hook.remove_v4 'my.perfect.domain', url: ['https://the.webhook.url/', 'https://another.webhook.url/']
+```
+
+Each v4 method returns a Hash of the domain's webhooks keyed by event type.
+
 More Documentation
 ------------------
-See the official [Mailgun Domain Docs](https://documentation.mailgun.com/en/latest/api-webhooks.html)
+See the official [Mailgun Webhooks Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-webhooks)
 for more information

data/lib/mailgun/api_keys/api_keys.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mailgun
+  # A Mailgun::ApiKeys object is a simple CRUD interface to Mailgun Api Keys.
+  # Uses Mailgun
+  class ApiKeys
+    include ApiVersionChecker
+
+    # Public creates a new Mailgun::ApiKeys 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: List Mailgun API keys
+    #
+    # options - [Hash] of
+    #   domain_name - [String] Domain name filter for domain keys
+    #   kind        - [String] Key kind filter ('domain', 'user', or 'web')
+    #
+    # Retrieve filtered api keys.
+    def list(options = {})
+      res = @client.get('keys', options)
+      res.to_h['items']
+    end
+
+    # Public: Create Mailgun API key
+
+    # options - [Hash] of
+    #   domain_name - [String] Web domain to associate with the key, for keys of 'domain' kind
+    #   kind        - [String] Type of API key ('domain', 'user', or 'web'). Defaults to 'user' if not provided.
+    #   description - [String] Key description
+    #   expiration  - [String] Key lifetime in seconds, must be greater than 0 if set
+    #   role        - [String] Key role ('admin', 'basic' [use in place of analyst],
+    #                          'sending' [use with keys of domain kind], or 'developer')
+    #   user_id     - [String] API Key user's string user ID; should be provided for all keys of 'web' kind
+    #   user_name   - [String] API Key user's name
+    #   email       - [String] API Key user's email address; should be provided for all keys of 'web' kind
+    #
+    # Returns the Api Key object
+    def create(options = {})
+      res = @client.post('keys', options)
+      res.to_h['key']
+    end
+
+    # Public: Delete Mailgun API key
+    #
+    # key_id - [String] The Key ID generated by Mailgun on key creation
+    #
+    # Returns a Boolean of the success
+    def remove(key_id)
+      @client.delete("keys/#{key_id}").status == 200
+    end
+
+    # Public: Regenerate Mailgun Public API key
+    #
+    # Returns new Mailgun Public API key.
+    def regenerate
+      res = @client.post('keys/public', {})
+      res.to_h['key']
+    end
+
+    enforces_api_version 'v1', :list, :create, :remove, :regenerate
+  end
+end

data/lib/mailgun/client.rb

@@ -13,7 +13,7 @@ module Mailgun
                    api_host = Mailgun.api_host || 'api.mailgun.net',
                    api_version = Mailgun.api_version || 'v3',
                    ssl = true,
-                   test_mode = !Mailgun.test_mode.nil?,
+                   test_mode = Mailgun.test_mode ? true : false,
                    timeout = nil,
                    proxy_url = Mailgun.proxy_url)
       endpoint = endpoint_generator(api_host, api_version, ssl)
@@ -185,7 +185,7 @@ module Mailgun
               request.body = params.to_json
             end
           else
-            @http_client.delete(resource_path, params: params)
+            @http_client.delete(resource_path, params)
           end
         else
           @http_client.delete(resource_path)

data/lib/mailgun/domains/domain_keys.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Mailgun
+  # A Mailgun::Domains object is a simple CRUD interface to Mailgun DomainsKeys.
+  # Uses Mailgun
+  class DomainKeys
+    include ApiVersionChecker
+
+    def initialize(client = Mailgun::Client.new)
+      @client = client
+    end
+
+    # Public: List keys for all domains
+    #
+    # options - [Hash] of
+    #   page - [String] Encoded paging information, provided via 'next', 'previous' links
+    #   limit - [Integer] Limits the number of items returned in a request
+    #   signing_domain  - [String] Filter by signing domain
+    #   selector - [String] Filter by selector
+    #
+    # Returns [Hash] with message key
+    def list_domain_keys(options = {})
+      @client.get('dkim/keys', options).to_h
+    end
+
+    # Public: Create a domain key
+    #
+    # options - [Hash] of
+    #   signing_domain  - [String] Name of the domain (ex. domain.com)
+    #   selector - [String] Selector to be used for the new domain key
+    #   bits - [Integer] Key size, can be 1024 or 2048
+    #   pem - [String] Private key PEM
+    #
+    # Returns [Hash] with message key
+    def create_domain_key(options = {})
+      @client.post('dkim/keys', options).to_h
+    end
+
+    # Public: Delete a domain key.
+    #
+    # options - [Hash] of
+    #   signing_domain - [Integer] Name of the domain (ex. domain.com)
+    #   selector - [String] Name of the selector
+    #
+    # Returns [Hash] with message key
+    def delete_domain_key(options = {})
+      @client.delete('dkim/keys', options).to_h
+    end
+
+    # Public: Activate a domain key for a specified authority and selector.
+    #
+    # domain    - [String] Name of the domain (ex. domain.com)
+    # selector  - [String] The selector you want to activate for the domain key
+    #
+    # Returns [Hash] with message key and autority + selector data
+    def activate_domain_key(domain, selector)
+      @client.put("domains/#{domain}/keys/#{selector}/activate", {}).to_h
+    end
+
+    # Public: Lists the domain keys for a specified signing domain / authority
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    #
+    # Returns [Hash] with domain keys data
+    def get_domain_keys(domain)
+      @client.get("domains/#{domain}/keys").to_h
+    end
+
+    # Public: Deactivate a domain key for a specified authority and selector
+    #
+    # domain    - [String] Name of the domain (ex. domain.com)
+    # selector  - [String] The selector you want to activate for the domain key
+    #
+    # Returns [Hash] with message key and autority + selector data
+    def deactivate_domain_key(domain, selector)
+      @client.put("domains/#{domain}/keys/#{selector}/deactivate", {}).to_h
+    end
+
+    # Public: Change the DKIM authority for a domain.
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    # options - [Hash] of
+    #   self  - [Boolean] true - the domain will be the DKIM authority for itself even
+    #           if the root domain is registered on the same mailgun account
+    #
+    # Returns [Hash] Information on the DKIM authority
+    def update_domain_dkim_authority(domain, options = {})
+      @client.put("domains/#{domain}/dkim_authority", options).to_h
+    end
+
+    # Public: Update the DKIM selector for a domains
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    # options - [Hash] of
+    #   dkim_selector  - [String] change the DKIM selector for a domain.
+    #
+    # Returns [Hash] with message key
+    def update_domain_dkim_selector(domain, options = {})
+      @client.put("domains/#{domain}/dkim_selector", options).to_h
+    end
+
+    enforces_api_version 'v1', :list_domain_keys, :create_domain_key, :delete_domain_key
+    enforces_api_version 'v3', :update_domain_dkim_authority, :update_domain_dkim_selector
+    enforces_api_version 'v4', :activate_domain_key, :deactivate_domain_key
+    enforces_api_version 'v4', :get_domain_keys
+  end
+end

data/lib/mailgun/domains/domains.rb

@@ -88,100 +88,6 @@ module Mailgun
 
     # ==== End of Core Domains methods ====
 
-    # ==== Domain::Keys methods ====
-
-    # Public: List keys for all domains
-    #
-
-    # options - [Hash] of
-    #   page - [String] Encoded paging information, provided via 'next', 'previous' links
-    #   limit - [Integer] Limits the number of items returned in a request
-    #   signing_domain  - [String] Filter by signing domain
-    #   selector - [String] Filter by selector
-    #
-    # Returns [Hash] with message key
-    def list_domain_keys(options = {})
-      @client.get('dkim/keys', options).to_h
-    end
-
-    # Public: Create a domain key
-    #
-    # options - [Hash] of
-    #   signing_domain  - [String] Name of the domain (ex. domain.com)
-    #   selector - [String] Selector to be used for the new domain key
-    #   bits - [Integer] Key size, can be 1024 or 2048
-    #   pem - [String] Private key PEM
-    #
-    # Returns [Hash] with message key
-    def create_domain_key(options = {})
-      @client.post('dkim/keys', options).to_h
-    end
-
-    # Public: Delete a domain key.
-    #
-    # options - [Hash] of
-    #   signing_domain - [Integer] Name of the domain (ex. domain.com)
-    #   selector - [String] Name of the selector
-    #
-    # Returns [Hash] with message key
-    def delete_domain_key(options = {})
-      @client.delete('dkim/keys', options).to_h
-    end
-
-    # Public: Activate a domain key for a specified authority and selector.
-    #
-    # domain    - [String] Name of the domain (ex. domain.com)
-    # selector  - [String] The selector you want to activate for the domain key
-    #
-    # Returns [Hash] with message key and autority + selector data
-    def activate_domain_key(domain, selector)
-      @client.put("domains/#{domain}/keys/#{selector}/activate", {}).to_h
-    end
-
-    # Public: Lists the domain keys for a specified signing domain / authority
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    #
-    # Returns [Hash] with domain keys data
-    def get_domain_keys(domain)
-      @client.get("domains/#{domain}/keys").to_h
-    end
-
-    # Public: Deactivate a domain key for a specified authority and selector
-    #
-    # domain    - [String] Name of the domain (ex. domain.com)
-    # selector  - [String] The selector you want to activate for the domain key
-    #
-    # Returns [Hash] with message key and autority + selector data
-    def deactivate_domain_key(domain, selector)
-      @client.put("domains/#{domain}/keys/#{selector}/deactivate", {}).to_h
-    end
-
-    # Public: Change the DKIM authority for a domain.
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    # options - [Hash] of
-    #   self  - [Boolean] true - the domain will be the DKIM authority for itself even
-    #           if the root domain is registered on the same mailgun account
-    #
-    # Returns [Hash] Information on the DKIM authority
-    def update_domain_dkim_authority(domain, options = {})
-      @client.put("domains/#{domain}/dkim_authority", options).to_h
-    end
-
-    # Public: Update the DKIM selector for a domains
-    #
-    # domain  - [String] Name of the domain (ex. domain.com)
-    # options - [Hash] of
-    #   dkim_selector  - [String] change the DKIM selector for a domain.
-    #
-    # Returns [Hash] with message key
-    def update_domain_dkim_selector(domain, options = {})
-      @client.put("domains/#{domain}/dkim_selector", options).to_h
-    end
-
-    # ==== End of Domain::Keys methods ====
-
     # ==== Domain::Tracking methods ====
 
     # Public: Returns tracking settings for the defined domain.
@@ -346,16 +252,13 @@ module Mailgun
 
     # ==== End of Reporting::Stats methods ====
 
-    enforces_api_version 'v1', :list_domain_keys, :create_domain_key, :delete_domain_key, :dkim_rotation,
-                         :dkim_rotate
+    enforces_api_version 'v1', :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_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, :get_domain_stats
-    enforces_api_version 'v4', :get_domain_keys, :activate_domain_key, :deactivate_domain_key,
-                         :list, :verify, :create, :update
+                         :update_domain_tracking_unsubscribe_settings, :get_domain_stats
+    enforces_api_version 'v4', :list, :verify, :create, :update
   end
 end

data/lib/mailgun/helpers/api_version_checker.rb

@@ -11,9 +11,9 @@ module Mailgun
         method_names.each do |method_name|
           original_method = instance_method(method_name)
 
-          define_method(method_name) do |*args, &block|
+          define_method(method_name) do |*args, **kwargs, &block|
             warn_unless_api_version(version)
-            original_method.bind(self).call(*args, &block)
+            original_method.bind(self).call(*args, **kwargs, &block)
           end
         end
       end
@@ -22,9 +22,9 @@ module Mailgun
         method_names.each do |method_name|
           original_method = instance_method(method_name)
 
-          define_method(method_name) do |*args, &block|
+          define_method(method_name) do |*args, **kwargs, &block|
             require_api_version(version)
-            original_method.bind(self).call(*args, &block)
+            original_method.bind(self).call(*args, **kwargs, &block)
           end
         end
       end

data/lib/mailgun/version.rb

@@ -2,5 +2,5 @@
 
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.4.3'
+  VERSION = '1.4.5'
 end