mailgun 0.8 → 0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20809378b057a083d20b98dd3dffb1d771d2845e
-  data.tar.gz: b063e69d0b35dca7f8a934e7a2e2fd3f9f5d57ff
+  metadata.gz: f47c74dc32e3f6a7436d43f289f9af79f449156f
+  data.tar.gz: 554bef62dd88c32a6de42af428c882e2b4f9c122
 SHA512:
-  metadata.gz: a568bf6b8ca38bd594d0f08e336c2d3a93961b32fe216e2d954e80b527675d8f8cbd91de0c8413e540135abed41be64e329e6dfe81911d71ad14196027daeed9
-  data.tar.gz: b307a01536f51da5b8bbd462ae477105685e95adab6e48f8c6c02dca6438f2affb929e8a0e76da4830dcee00fb33d9cbd4c40bdfad51b4b264bad3ecf128492e
+  metadata.gz: 7f0b40b7ecbeda0baea7d9069c10f4516d79b4fcc51e22f2bb98078d64a44883ee095b0b42d8945f0cfdc2a7530ff8f5bebbb3da64397c9156087087429c0c24
+  data.tar.gz: 34e235408386e399fe7f19f4ec6f51d52cf1d3487ceca784d89976f315ab74f7bd54b61ec4f1403f5a2928491bfc2ae1825b4c5087b5a8fc7e552e2326ab3e52

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.byebug_history

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3.0
+
+before_install:
+  - gem install bundler
+
+cache: bundler
+
+script: bundle exec rspec --color

data/CONTRIBUTORS.md

@@ -20,4 +20,8 @@
   * new functionality and improvements
 
 * Yomi Colledge / [@baphled](http://github.com/baphled)
-  * For refactoring API configuration and some documentation
+  * For refactoring API configuration and some documentation
+
+* Gregory Hilkert / [@EpiphanyMachine](http://github.com/EpiphanyMachine) and [@asheeshchoksi](https://github.com/asheeshchoksi)
+  * Support for Webhooks API
+  * Support for Address API

data/README.md

@@ -1,5 +1,7 @@
 # Mailgun rubygem
 
+![](https://travis-ci.org/HashNuke/mailgun.svg?branch=master)
+
 This gem allows for idiomatic Mailgun usage from within ruby. Mailgun is a kickass email-as-a-service that lets you use email as if it made sense. Check it out at http://mailgun.net
 
 Mailgun exposes the following resources:
@@ -16,6 +18,8 @@ Mailgun exposes the following resources:
   * Unsubscribes
   * Complaints
   * Domain management
+  * Webhook management
+  * Address Validation
 
 Patches are welcome (and easy!).
 
@@ -94,6 +98,9 @@ parameters = {
 # Add a member to a list
 @mailgun.list_members.add "devs@your.mailgun.domain", "Q@mi6.co.uk"
 
+# Add multiple mailing list members to a list (limit 1,000 per call)
+@mailgun.list_members.add_multi "devs@your.mailgun.domain", [{"address": "Alice <alice@example.com>", "vars": {"age": 26}}, {"name": "Bob", "address": "bob@example.com", "vars": {"age": 34}}].to_json, {:upsert => true}
+    
 # Update a member on a list
 @mailgun.list_members.update "devs@your.mailgun.domain", "Q@mi6.co.uk", "Q", {:gender => 'male'}.to_json, :subscribed => 'no')
 
@@ -181,6 +188,36 @@ Supported route actions are: `:forward`, and `:stop`
 @mailbox.domains.delete "example.com"
 ```
 
+#### Webhooks
+```ruby
+# List of currently available webhooks
+@mailgun.webhooks.available_ids
+
+# Returns a list of webhooks set for the specified domain
+@mailgun.webhooks.list
+
+# Returns details about the webhook specified
+@mailgun.webhooks.find(:open)
+
+# Creates a new webhook
+# Note: Creating an Open or Click webhook will enable Open or Click tracking
+@mailgun.webhooks.create(:open, "http://bin.example.com/8de4a9c4")
+
+# Updates an existing webhook
+@mailgun.webhooks.update(:open, "http://bin.example.com/8de4a9c4")
+
+# Deletes an existing webhook
+# Note: Deleting an Open or Click webhook will disable Open or Click tracking
+@mailgun.webhooks.delete(:open)
+```
+
+#### Address Validation
+Requires the `public_api_key` to be set.  The Mailgun public key is available in the My Account tab of the Control Panel.
+```ruby
+# Given an arbitrary address, validates address based off defined checks
+@mailgun.addresses.validate('hello@example.com')
+```
+
 ## Making Your Changes
 
   * Fork the project (Github has really good step-by-step directions)
@@ -208,9 +245,9 @@ Supported route actions are: `:forward`, and `:stop`
   * Campaign?
 
 
-## Maintainer
+## Maintainers
 
-Akash Manohar / [@HashNuke](http://github.com/HashNuke)
+* Hairihan / [@hairihan](http://github.com/hairihan)
 
 
 ## Authors

data/lib/mailgun.rb

@@ -1,4 +1,3 @@
-require "rest-client"
 require "json"
 require "multimap/lib/multimap"
 require "multimap/lib/multiset"
@@ -11,16 +10,22 @@ require "mailgun/route"
 require "mailgun/mailbox"
 require "mailgun/bounce"
 require "mailgun/unsubscribe"
+require "mailgun/webhook"
 require "mailgun/complaint"
 require "mailgun/log"
 require "mailgun/list"
 require "mailgun/list/member"
 require "mailgun/message"
+require "mailgun/secure"
+require "mailgun/address"
+require "mailgun/client"
 
 #require "startup"
 
 def Mailgun(options={})
   options[:api_key] = Mailgun.api_key if Mailgun.api_key
   options[:domain] = Mailgun.domain if Mailgun.domain
+  options[:webhook_url] = Mailgun.webhook_url if Mailgun.webhook_url
+  options[:public_api_key] = Mailgun.public_api_key if Mailgun.public_api_key
   Mailgun::Base.new(options)
 end

data/lib/mailgun/address.rb

@@ -0,0 +1,20 @@
+module Mailgun
+  # https://documentation.mailgun.com/api-email-validation.html#email-validation
+  class Address
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+
+    # Given an arbitrary address, validates address based off defined checks
+    def validate(email)
+      Mailgun.submit :get, address_url('validate'), {:address => email}
+    end
+
+    private
+
+    def address_url(action)
+      "#{@mailgun.public_base_url}/address/#{action}"
+    end
+  end
+end

data/lib/mailgun/base.rb

@@ -7,13 +7,17 @@ module Mailgun
     # * API key and version
     # * Test mode - if enabled, doesn't actually send emails (see http://documentation.mailgun.net/user_manual.html#sending-in-test-mode)
     # * Domain - domain to use
+    # * Webhook URL - default url to use if one is not specified in each request
+    # * Public API Key - used for address endpoint
     def initialize(options)
-      Mailgun.mailgun_host    = options.fetch(:mailgun_host)    {"api.mailgun.net"}
-      Mailgun.protocol        = options.fetch(:protocol)        { "https"  }
-      Mailgun.api_version     = options.fetch(:api_version)     { "v2"  }
+      Mailgun.mailgun_host    = options.fetch(:mailgun_host)    { "api.mailgun.net" }
+      Mailgun.protocol        = options.fetch(:protocol)        { "https" }
+      Mailgun.api_version     = options.fetch(:api_version)     { "v3" }
       Mailgun.test_mode       = options.fetch(:test_mode)       { false }
-      Mailgun.api_key         = options.fetch(:api_key)         { raise ArgumentError.new(":api_key is a required argument to initialize Mailgun") if Mailgun.api_key.nil?}
+      Mailgun.api_key         = options.fetch(:api_key)         { raise ArgumentError.new(":api_key is a required argument to initialize Mailgun") if Mailgun.api_key.nil? }
       Mailgun.domain          = options.fetch(:domain)          { nil }
+      Mailgun.webhook_url     = options.fetch(:webhook_url)     { nil }
+      Mailgun.public_api_key  = options.fetch(:public_api_key)  { nil }
     end
 
     # Returns the base url used in all Mailgun API calls
@@ -21,6 +25,10 @@ module Mailgun
       "#{Mailgun.protocol}://api:#{Mailgun.api_key}@#{Mailgun.mailgun_host}/#{Mailgun.api_version}"
     end
 
+    def public_base_url
+      "#{Mailgun.protocol}://api:#{Mailgun.public_api_key}@#{Mailgun.mailgun_host}/#{Mailgun.api_version}"
+    end
+
     # Returns an instance of Mailgun::Mailbox configured for the current API user
     def mailboxes(domain = Mailgun.domain)
       Mailgun::Mailbox.new(self, domain)
@@ -46,6 +54,17 @@ module Mailgun
       Mailgun::Unsubscribe.new(self, domain)
     end
 
+    def webhooks(domain = Mailgun.domain, webhook_url = Mailgun.webhook_url)
+      Mailgun::Webhook.new(self, domain, webhook_url)
+    end
+
+    def addresses(domain = Mailgun.domain)
+      if Mailgun.public_api_key.nil?
+        raise ArgumentError.new(":public_api_key is a required argument to validate addresses")
+      end
+      Mailgun::Address.new(self)
+    end
+
     def complaints(domain = Mailgun.domain)
       Mailgun::Complaint.new(self, domain)
     end
@@ -61,25 +80,33 @@ module Mailgun
     def list_members(address)
       Mailgun::MailingList::Member.new(self, address)
     end
+
+    def secure
+      Mailgun::Secure.new(self)
+    end
   end
 
 
   # Submits the API call to the Mailgun server
   def self.submit(method, url, parameters={})
     begin
-      parameters = {:params => parameters} if method == :get
-      return JSON(RestClient.send(method, url, parameters))
+      JSON.parse(Client.new(url).send(method, parameters))
     rescue => e
-      error_message = nil
-      if e.respond_to? :http_body
-        begin
-          error_message = JSON(e.http_body)["message"]
-        rescue
-          raise e
-        end
-        raise Mailgun::Error.new(error_message)
+      error_code = e.http_code
+      error_message = begin
+        JSON(e.http_body)["message"]
+      rescue JSON::ParserError
+        ''
+      end
+      error = Mailgun::Error.new(
+        :code => error_code || nil,
+        :message => error_message || nil
+      )
+      if error.handle.kind_of? Mailgun::ErrorBase
+        raise error.handle
+      else
+        raise error
       end
-      raise e
     end
   end
 
@@ -92,7 +119,9 @@ module Mailgun
                   :protocol,
                   :mailgun_host,
                   :test_mode,
-                  :domain
+                  :domain,
+                  :webhook_url,
+                  :public_api_key
 
     def configure
       yield self

data/lib/mailgun/client.rb

@@ -0,0 +1,87 @@
+module Mailgun
+  class Client
+    attr_reader :url
+
+    def initialize(url)
+      @url = url
+    end
+
+    def get(params = {})
+      request_path = path
+      request_path += "?#{URI.encode_www_form(params)}" if params.any?
+
+      request = Net::HTTP::Get.new(request_path)
+
+      make_request(request)
+    end
+
+    def post(params = {})
+      request = Net::HTTP::Post.new(path)
+      request.set_form_data(params)
+
+      make_request(request)
+    end
+
+    def put(params = {})
+      request = Net::HTTP::Put.new(path)
+      request.set_form_data(params)
+
+      make_request(request)
+    end
+
+    def delete(params = {})
+      request = Net::HTTP::Delete.new(path)
+      request.set_form_data(params)
+
+      make_request(request)
+    end
+
+    private
+
+    def make_request(request)
+      set_auth(request)
+      response = http_client.request(request)
+
+      check_for_errors(response)
+
+      response.body
+    end
+
+    def check_for_errors(response)
+      return if response.code == '200'
+
+      error = ClientError.new
+      error.http_code = response.code.to_i
+      error.http_body = response.body
+      raise error
+    end
+
+    def path
+      parsed_url.path
+    end
+
+    def parsed_url
+      @parsed_url ||= URI.parse url
+    end
+
+    def http_client
+      http = Net::HTTP.new(mailgun_url.host, mailgun_url.port)
+      http.use_ssl = true
+      http
+    end
+
+    def mailgun_url
+      URI.parse Mailgun().base_url
+    end
+
+    def set_auth(request)
+      request.basic_auth(parsed_url.user, parsed_url.password)
+    end
+  end
+end
+
+module Mailgun
+  class ClientError < StandardError
+    attr_accessor :http_code, :http_body
+  end
+end

data/lib/mailgun/domain.rb

@@ -2,12 +2,11 @@ module Mailgun
 
   # Interface to manage domains
   class Domain
-
     # Used internally, called from Mailgun::Base
     def initialize(mailgun)
       @mailgun = mailgun
     end
-    
+
     # List all domains on the account
     def list(options={})
       Mailgun.submit(:get, domain_url, options)["items"] || []
@@ -29,12 +28,18 @@ module Mailgun
       Mailgun.submit :delete, domain_url(domain)
     end
 
+    # Verifies a domain from account (Check DNS Records Now from Mailgun Web UI)
+    # The method is still in beta and you will need
+    # access from Mailgun to use it
+    def verify(domain)
+      Mailgun.submit :put, "#{domain_url(domain)}/verify"
+    end
+
     private
 
     # Helper method to generate the proper url for Mailgun domain API calls
     def domain_url(domain = nil)
       "#{@mailgun.base_url}/domains#{'/' + domain if domain}"
     end
-    
   end
-end
+end

data/lib/mailgun/list/member.rb

@@ -27,6 +27,11 @@ module Mailgun
       Mailgun.submit :post, list_member_url, params.merge(options)
     end
 
+    def add_multi(members=[], options={})
+      params = {:members => members}
+      Mailgun.submit :post, list_member_json, params.merge(options)
+    end
+
     # TODO add spec?
     alias_method :create, :add
 
@@ -48,6 +53,9 @@ module Mailgun
     def list_member_url(member_address=nil)
       "#{@mailgun.base_url}/lists#{'/' + @address}/members#{'/' + member_address if member_address}"
     end
-    
+
+    def list_member_json
+      "#{@mailgun.base_url}/lists#{'/' + @address}/members.json"
+    end
   end
 end

data/lib/mailgun/mailgun_error.rb

@@ -1,4 +1,57 @@
 module Mailgun
-  class Error < StandardError
+  class Error
+    attr_accessor :error
+
+    def initialize(options={})
+      @error =
+        case options[:code]
+        when 200
+          # Not an error
+        when 404
+          Mailgun::NotFound.new(options[:message])
+        when 400
+          Mailgun::BadRequest.new(options[:message])
+        when 401
+          Mailgun::Unauthorized.new(options[:message])
+        when 402
+          Mailgun::ResquestFailed.new(options[:message])
+        when 500, 502, 503, 504
+          Mailgun::ServerError.new(options[:message])
+        else
+          Mailgun::ErrorBase.new(options[:message])
+        end
+    end
+
+    def handle
+      return error.handle
+    end
+  end
+
+  class ErrorBase < StandardError
+    # Handles the error if needed
+    # by default returns an error
+    #
+    # @return [type] [description]
+    def handle
+      return self
+    end
+  end
+
+  class NotFound < ErrorBase
+    def handle
+      return nil
+    end
+  end
+
+  class BadRequest < ErrorBase
+  end
+
+  class Unauthorized < ErrorBase
+  end
+
+  class ResquestFailed < ErrorBase
+  end
+
+  class ServerError < ErrorBase
   end
 end