mailgun 0.0.3 → 0.5

data/.gitignore

@@ -15,3 +15,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+startup.rb
+Guardfile
+.DS_Store
+lib/startup.rb

data/Gemfile

@@ -1,9 +1,9 @@
 source 'http://rubygems.org'
 
-gem "rest-client"
-
 group :development do
   gem "rspec"
+  gem "guard"
+  gem 'simplecov', :require => false, :group => :test
 end
 
 # Specify your gem's dependencies in mailgun.gemspec

data/README.md

@@ -6,30 +6,133 @@ The official gem repo is at https://github.com/Bushido/mailgun
 
 Mailgun exposes the following resources:
 
+  * Mailing Lists
+  * Mailing List Members
+  * Mailboxes
   * Routes
   * Log
   * Stats
   * Messages
-  * Mailboxes
+  * Bounces
+  * Unsubscribes
+  * Complaints
+
+Currently the gem only exposes the Mailbox and Routes APIs, but patches are welcome (and easy!). 
+
+ActionMailer
+============
+
+This gem is unnecessary if you'd like to simply hook up Mailgun to Rails' Action Mailer.  Just add the below to your Configuration.
 
-Currently the gem only exposes the Mailbox API, but patches are welcome (and easy!). 
+    ActionMailer::Base.smtp_settings = {
+      :port           => 587, 
+      :address        => 'smtp.mailgun.org',
+      :user_name      => 'postmaster@your.mailgun.domain',
+      :password       => 'mailgun-smtp-password',
+      :domain         => 'your.mailgun.domain',
+      :authentication => :plain,
+    }
+    ActionMailer::Base.delivery_method = :smtp
 
 Usage
 =====
 We mimic the ActiveRecord-style interface.
 
+
+Configuration:
+
     # Initialize your Mailgun object:
+    Mailgun.configure do |config|
+      config.api_key = 'your-api-key'
+      config.domain  = 'your-mailgun-domain'
+    end
+
+    @mailgun = Mailgun()
+
+    # or alternatively:
     @mailgun = Mailgun(:api_key => 'your-api-key')
     
+
+Mailing Lists:
+
+    # Create a mailing list
+    @mailgun.lists.create "devs@your.mailgun.domain"
+
+    # List all Mailing lists
+    @mailgun.lists.all
+
+    # Find a mailing list
+    @mailgun.lists.find "devs@your.mailgun.domain"
+
+    # Update a mailing list
+    @mailgun.lists.update("devs@your.mailgun.domain", "developers@your.mailgun.domain", "Developers", "Develepor Mailing List")
+
+    # Delete a mailing list
+    @mailgun.lists.delete("developers@your.mailgun.domain")
+
+Mailing List Members:
+
+    # List all members within a mailing list
+    @mailgun.list_members.list "devs@your.mailgun.domain"
+
+    # Find a particular member in a list
+    @mailgun.list_members.find "devs@your.mailgun.domain", "bond@mi6.co.uk"
+
+    # Add a member to a list
+    @mailgun.list_members.add "devs@your.mailgun.domain", "Q@mi6.co.uk"
+
+    # 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')
+
+    # Remove a member from a list
+    @mailgun.list_members.remove "devs@your.mailgun.domain", "M@mi6.co.uk"
+
+Mailboxes:
+
     # Create a mailbox
-    @mailgun.mailbox.create "new-mailbox@your-domain.com", "password"
+    @mailgun.mailboxes.create "new-mailbox@your-domain.com", "password"
     
     # List all mailboxes that belong to a domain
-    @mailgun.mailboxes.list domain.com"
+    @mailgun.mailboxes.list "domain.com"
     
     # Destroy a mailbox (queue bond-villian laughter)
     # "I'm sorry Bond, it seems your mailbox will be... destroyed!"
-    @mailbox.mailboxes.destroy "bond@mi5.co.uk"
+    @mailbox.mailboxes.destroy "bond@mi6.co.uk"
+    
+
+Routes:
+
+    # Initialize your Mailgun object:
+    @mailgun = Mailgun(:api_key => 'your-api-key')
+
+    # Create a route
+    # Give it a human-readable description for later, a priority
+    # filters, and actions
+    @mailgun.routes.create "Description for the new route", 1,
+         [:match_recipient, "apowers@mi5.co.uk"],
+         [[:forward, "http://my-site.com/incoming-mail-route"],
+          [:stop]]
+    
+    # List all routes that belong to a domain
+    # limit the query to 100 routes starting from 0
+    @mailgun.routes.list 100, 0
+
+    # Get the details of a route via its id
+    @mailgun.routes.find "4e97c1b2ba8a48567f007fb6"
+
+    # Update a route via its id
+    # (all keys are optional)
+    @mailgun.routes.update "4e97c1b2ba8a48567f007fb6", {
+         :priority => 2,
+         :filter   => [:match_header, :subject, "*.support"],
+         :actions  => [[:forward, "http://new-site.com/incoming-emails"]]
+         }
+    
+    # Destroy a route via its id
+    @mailbox.routes.destroy "4e97c1b2ba8a48567f007fb6"
+
+Supported route filters are: `:match_header`, `:match_recipient`, and `:catch_all`
+Supported route actions are: `:forward`, and `:stop`
 
 Making Your Changes
 ===================
@@ -41,18 +144,28 @@ Making Your Changes
   * After making your changes, be sure to run the Mailgun RSpec specs to make sure everything works.
   * Submit your change as a Pull Request and update the GitHub issue to let us know it is ready for review.
 
+
+TODO
+=========
+
+  * Mailgun() is overwriting api key. api key is not persisting
+  * Add skip and limit functionality
+  * Distinguish failed in logs
+  * Distinguish delivered in logs
+  * Tracking?
+  * Stats?
+  * Campaign?
+
 Authors
 =======
 
   * Akash Manohar J (akash@akash.im)
+  * Scott Carleton (@scotterc) - for new functionality and major improvements.
   * Sean Grove (sean@gobushido.com)
+  
 
-Thanks
-======
-Huge thanks to the Mailgun guys for such an amazing service! No time spent on mailservers == way more time spent drinking!
-
-License & Copyright
+License
 ===================
-Released under the MIT license. See LICENSE for more details.
+Released under the MIT license by CloudFuji. See LICENSE for more details.
 
-All copyright Bushido Inc. 2011
+This is a fork of he Cloudfuji/mailgun repo.

data/lib/mailgun/base.rb

@@ -1,11 +1,5 @@
 module Mailgun
   class Base
-    attr_accessor :api_key,
-                  :api_version,
-                  :protocol,
-                  :mailgun_host,
-                  :use_test_mode
-
     # Options taken from
     # http://documentation.mailgun.net/quickstart.html#authentication
     # * Mailgun host - location of mailgun api servers
@@ -13,22 +7,86 @@ 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)
     def initialize(options)
-      @mailgun_host = options.fetch(:mailgun_host) {"api.mailgun.net"}
-      @protocol     = options.fetch(:protocol)     { "https"  }
-      @api_version  = options.fetch(:api_version)  { "v2"  }
-      @test_mode    = options.fetch(:test_mode)    { false }
-
-      @api_key      = options.fetch(:api_key)      { raise ArgumentError(":api_key is a required argument to initialize Mailgun") }
+      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.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?}
     end
 
     # Returns the base url used in all Mailgun API calls
     def base_url
-      "#{@protocol}://api:#{api_key}@#{mailgun_host}/#{api_version}"
+      "#{Mailgun.protocol}://api:#{Mailgun.api_key}@#{Mailgun.mailgun_host}/#{Mailgun.api_version}"
     end
 
     # Returns an instance of Mailgun::Mailbox configured for the current API user
     def mailboxes
       @mailboxes ||= Mailgun::Mailbox.new(self)
     end
+    
+    def routes
+      @routes ||= Mailgun::Route.new(self)
+    end
+    
+    def bounces
+      @bounces ||= Mailgun::Bounce.new(self)
+    end
+    
+    def unsubscribes
+      @unsubscribes ||= Mailgun::Unsubscribe.new(self)
+    end
+
+    def complaints
+      @complaints ||= Mailgun::Complaint.new(self)
+    end
+
+    def log
+      @log ||= Mailgun::Log.new(self)
+    end
+
+    def lists
+      @lists ||= Mailgun::List.new(self)
+    end
+
+    def list_members
+      @list_members ||= Mailgun::List::Member.new(self)
+    end
+  end
+
+
+  # Submits the API call to the Mailgun server
+  def self.submit(method, url, parameters={})
+    begin
+      return JSON(RestClient.send(method, url, 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)
+      end
+      raise e
+    end
+  end
+
+  #
+  # @TODO Create root module to give this a better home
+  #
+  class << self
+    attr_accessor :api_key,
+                  :api_version,
+                  :protocol,
+                  :mailgun_host,
+                  :test_mode,
+                  :domain
+
+    def configure
+      yield self
+      true
+    end
+    alias :config :configure
   end
 end

data/lib/mailgun/bounce.rb

@@ -0,0 +1,35 @@
+module Mailgun
+  class Bounce
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+    # List all bounces for a given domain
+    # * domain the domain for which all bounces will listed
+    def list(domain = Mailgun.domain)
+      response = Mailgun.submit :get, bounce_url(domain)
+
+      if response
+        response["items"].collect {|item| item["address"]}
+      end
+    end
+
+    def find(domain = Mailgun.domain, email)
+      Mailgun.submit :get, bounce_url(domain, email)
+    end
+
+    def add(domain = Mailgun.domain, email)
+      Mailgun.submit :post, bounce_url(domain), :address => email
+    end
+
+    private
+
+    # Helper method to generate the proper url for Mailgun mailbox API calls
+    def bounce_url(domain, address=nil)
+      domain = Mailgun.domain if Mailgun.domain
+      "#{@mailgun.base_url}/#{domain}/bounces#{'/' + address if address}"
+    end
+    
+  end
+end

data/lib/mailgun/complaint.rb

@@ -0,0 +1,38 @@
+module Mailgun
+  class Complaint
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+    # List all complaints for a given domain
+    # * domain the domain for which all complaints will listed
+    def list(domain = Mailgun.domain)
+      response = Mailgun.submit :get, complaint_url(domain)
+
+      if response
+        response["items"].collect {|item| item["address"]}
+      end
+    end
+    
+    def find(domain = Mailgun.domain, email)
+      Mailgun.submit :get, complaint_url(domain, email)
+    end
+
+    def add(domain=Mailgun.domain, email)
+      Mailgun.submit :post, complaint_url(domain), {:address => email}
+    end
+
+    def remove(domain = Mailgun.domain, email)
+      Mailgun.submit :delete, complaint_url(domain, email)
+    end
+
+    private
+
+    # Helper method to generate the proper url for Mailgun complaints API calls
+    def complaint_url(domain, address=nil)
+      "#{@mailgun.base_url}/#{domain}/complaints#{'/' + address if address}"
+    end
+    
+  end
+end

data/lib/mailgun/list/member.rb

@@ -0,0 +1,57 @@
+module Mailgun
+  class List::Member
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+    ## List Member functionality
+
+    # List all mailing list members
+    # TODO add parameters: subscribed, limit, skip
+    def list(address)
+      response = Mailgun.submit :get, list_member_url(address)
+
+      if response
+        response["items"].collect {|item| item["address"]}
+      end
+    end
+
+    # List a single mailing list member by a given address
+    def find(address, member_address)
+      Mailgun.submit :get, list_member_url(address, member_address)
+    end
+
+    # Adds a mailing list member with a given address
+    # TODO add name, vars, subscribed, upsert
+    def add(address, member_address, name=nil, vars={}, subscribed='yes', upsert='no')
+      params = {:address => member_address, :subscribed => subscribed, :upsert => 'no'}
+      params[:name] = name if name
+      params[:vars] = vars unless vars.empty?
+      Mailgun.submit :post, list_member_url(address), params
+    end
+
+    # Update a mailing list member with a given address
+    # with an optional new member_address, name, vars and subscribed
+    def update(address, member_address, name=nil, vars={}, subscribed='yes')
+      params = {:address => member_address, :subscribed => subscribed}
+      params[:name] = name if name
+      params[:vars] = vars unless vars.empty?
+      Mailgun.submit :put, list_member_url(address, member_address), params
+    end   
+
+    # Deletes a mailing list member with a given address
+    def remove(address, member_address)
+      Mailgun.submit :delete, list_member_url(address, member_address)
+    end
+
+
+    private
+
+    # Helper method to generate the proper url for Mailgun mailbox API calls
+    def list_member_url(address, member_address=nil)
+      "#{@mailgun.base_url}/lists#{'/' + address}/members#{'/' + member_address if member_address}"
+    end
+    
+  end
+end

data/lib/mailgun/list.rb

@@ -0,0 +1,59 @@
+module Mailgun
+	class List
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+
+    ## List functionality
+
+    # TODO add default domain functionality for the address names of lists
+
+    # List all mailing lists 
+    def all
+      response = Mailgun.submit :get, list_url
+
+      if response
+        response["items"].collect {|item| item["address"]}
+      end
+    end
+
+    # List a single mailing list by a given address
+    def find(address)
+      Mailgun.submit :get, list_url(address)
+    end
+
+    # Create a mailing list with a given address
+    # with an optional name and description
+    def create(address, name=nil, description=nil)
+    	params = {:address => address}
+    	params[:name] = name if name
+    	params[:description] = description if description
+      Mailgun.submit :post, list_url, params
+    end
+
+    # Update a mailing list with a given address
+    # with an optional new address, name or description
+    def update(address, new_address, name=nil, description=nil)
+     	params = {:address => new_address}
+    	params[:name] = name if name
+    	params[:description] = description if description
+      Mailgun.submit :put, list_url(address), params
+    end		
+
+    # Deletes a mailing list with a given address
+    def delete(address)
+    	Mailgun.submit :delete, list_url(address)
+    end
+
+
+    private
+
+    # Helper method to generate the proper url for Mailgun mailbox API calls
+    def list_url(address=nil)
+      "#{@mailgun.base_url}/lists#{'/' + address if address}"
+    end
+    
+	end
+end

data/lib/mailgun/log.rb

@@ -0,0 +1,26 @@
+module Mailgun
+	class Log
+    # Used internally, called from Mailgun::Base
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+    # List all logs for a given domain
+    # * domain the domain for which all complaints will listed
+    def list(domain=Mailgun.domain, limit=100, skip=0)
+      response = Mailgun.submit :get, log_url(domain), {:limit => limit, :skip => skip}
+
+      if response
+        response["items"].collect {|item| item["message"]}
+      end
+    end
+    
+    private
+
+    # Helper method to generate the proper url for Mailgun complaints API calls
+    def log_url(domain)
+      "#{@mailgun.base_url}/#{domain}/log"
+    end
+   
+	end
+end

data/lib/mailgun/mailbox.rb

@@ -5,17 +5,21 @@ module Mailgun
     def initialize(mailgun)
       @mailgun = mailgun
     end
-
+    
     # List all mailboxes for a given domain
     # * domain the domain for which all mailboxes will listed
-    def list(domain)
-      submit :get, mailbox_url(domain)
+    def list(domain = Mailgun.domain)
+      response = Mailgun.submit :get, mailbox_url(domain)
+
+      if response
+        response["items"].collect {|item| item["mailbox"]}
+      end
     end
     
 
     # Creates a mailbox on the Mailgun server with the given password
     def create(address, password)
-      submit :post, mailbox_url(address.split("@").last), :mailbox =>  address,
+      Mailgun.submit :post, mailbox_url(address.split("@").last), :mailbox =>  address,
       :password => password
     end
 
@@ -24,7 +28,7 @@ module Mailgun
     def update_password(address, password)
       mailbox_name, domain = address.split("@")
 
-      submit :put, mailbox_url(domain, mailbox_name), :password => password
+      Mailgun.submit :put, mailbox_url(domain, mailbox_name), :password => password
     end
 
 
@@ -32,7 +36,7 @@ module Mailgun
     def destroy(address)
       mailbox_name, domain = address.split("@")
 
-      submit :delete,  mailbox_url(domain, mailbox_name)
+      Mailgun.submit :delete,  mailbox_url(domain, mailbox_name)
     end
 
 
@@ -43,10 +47,5 @@ module Mailgun
       "#{@mailgun.base_url}/#{domain}/mailboxes#{'/' + mailbox_name if mailbox_name}"
     end
 
-
-    # Submits the API call to the Mailgun server
-    def submit(method, url, parameters={})
-      JSON(RestClient.send(method, url, parameters))
-    end
   end
 end

data/lib/mailgun/mailgun_error.rb

@@ -0,0 +1,4 @@
+module Mailgun
+  class Error < StandardError
+  end
+end

data/lib/mailgun/route.rb

@@ -0,0 +1,94 @@
+module Mailgun
+  class Route
+
+    def initialize(mailgun)
+      @mailgun = mailgun
+    end
+    
+    def list(limit=100, skip=0)
+      Mailgun.submit(:get, route_url, :limit => limit, :skip => skip)["items"] || []
+    end
+
+    def find(route_id)
+      Mailgun.submit(:get, route_url(route_id))["route"]
+    end
+
+    def create(description, priority, filter, actions)
+      data = ::Multimap.new
+
+      data['priority']    = priority
+      data['description'] = description
+      data['expression']  = build_filter(filter)
+
+      actions = build_actions(actions)
+
+      actions.each do |action|
+        data['action'] = action
+      end
+
+      # TODO: Raise an error or return false if unable to create route
+      Mailgun.submit(:post, route_url, data)["route"]["id"]
+    end
+
+    def update(route_id, params)
+      data = ::Multimap.new
+
+      ['priority', 'description'].each do |key|
+        data[key] = params[key] if params.has_key?(key)
+      end
+
+      data['expression'] = build_filter(params['expression']) if params.has_key?('expression')
+
+      if params.has_key?('actions')
+        actions = build_actions(params['actions'])
+
+        actions.each do |action|
+          data['action'] = action
+        end
+      end
+
+      Mailgun.submit(:put, route_url(route_id), data)
+    end
+    
+    def destroy(route_id)
+      Mailgun.submit(:delete, route_url(route_id))["id"]
+    end
+    
+    private
+
+    def route_url(route_id=nil)
+      "#{@mailgun.base_url}/routes#{'/' + route_id if route_id}"
+    end
+
+    def build_actions(actions)
+      _actions = []
+
+      actions.each do |action|
+        case action.first.to_sym
+        when :forward
+          _actions << "forward(\"#{action.last}\")"
+        when :stop
+          _actions << "stop()"
+        else
+          raise Mailgun::Error.new("Unsupported action requested, see http://documentation.mailgun.net/user_manual.html#routes for a list of allowed actions")
+        end
+      end
+
+      _actions
+    end
+
+
+    def build_filter(filter)
+      case filter.first.to_sym
+      when :match_recipient
+        return "match_recipient('#{filter.last}')"
+      when :match_header
+        return "match_header('#{filter[1]}', '#{filter.last}')"
+      when :catch_all
+        return "catch_all()"
+      else
+        raise Mailgun::Error.new("Unsupported filter requested, see http://documentation.mailgun.net/user_manual.html#routes for a list of allowed filters")
+      end
+    end
+  end
+end