RubyGems - mailgun-ruby - Versions diffs - 1.0.3 → 1.1.0 - Mend

mailgun-ruby 1.0.3 → 1.1.0

Files changed (62) hide show

checksums.yaml +4 -4
data/.gitignore +2 -0
data/.rubocop.yml +8 -0
data/.rubocop_todo.yml +22 -0
data/.ruby-env.yml.example +12 -0
data/.travis.yml +6 -12
data/Domains.md +36 -0
data/MessageBuilder.md +14 -14
data/Messages.md +44 -30
data/OptInHandler.md +34 -34
data/README.md +74 -24
data/Rakefile +22 -20
data/Snippets.md +26 -26
data/Webhooks.md +40 -0
data/lib/mailgun.rb +26 -228
data/lib/mailgun/chains.rb +16 -0
data/lib/mailgun/client.rb +143 -0
data/lib/mailgun/domains/domains.rb +84 -0
data/lib/mailgun/events/events.rb +53 -35
data/lib/mailgun/exceptions/exceptions.rb +43 -10
data/lib/mailgun/lists/opt_in_handler.rb +18 -19
data/lib/mailgun/messages/batch_message.rb +31 -48
data/lib/mailgun/messages/message_builder.rb +160 -144
data/lib/mailgun/response.rb +55 -0
data/lib/mailgun/version.rb +2 -3
data/lib/mailgun/webhooks/webhooks.rb +101 -0
data/mailgun.gemspec +16 -10
data/spec/integration/bounces_spec.rb +44 -0
data/spec/integration/campaign_spec.rb +60 -0
data/spec/integration/complaints_spec.rb +38 -0
data/spec/integration/domains_spec.rb +39 -0
data/spec/integration/email_validation_spec.rb +29 -0
data/spec/integration/events_spec.rb +20 -0
data/spec/integration/list_members_spec.rb +63 -0
data/spec/integration/list_spec.rb +58 -0
data/spec/integration/mailgun_spec.rb +26 -550
data/spec/integration/routes_spec.rb +74 -0
data/spec/integration/stats_spec.rb +15 -0
data/spec/integration/unsubscribes_spec.rb +42 -0
data/spec/integration/webhook_spec.rb +54 -0
data/spec/spec_helper.rb +37 -7
data/spec/unit/connection/test_client.rb +15 -95
data/spec/unit/events/events_spec.rb +9 -6
data/spec/unit/lists/opt_in_handler_spec.rb +6 -4
data/spec/unit/mailgun_spec.rb +25 -19
data/spec/unit/messages/batch_message_spec.rb +47 -38
data/spec/unit/messages/message_builder_spec.rb +282 -111
data/vcr_cassettes/bounces.yml +175 -0
data/vcr_cassettes/complaints.yml +175 -0
data/vcr_cassettes/domains.todo.yml +42 -0
data/vcr_cassettes/domains.yml +360 -0
data/vcr_cassettes/email_validation.yml +104 -0
data/vcr_cassettes/events.yml +61 -0
data/vcr_cassettes/list_members.yml +320 -0
data/vcr_cassettes/mailing_list.todo.yml +43 -0
data/vcr_cassettes/mailing_list.yml +390 -0
data/vcr_cassettes/routes.yml +359 -0
data/vcr_cassettes/send_message.yml +107 -0
data/vcr_cassettes/stats.yml +44 -0
data/vcr_cassettes/unsubscribes.yml +191 -0
data/vcr_cassettes/webhooks.yml +276 -0
metadata +114 -10

data/Rakefile CHANGED

@@ -1,33 +1,35 @@
-begin
-	require 'bundler/gem_tasks'
-rescue LoadError
-end
+require 'bundler/gem_tasks'
 require 'rake'
 require 'rspec/core/rake_task'
-require 'bundler/gem_tasks'
-desc "Build Gem"
-	task :default do
-		system "gem build mailgun.gemspec"
-	end
-desc "Run default unit specs"
-RSpec::Core::RakeTask.new('spec') do |t|
-  t.rspec_opts = %w{--colour --format progress}
-  t.pattern = 'spec/unit/*_spec.rb', 'spec/unit/*/*_spec.rb'
+desc 'Build Gem'
+task :build do
+  system 'gem build mailgun.gemspec'
 end
-desc "Run unit specs"
+desc 'Run unit specs'
 RSpec::Core::RakeTask.new('spec:unit') do |t|
-  t.rspec_opts = %w{--colour --format progress}
+  t.rspec_opts = %w(--colour --format documentation)
   t.pattern = 'spec/unit/*_spec.rb', 'spec/unit/*/*_spec.rb'
 end
-desc "Run integration specs"
+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 progress}
+  t.rspec_opts = %w(--colour --format documentation)
   t.pattern = 'spec/integration/*_spec.rb'
-end
+end
+desc 'Run all tests'
+RSpec::Core::RakeTask.new('spec:all') do |t|
+  t.rspec_opts = %w(--colour --format documentation)
+  t.pattern = 'spec/**/*_spec.rb'
+end
+task default: 'spec:unit'
+task spec: 'spec:unit'
+task :console do
+  sh 'pry --gem'
+end

data/Snippets.md CHANGED

@@ -1,15 +1,15 @@
 Mailgun-Ruby Snippets
 =====================
-This page is filled with snippets that cover almost every API endpoint and action. Copy, Paste, Go! There will be little inline documentation in these samples, please consult Mailgun's official documentation for detailed information.
+This page is filled with snippets that cover almost every API endpoint and action. Copy, Paste, Go! There will be little inline documentation in these samples, please consult Mailgun's official documentation for detailed information.
-If you haven't already installed the SDK, go to the README and follow the installation instructions.
+If you haven't already installed the SDK, go to the README and follow the installation instructions.
 These snippets require that you pipe in a few parameters. "mg_client" is instantiated like so:
 ```ruby
 require 'mailgun'
-mg_client = Mailgun::Client.new "your-api-key"
+mg_client = Mailgun::Client.new "your-api-key"
 ```
 ### Messages:
@@ -17,9 +17,9 @@ ____________________________________________________
 **Send a basic message: **
 ```ruby
-data = {:from => 'bob@sending_domain.com',
-                  :to => 'sally@example.com',
-                  :subject => 'The Ruby SDK is awesome!',
+data = {:from => 'bob@sending_domain.com',
+                  :to => 'sally@example.com',
+                  :subject => 'The Ruby SDK is awesome!',
                   :text => 'It is really easy to send a message!'}
 mg_client.send_message "sending_domain.com", data
@@ -28,9 +28,9 @@ mg_client.send_message "sending_domain.com", data
 **Send a multipart text/html message:**
 ```ruby
-data = {:from => 'bob@sending_domain.com',
-                  :to => 'sally@example.com',
-                  :subject => 'The Ruby SDK is awesome!',
+data = {:from => 'bob@sending_domain.com',
+                  :to => 'sally@example.com',
+                  :subject => 'The Ruby SDK is awesome!',
                   :text => 'This is the text part.',
                   :html => '<html><body><p>This is the HTML part.</p></body></html>'}
@@ -68,10 +68,10 @@ mg_client.send_message "sending_domain.com", data
 ```ruby
 mb_obj = Mailgun::MessageBuilder.new
-mb_obj.set_from_address :from, "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
+mb_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
 mb_obj.add_recipient :to, "recipient@example.com", {'first' => 'Recipient', 'last' => 'User'}
-mb_obj.set_subject :subject, "This is the subject!"
-mb_obj.set_text_body :text, "This is the text body."
+mb_obj.set_subject "This is the subject!"
+mb_obj.set_text_body "This is the text body."
 mg_client.send_message "sending_domain.com", mb_obj
 ```
@@ -82,10 +82,10 @@ mg_client.send_message "sending_domain.com", mb_obj
 bm_obj = Mailgun::BatchMessage.new
 # Build message using Message Builder
-bm_obj.set_from_address :from, "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
+bm_obj.set_from_address "sender@example.com", {'first' => 'Sending', 'last' => 'User'}
 bm_obj.set_message_id("<20141014000000.11111.11111@example.com>") # optional
-bm_obj.set_subject :subject, "This is the subject!"
-bm_obj.set_text_body :text, "This is the text body."
+bm_obj.set_subject "This is the subject!"
+bm_obj.set_text_body "This is the text body."
 # Loop and add unlimited recipients (batch jobs will fire when thresholds reached)
 bm_obj.add_recipient :to, "a_user@example.com"
@@ -108,10 +108,10 @@ result = @mg_client.get "domains", {:limit => 5, :skip => 0}
 result = @mg_client.get "domains/#{domain}"
 ```
-**Add a domain:**
+**Add a domain:**
 ```ruby
-result = @mg_client.post "domains", {:name => 'anothersample.mailgun.org',
+result = @mg_client.post "domains", {:name => 'anothersample.mailgun.org',
                                      :smtp_password => 'super_secret',
                                      :spam_action => 'tag'}
 ```
@@ -210,7 +210,7 @@ ____________________________________________________
 **Get Statistics: **
 ```ruby
-result = @mg_client.get "#{domain}/stats", {:limit => 50,
+result = @mg_client.get "#{domain}/stats", {:limit => 50,
                                             :skip => 10,
                                             :event => 'sent',
                                             "start-date" => 'Mon, 13 Feb 2015 00:00:00 GMT'}
@@ -300,7 +300,7 @@ result = @mg_client.delete "#{domain}/campaigns/#{campaign_id}"
 **Get Campaign Events: **
 ```ruby
-result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event => 'clicked',
+result = @mg_client.get "#{domain}/campaigns/#{campaign_id}/events", {:event => 'clicked',
                                                                       :recipient => 'test@example.com',
                                                                       :country => 'US',
                                                                       :region => 'TX',
@@ -488,7 +488,7 @@ result = @mg_client.get "address/validate", {:address => 'test@example.com'}
 **Parse Addresses: **
 ```ruby
-result = @mg_client.get "address/parse", {:addresses => 'test@example.com, "First Last <first.last@example.com>',
+result = @mg_client.get "address/parse", {:addresses => 'test@example.com, "First Last <first.last@example.com>',
                                           :syntax_only => true}
 ```
@@ -496,12 +496,12 @@ result = @mg_client.get "address/parse", {:addresses => 'test@example.com, "Firs
 Support and Feedback
 --------------------
-Be sure to visit the Mailgun official
-[documentation website](http://documentation.mailgun.com/) for additional
-information about our API.
+Be sure to visit the Mailgun official
+[documentation website](https://documentation.mailgun.com/) for additional
+information about our API.
-If you find a bug, please submit the issue in Github directly.
+If you find a bug, please submit the issue in Github directly.
 [Mailgun-Ruby Issues](https://github.com/mailgun/Mailgun-PHP/issues)
-As always, if you need additional assistance, drop us a note at
-[support@mailgun.com](mailto:support@mailgun.com).
+As always, if you need additional assistance, drop us a note at
+[support@mailgun.com](mailto:support@mailgun.com).

data/Webhooks.md ADDED

@@ -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.rb CHANGED

@@ -3,238 +3,36 @@ require 'rest_client'
 require 'yaml'
 require 'json'
-require "mailgun/version"
-require "mailgun/lists/opt_in_handler"
-require "mailgun/messages/batch_message"
-require "mailgun/events/events"
-require "mailgun/messages/message_builder"
-require "mailgun/exceptions/exceptions"
+require 'mailgun/version'
+require 'mailgun/client'
+require 'mailgun/response'
+require 'mailgun/chains'
+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
-  # 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,
-                   api_host="api.mailgun.net",
-                   api_version="v2",
-                   ssl=true)
-      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}")
-    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)
-      case data
-      when Hash
-        if data.has_key?(:message)
-          if data[:message].is_a?(String)
-            data[:message] = convert_string_to_file(data[:message])
-          end
-          post("#{working_domain}/messages.mime", data)
-        else
-          post("#{working_domain}/messages", data)
-        end
-      when MessageBuilder
-        post("#{working_domain}/messages", data.message)
-      else
-        raise 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.
-    # @return [Mailgun::Response] A Mailgun::Response object.
-    def post(resource_path, data)
-      begin
-        response = @http_client[resource_path].post(data)
-        Response.new(response)
-      rescue Exception => e
-        communication_error e
-      end
-    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] query_string This should be a standard Hash
-    # containing required parameters for the requested resource.
-    # @return [Mailgun::Response] A Mailgun::Response object.
+  class << self
+    attr_accessor :api_key,
+                  :api_version,
+                  :protocol,
+                  :mailgun_host,
+                  :test_mode,
+                  :domain
-    def get(resource_path, params=nil, accept="*/*")
-      begin
-        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 Exception => e
-        communication_error e
-      end
+    def configure
+      yield self
+      true
     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)
-      begin
-        response = @http_client[resource_path].put(data)
-        Response.new(response)
-      rescue Exception => e
-        communication_error e
-      end
-    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)
-      begin
-        response = @http_client[resource_path].delete()
-        Response.new(response)
-      rescue Exception => e
-        communication_error e
-      end
-    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
-    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 [Exception] e upstream exception object
-    def communication_error(e)
-      if e.respond_to? :response
-        raise CommunicationError.new(e.message, e.response)
-      else
-        raise CommunicationError.new(e.message)
-      end
-    end
-  end
-  # A Mailgun::Response object is instantiated for each response generated
-  # by the Client request. The Response object supports deserialization of
-  # the JSON result. Or, if you prefer JSON or YAML formatting, call the
-  # method for conversion.
-  #
-  # See the Github documentation for full examples.
-  class Response
-    attr_accessor :body
-    attr_accessor :code
-    def initialize(response)
-      @body = response.body
-      @code = response.code
-    end
-    # Return response as Ruby Hash
-    #
-    # @return [Hash] A standard Ruby Hash containing the HTTP result.
-    def to_h
-      begin
-        JSON.parse(@body)
-      rescue Exception => e
-        raise ParseError.new(e), e
-      end
-    end
-    # Replace @body with Ruby Hash
-    #
-    # @return [Hash] A standard Ruby Hash containing the HTTP result.
-    def to_h!
-      begin
-        @body = JSON.parse(@body)
-      rescue Exception => e
-        raise ParseError.new(e), e
-      end
-    end
-    # Return response as Yaml
-    #
-    # @return [String] A string containing response as YAML
-    def to_yaml
-      begin
-        YAML::dump(JSON.parse(@body))
-      rescue Exception => e
-        raise ParseError.new(e), e
-      end
-    end
-    # Replace @body with YAML
-    #
-    # @return [String] A string containing response as YAML
-    def to_yaml!
-      begin
-        @body = YAML::dump(JSON.parse(@body))
-      rescue Exception => e
-        raise ParseError.new(e), e
-      end
-    end
+    alias_method :config, :configure
   end
 end