wj-mailgun-ruby 1.1.7

data/docs/Suppressions.md

@@ -0,0 +1,82 @@
+Mailgun - Suppressions
+====================
+
+This is the Mailgun Ruby *Suppressions* 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.
+
+----
+
+The Suppressions client lets you manage bounces, unsubscribes, and complaints for a
+single domain.
+
+You can view additional samples in the [suppressions_spec.rb](/spec/integration/suppressions_spec.rb)
+or the Suppressions client API in [suppressions.rb](/lib/mailgun/suppressions.rb).
+
+
+Usage
+-----
+
+To get an instance of the Suppressions client:
+
+```ruby
+mg_client = Mailgun::Client.new('api_key')
+supp_client = mg_client.suppressions('yourdomain.com')
+```
+
+----
+
+To get a list of bounces, unsubscribes, and/or complaints:
+
+```ruby
+supp_client.list_bounces
+supp_client.list_unsubscribes
+supp_client.list_complaints
+```
+
+----
+
+To batch-add a set of bounces:
+
+```ruby
+@addresses = <load or generate some addresses...>
+
+bounces = []
+@addresses.each do |addr|
+  bounces.push({
+    :address => addr,
+    :code => 500,
+    :error => 'some bounce because reasons',
+  })
+end
+
+response, addt_responses = @supp_client.create_bounces bounces
+```
+
+`create_bounces`, `create_unsubscribes`, and `create_complaints` will all
+return two values - first, a simple `Mailgun::Response` object. Second,
+a list containing any `Mailgun::Response` objects created recursively, if over 998
+bounces were provided to `create_*`.
+
+----
+
+To delete bounces:
+
+```ruby
+@addresses = <load addresses...>
+
+@addresses.each do |addr|
+  @supp_client.delete_bounce addr
+end
+```
+
+Or, alternatively, to remove *all* bounces:
+
+```ruby
+@supp_client.delete_all_bounces
+```
+
+The `delete_*` methods are similar for `bounces`, `unsubscribe`, and `complaints` -
+they all will return a `Mailgun::Response` object.

data/docs/Webhooks.md

@@ -0,0 +1,40 @@
+Mailgun - Webhooks
+====================
+
+This is the Mailgun Ruby *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. It currently supports
+all calls except updating webhooks.
+
+Usage - Webhooks
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key')
+hook = Mailgun::Webhooks.new(mg_client)
+
+# Get a list webhooks for a domain.
+hook.list 'my.perfect.domain'
+
+# View a single webhook detail
+hook.info 'my.perfect.domain', 'deliver'
+
+# 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/'
+
+# Remove a url for a specific webhook
+hook.remove 'my.perfect.domain', 'deliver'
+
+# Remove all webhooks for a domain
+hook.remove 'my.perfect.domain'
+```
+
+More Documentation
+------------------
+See the official [Mailgun Domain Docs](https://documentation.mailgun.com/api-webhooks.html)
+for more information

data/lib/mailgun-ruby.rb

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

data/lib/mailgun.rb

@@ -0,0 +1,39 @@
+require 'tempfile'
+require 'rest_client'
+require 'yaml'
+require 'json'
+
+require 'mailgun/version'
+require 'mailgun/client'
+require 'mailgun/response'
+require 'mailgun/chains'
+require 'mailgun/address'
+require 'mailgun/lists/opt_in_handler'
+require 'mailgun/messages/batch_message'
+require 'mailgun/messages/message_builder'
+require 'mailgun/events/events'
+require 'mailgun/exceptions/exceptions'
+require 'mailgun/domains/domains'
+require 'mailgun/webhooks/webhooks'
+
+# Module for interacting with the sweet Mailgun API.
+#
+# See the Github documentation for full examples.
+module Mailgun
+
+  class << self
+    attr_accessor :api_key,
+                  :api_version,
+                  :protocol,
+                  :mailgun_host,
+                  :test_mode,
+                  :domain
+
+    def configure
+      yield self
+      true
+    end
+    alias_method :config, :configure
+  end
+
+end

data/lib/mailgun/address.rb

@@ -0,0 +1,45 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # Mailgun::Address is a simple interface to the Email Validation API.
+  class Address
+
+    # @param [String] api_key Mailgun API - public key
+    def initialize(api_key = "")
+      if api_key == "" then
+        fail ParameterError.new('Public API key is required for Mailgun::Address.initialize()', nil)
+      end
+
+      @api_key = api_key
+      @client = Mailgun::Client.new(api_key = api_key)
+    end
+
+    # Given an arbitrary address, validates it based on defined checks.
+    #
+    # @param [String] address Email address to validate (max 512 chars.)
+    def validate(address)
+      res = @client.get "address/validate", {:address => address}
+      return res.to_h!
+    end
+
+    # Parses a delimiter separated list of email addresses into two lists:
+    # parsed addresses and unparsable portions. The parsed addresses are a
+    # list of addresses that are syntactically valid (and optionally have
+    # DNS and ESP specific grammar checks) the unparsable list is a list
+    # of characters sequences that the parser was not able to understand.
+    # These often align with invalid email addresses, but not always.
+    # Delimiter characters are comma (,) and semicolon (;).
+    #
+    # @param [Array] addresses Addresses to parse
+    # @param [TrueClass|FalseClass] syntax_only Perform only syntax checks
+    def parse(addresses, syntax_only = true)
+      validate_addrs = addresses.join(";")
+
+      res = @client.get "address/parse", {:addresses => validate_addrs,
+                                          :syntax_only => syntax_only.to_s}
+      return res.to_h!
+    end
+  end
+
+end

data/lib/mailgun/chains.rb

@@ -0,0 +1,16 @@
+module Mailgun
+
+  # Public constants used throughout
+  class Chains
+
+    # maximum campaign ids per message
+    MAX_CAMPAIGN_IDS = 3
+
+    # maximum tags per message
+    MAX_TAGS = 3
+
+    # maximum recipients per message or batch
+    MAX_RECIPIENTS = 1000
+
+  end
+end

data/lib/mailgun/client.rb

@@ -0,0 +1,199 @@
+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 RestClient so you don't have to worry about the HTTP aspect
+  # of communicating with our API.
+  #
+  # See the Github documentation for full examples.
+  class Client
+
+    def initialize(api_key = Mailgun.api_key,
+                   api_host = 'api.mailgun.net',
+                   api_version = 'v3',
+                   ssl = true,
+                   test_mode = false)
+
+      endpoint = endpoint_generator(api_host, api_version, ssl)
+      @http_client = RestClient::Resource.new(endpoint,
+                                              user: 'api',
+                                              password: api_key,
+                                              user_agent: "mailgun-sdk-ruby/#{Mailgun::VERSION}")
+      @test_mode = test_mode
+    end
+
+    # Enable test mode
+    #
+    # Prevents sending of any messages.
+    def enable_test_mode!
+      @test_mode = true
+    end
+
+    # Disable test mode
+    #
+    # Reverts the test_mode flag and allows the client to send messages.
+    def disable_test_mode!
+      @test_mode = false
+    end
+
+    # Client is in test mode?
+    #
+    # @return [Boolean] Is the client set in test mode?
+    def test_mode?
+      @test_mode
+    end
+
+    # Provides a store of all the emails sent in test mode so you can check them.
+    #
+    # @return [Hash]
+    def self.deliveries
+      @@deliveries ||= []
+    end
+
+    # Simple Message Sending
+    #
+    # @param [String] working_domain This is the domain you wish to send from.
+    # @param [Hash] data This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def send_message(working_domain, data)
+      if test_mode? then
+        Mailgun::Client.deliveries << data
+        return Response.from_hash(
+          {
+            :body => '{"id": "test-mode-mail@localhost", "message": "Queued. Thank you."}',
+            :code => 200,
+          }
+        )
+      end
+
+      case data
+      when Hash
+        # 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 }
+
+        if data.key?(:message)
+          if data[:message].is_a?(String)
+            data[:message] = convert_string_to_file(data[:message])
+          end
+          return post("#{working_domain}/messages.mime", data)
+        end
+        post("#{working_domain}/messages", data)
+      when MessageBuilder
+        post("#{working_domain}/messages", data.message)
+      else
+        fail ParameterError.new('Unknown data type for data parameter.', data)
+      end
+    end
+
+    # Generic Mailgun POST Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] data This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @param [Hash] headers Additional headers to pass to the resource.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def post(resource_path, data, headers = {})
+      response = @http_client[resource_path].post(data, headers)
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun GET Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @param [Hash] params This should be a standard Hash
+    # containing required parameters for the requested resource.
+    # @param [String] accept Acceptable Content-Type of the response body.
+    # @return [Mailgun::Response] A Mailgun::Response object.
+    def get(resource_path, params = nil, accept = '*/*')
+      if params
+        response = @http_client[resource_path].get(params: params, accept: accept)
+      else
+        response = @http_client[resource_path].get(accept: accept)
+      end
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun PUT Handler
+    #
+    # @param [String] resource_path This is the API resource you wish to interact
+    # with. Be sure to include your domain, where necessary.
+    # @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[resource_path].put(data)
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Generic Mailgun DELETE Handler
+    #
+    # @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)
+      response = @http_client[resource_path].delete
+      Response.new(response)
+    rescue => err
+      raise communication_error err
+    end
+
+    # Constructs a Suppressions client for the given domain.
+    #
+    # @param [String] domain Domain which suppressions requests will be made for
+    # @return [Mailgun::Suppressions]
+    def suppressions(domain)
+      Suppressions.new(self, domain)
+    end
+
+    private
+
+    # Converts MIME string to file for easy uploading to API
+    #
+    # @param [String] string MIME string to post to API
+    # @return [File] File object
+    def convert_string_to_file(string)
+      file = Tempfile.new('MG_TMP_MIME')
+      file.write(string)
+      file.rewind
+      file
+    end
+
+    # Generates the endpoint URL to for the API. Allows overriding
+    # API endpoint, API versions, and toggling SSL.
+    #
+    # @param [String] api_host URL endpoint the library will hit
+    # @param [String] api_version The version of the API to hit
+    # @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'
+      if api_version
+        "#{scheme}://#{api_host}/#{api_version}"
+      else
+        "#{scheme}://#{api_host}"
+      end
+    end
+
+    # Raises CommunicationError and stores response in it if present
+    #
+    # @param [StandardException] e upstream exception object
+    def communication_error(e)
+      return CommunicationError.new(e.message, e.response) if e.respond_to? :response
+      CommunicationError.new(e.message)
+    end
+
+  end
+end

data/lib/mailgun/domains/domains.rb

@@ -0,0 +1,84 @@
+require 'mailgun/exceptions/exceptions'
+
+module Mailgun
+
+  # A Mailgun::Domains object is a simple CRUD interface to Mailgun Domains.
+  # Uses Mailgun
+  class Domains
+
+    # Public: creates a new Mailgun::Domains instance.
+    #   Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new)
+      @client = client
+    end
+
+    # Public: Get Domains
+    #
+    # limit - [Integer] Maximum number of records to return. (100 by default)
+    # skip  - [Integer] Number of records to skip. (0 by default)
+    #
+    # Returns [Array] A list of domains (hash)
+    def list(options = {})
+      @client.get('domains', options).to_h['items']
+    end
+    alias_method :get_domains, :list
+
+    # Public: Get domain information
+    #
+    # domain - [String] Domain name to lookup
+    #
+    # Returns [Hash] Information on the requested domains.
+    def info(domain)
+      fail(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
+      @client.get("domains/#{domain}").to_h!
+    end
+    alias_method :get, :info
+    alias_method :get_domain, :info
+
+    # 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.
+    #
+    # domain - [String] Domain name
+    #
+    # Returns [Hash] Information on the updated/verified domains
+    def verify(domain)
+      fail(ParameterError, 'No domain given to verify on Mailgun', caller) unless domain
+      @client.put("domains/#{domain}/verify", nil).to_h!
+    end
+    alias_method :verify_domain, :verify
+
+    # Public: Add domain
+    #
+    # domain  - [String] Name of the domain (ex. domain.com)
+    # options - [Hash] of
+    #     smtp_password - [String] Password for SMTP authentication
+    #     spam_action   - [String] disabled or tag
+    #       Disable, no spam filtering will occur for inbound messages.
+    #       Tag, messages will be tagged wtih a spam header. See Spam Filter.
+    #     wildcard      - [Boolean] true or false Determines whether the domain will accept email for sub-domains.
+    #
+    # Returns [Hash] of created domain
+    def create(domain, options = {})
+      fail(ParameterError, 'No domain given to add on Mailgun', caller) unless domain
+      options = { smtp_password: nil, spam_action: 'disabled', wildcard: false }.merge(options)
+      options[:name] = domain
+      @client.post('domains', options).to_h
+    end
+    alias_method :add, :create
+    alias_method :add_domain, :create
+
+    # Public: Delete Domain
+    #
+    # domain - [String] domain name to delete (ex. domain.com)
+    #
+    # Returns [Boolean] if successful or not
+    def remove(domain)
+      fail(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
+      @client.delete("domains/#{domain}").to_h['message'] == 'Domain has been deleted'
+    end
+    alias_method :delete, :remove
+    alias_method :delete_domain, :remove
+
+  end
+end