mailgun 0.5 → 0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0473a66b46e7ce54574d5f4f4c89867a563f2982
+  data.tar.gz: 9ad4fff672c513bc611fd99f724570177fa19582
+SHA512:
+  metadata.gz: 1cddcab564ee3f9a8e1759a1ec253fef84ccb88a65debd3ab7c1e139a39c4d2c577dd90937e600cfbb90ffe8bd78cfea0378d472999749f0ecdeefab23a9ee36
+  data.tar.gz: e768a1407bdf85514d1ba2940b2fdb3d34f35de5d76159ad0274437441897d0e2c0e92df4f24d255948a2b4bf4718603cf6b9f15ae3ebc006b2c3fe64c79279e

data/Gemfile

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

data/README.md

@@ -1,11 +1,10 @@
-Mailgun
-=========
-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 rubygem
 
-The official gem repo is at https://github.com/Bushido/mailgun
+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:
 
+  * Sending email
   * Mailing Lists
   * Mailing List Members
   * Mailboxes
@@ -17,136 +16,156 @@ Mailgun exposes the following resources:
   * Unsubscribes
   * Complaints
 
-Currently the gem only exposes the Mailbox and Routes APIs, but patches are welcome (and easy!). 
+Patches are welcome (and easy!). 
 
-ActionMailer
-============
+## Sending mail using 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.
+If you simply want to send mail using Mailgun, just set the smtp settings in the Rails application like the following. Replace wherever necessary in the following snippet :)
+```ruby
+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
+```
 
-    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
 
-Usage
-=====
 We mimic the ActiveRecord-style interface.
 
 
-Configuration:
+#### Configuration
+```ruby
+# 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')
+```
+
+#### Sending Email
+```ruby
+parameters = {
+  :to => "cooldev@your.mailgun.domain",
+  :subject => "missing tps reports",
+  :text => "yeah, we're gonna need you to come in on friday...yeah.",
+  :from => "lumberg.bill@initech.mailgun.domain"
+}
+@mailgun.messages.send_email(parameters)
+```
+####
+
+#### Mailing Lists
+```ruby
+# 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
+```ruby
+# 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
+```ruby
+# Create a mailbox
+@mailgun.mailboxes.create "new-mailbox@your-domain.com", "password"
+
+# List all mailboxes that belong to a domain
+@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@mi6.co.uk"
+```
+
+#### Routes
+```ruby
+# 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"
+```
 
-    # 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:
+Supported route filters are: `:match_header`, `:match_recipient`, and `:catch_all`
 
-    # Create a mailbox
-    @mailgun.mailboxes.create "new-mailbox@your-domain.com", "password"
-    
-    # List all mailboxes that belong to a domain
-    @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@mi6.co.uk"
-    
+Supported route actions are: `:forward`, and `:stop`
 
-Routes:
 
-    # Initialize your Mailgun object:
-    @mailgun = Mailgun(:api_key => 'your-api-key')
+## Making Your Changes
 
-    # 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
+  * Fork the project (Github has really good step-by-step directions)
 
-    # Get the details of a route via its id
-    @mailgun.routes.find "4e97c1b2ba8a48567f007fb6"
+  * Start a feature/bugfix branch
 
-    # 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"
+  * Commit and push until you are happy with your contribution
 
-Supported route filters are: `:match_header`, `:match_recipient`, and `:catch_all`
-Supported route actions are: `:forward`, and `:stop`
+  * Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
 
-Making Your Changes
-===================
+  * After making your changes, be sure to run the Mailgun tests using the `rspec spec` to make sure everything works.
 
-  * Fork the project (Github has really good step-by-step directions)
-  * Start a feature/bugfix branch
-  * Commit and push until you are happy with your contribution
-  * Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
-  * 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
-=========
+## TODO
 
   * Mailgun() is overwriting api key. api key is not persisting
   * Add skip and limit functionality
@@ -156,16 +175,18 @@ TODO
   * Stats?
   * Campaign?
 
-Authors
-=======
 
-  * Akash Manohar J (akash@akash.im)
-  * Scott Carleton (@scotterc) - for new functionality and major improvements.
-  * Sean Grove (sean@gobushido.com)
-  
+## Authors
+
+* Akash Manohar J ([@HashNuke](http://github.com/HashNuke))
+* Sean Grove ([@sgrove](http://github.com/sgrove))
+
+## Contrubutions
+
+* Yomi Colledge ([@baphled](http://github.com/baphled))
+* Scott Carleton ([@scotterc](http://github.com/scotterc)) - new functionality and improvements
+* Alan deLevie ([@adelevie](http://github.com/adelevie)) - Sending email
 
-License
-===================
-Released under the MIT license by CloudFuji. See LICENSE for more details.
+## License
 
-This is a fork of he Cloudfuji/mailgun repo.
+Released under the MIT license. See LICENSE for more details.

data/lib/mailgun.rb

@@ -12,6 +12,7 @@ require "mailgun/complaint"
 require "mailgun/log"
 require "mailgun/list"
 require "mailgun/list/member"
+require "mailgun/message"
 
 #require "startup"
 

data/lib/mailgun/base.rb

@@ -20,36 +20,40 @@ module Mailgun
     end
 
     # Returns an instance of Mailgun::Mailbox configured for the current API user
-    def mailboxes
-      @mailboxes ||= Mailgun::Mailbox.new(self)
+    def mailboxes(domain = Mailgun.domain)
+      Mailgun::Mailbox.new(self, domain)
+    end
+
+    def messages(domain = Mailgun.domain)
+      @messages ||= Mailgun::Message.new(self, domain)
     end
     
     def routes
       @routes ||= Mailgun::Route.new(self)
     end
     
-    def bounces
-      @bounces ||= Mailgun::Bounce.new(self)
+    def bounces(domain = Mailgun.domain)
+      Mailgun::Bounce.new(self, domain)
     end
     
-    def unsubscribes
-      @unsubscribes ||= Mailgun::Unsubscribe.new(self)
+    def unsubscribes(domain = Mailgun.domain)
+      Mailgun::Unsubscribe.new(self, domain)
     end
 
-    def complaints
-      @complaints ||= Mailgun::Complaint.new(self)
+    def complaints(domain = Mailgun.domain)
+      Mailgun::Complaint.new(self, domain)
     end
 
-    def log
-      @log ||= Mailgun::Log.new(self)
+    def log(domain=Mailgun.domain)
+      Mailgun::Log.new(self, domain)
     end
 
     def lists
-      @lists ||= Mailgun::List.new(self)
+      @lists ||= Mailgun::MailingList.new(self)
     end
 
-    def list_members
-      @list_members ||= Mailgun::List::Member.new(self)
+    def list_members(address)
+      Mailgun::MailingList::Member.new(self, address)
     end
   end
 
@@ -57,6 +61,7 @@ module Mailgun
   # 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))
     rescue => e
       error_message = nil

data/lib/mailgun/bounce.rb

@@ -1,34 +1,33 @@
 module Mailgun
+
+  # Interface to manage bounce lists
+  # Refer - http://documentation.mailgun.net/api-bounces.html for optional params to pass
   class Bounce
     # Used internally, called from Mailgun::Base
-    def initialize(mailgun)
+    def initialize(mailgun, domain)
       @mailgun = mailgun
+      @domain  = domain
     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
+    def list(options={})
+      Mailgun.submit(:get, bounce_url, options)["items"] || []
     end
 
-    def find(domain = Mailgun.domain, email)
-      Mailgun.submit :get, bounce_url(domain, email)
+    # Find bounce events for an email address
+    def find(email)
+      Mailgun.submit :get, bounce_url(email)
     end
 
-    def add(domain = Mailgun.domain, email)
-      Mailgun.submit :post, bounce_url(domain), :address => email
+    def add(email)
+      Mailgun.submit :post, bounce_url, :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}"
+    def bounce_url(address=nil)
+      "#{@mailgun.base_url}/#{@domain}/bounces#{'/' + address if address}"
     end
     
   end

data/lib/mailgun/complaint.rb

@@ -1,38 +1,39 @@
 module Mailgun
+
+  # Complaints interface. Refer to http://documentation.mailgun.net/api-complaints.html
   class Complaint
     # Used internally, called from Mailgun::Base
-    def initialize(mailgun)
+    def initialize(mailgun, domain)
       @mailgun = mailgun
+      @domain  = domain
     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
+    # List all the users who have complained
+    def list(options={})
+      Mailgun.submit(:get, complaint_url, options)["items"] || []
     end
-    
-    def find(domain = Mailgun.domain, email)
-      Mailgun.submit :get, complaint_url(domain, email)
+
+    # Find a complaint by email
+    def find(email)
+      Mailgun.submit :get, complaint_url(email)
     end
 
-    def add(domain=Mailgun.domain, email)
-      Mailgun.submit :post, complaint_url(domain), {:address => email}
+    # Add an email to the complaints list
+    def add(email)
+      Mailgun.submit :post, complaint_url, {:address => email}
     end
 
-    def remove(domain = Mailgun.domain, email)
-      Mailgun.submit :delete, complaint_url(domain, email)
+    # Removes a complaint by email
+    def destroy(email)
+      Mailgun.submit :delete, complaint_url(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}"
+    def complaint_url(address=nil)
+      "#{@mailgun.base_url}/#{@domain}/complaints#{'/' + address if address}"
     end
-    
+
   end
 end