sendgrid_webapi 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+.rvmrc
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format nested

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.3
+  - 1.9.2
+  
+script: rake spec

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in send_grid.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,389 @@
+= SendGrid WEB API gem for Rails 3 {<img src="https://secure.travis-ci.org/kylejginavan/sendgrid_webapi.png"/>}[http://travis-ci.org/kylejginavan/sendgrid_webapi]
+
+SendGrid WEB API gem allow you to retrieve information such as statistics, bounces, spam reports, unsubscribes, send email and other information.
+
+== Rails 3 configuration
+
+In your Gemfile:
+
+    gem 'sendgrid_webapi'
+
+== Usage examples
+
+=== Creating client object:
+
+    client = SendGridWebApi::Client.new("user_name", "password")
+
+== Modules
+
+=== Bounces
+This module allows you to retrieve and delete email addresses that have bounced from emails that you've delivered.
+
+    client.bounces.get(options)
+
+    client.bounces.delete(:email => "email@example.com", :foor => "bar")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapibounces
+
+=== Blocks
+This module allows you to retrieve and delete email addresses that were blocked by their ISP. These emails are not suppressed and are just for information.
+
+    client.blocks.get(options)
+
+    client.blocks.delete(:email => "email@example.com", :foor => "bar")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapiblocks
+
+=== Invalid Email
+This module allows you to retrieve and delete email addresses that you've sent to that are invalid email addresses.
+
+    client.invalid_emails.get(options)
+
+    client.invalid_emails.delete(:email => "email@example.com", :foor => "bar")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapiinvalidemails
+
+=== Spam Report
+This module allows you to retrieve and delete email addresses that have marked your emails as SPAM.
+
+    client.spam.get(options)
+
+    client.spam.delete(:email => "email@example.com", :foor => "bar")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapispamreports
+
+=== Unsubscribes
+This module allows you to add, retrieve and delete email addresses that were unsubscribed from your emails.
+
+    client.unsubscribes.add(:email => "email@example.com", :foor => "bar")
+
+    client.unsubscribes.get(options)
+
+    client.unsubscribes.delete(:email => "email@example.com", :foor => "bar")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapiunsubscribes
+
+=== Parse Email
+This module allows you to add, edit, or delete your email parse settings.
+
+    client.parse_emails.add(:hostname => "www.example.com", :url => "www.domain.com/parse.php", :spam_check => 1)
+
+    client.parse_emails.get(options)
+
+    client.parse_emails.delete(:hostname => "www.example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapiparse
+
+=== Event Notification URL
+This module allows you to add, edit, or delete an event notification URL for your account.
+
+    client.event_notification.set(:url => "http://www.yourposturlhere.com")
+
+    client.event_notification.get(options)
+
+    client.event_notification.delete(options)
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/event-notification-url
+
+
+=== Stats
+This module allows you to retrieve statistical data on a range of metrics including requests, bounces, spam reports, categories, and others.
+
+    client.stats.get(options)
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/event-notification-url
+
+=== Profile
+This module allows you to retrieve and update your profile information such as credentials and email address.
+
+    client.profile.get(options)
+    
+    client.profile.set(options)
+    
+    client.profile.set_password(:password => "foo", :confirm_password => "foo")
+
+    client.profile.set_username(:username => "yournewusername@domain.com")
+    
+    client.profile.set_email(:email => "yournewusername@domain.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/webapiprofile
+
+
+=== Mail
+This module allows you to send email.
+  
+  client.mail.send(:to => "test@test.com", :subject => "test", :text => "some body", :from => "test@example.com")
+  
+* options are available here: http://docs.sendgrid.com/documentation/api/web-api/mail/
+
+== SubUser
+
+=== Creating client object:
+
+    client = SendGridWebApi::Client.new("user_name", "password")
+
+    client.sub_user
+
+
+== Modules
+
+=== Management SubUsers
+Retrieve/Create/Enable/Disable your subusers. Change a subuser email address and username.
+
+Create a sub_user
+
+    client.sub_user.management.add(:username => "sub_user", :website => "example.com", :password => "somepass", :confirm_password => "somepass", :first_name => "homero", :last_name => "simpson", :address => "555 anystreet", :city => "any city",:state => "CA", :zip => "91234", :email => "sub_user@example.com", :country => "US", :phone => "555-555")
+
+Get sub_users list
+
+    client.sub_user.management.get
+
+This prevents them from sending out emails with SendGrid
+
+    client.sub_user.management.disable(:user => "sub_user")
+
+Enable a subuser so they may start sending out emails again. This call will not enable website access
+
+    client.sub_user.management.enable(:user => "sub_user")
+
+Allow a subuser to login to the SendGrid.com website
+
+    client.sub_user.management.website_enable(:user => "sub_user")
+
+Disable a subuser to login to the SendGrid.com website
+
+    client.sub_user.management.website_disable(:user => "sub_user")
+
+Allows you to update your subusers profile information
+
+    client.sub_user.management.update(:user => "sub_user", :first_name => "change_named")
+  
+    client.sub_user.management.update_password(:user => "sub_user", :password => "somepassword", :confirm_password => "somepassword")
+
+    client.sub_user.management.update_username(:user => "sub_user", :username => "newusername")
+  
+    client.sub_user.management.update_email(:user => "sub_user", :email => "newemail")
+  
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/subusers/  
+
+=== Bounces
+This module allows you to manage bounce records of your subusers.
+
+    client.sub_user.bounces.get(:user => "sub_user")
+
+    client.sub_user.bounces.delete(:user => "sub_user", :email => "email@example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-subuser-api-v1/email-list-management/subuser-bounces/
+
+=== Invalid Email
+This module allows you to manage invalid emails of your subusers.
+
+    client.sub_user.invalid_emails.get(:user => "sub_user")
+
+    client.sub_user.invalid_emails.delete(:user => "sub_user", :email => "email@example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/subuser-invalid-emails/
+
+=== Spam Report
+This module allows you to manage spam reports of your subusers.
+
+    client.sub_user.spam.get(:user => "sub_user")
+
+    client.sub_user.spam.delete(:user => "sub_user", :email => "email@example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-subuser-api-v1/email-list-management/subuser-spam-reports/
+
+=== Unsubscribes
+This module allows you to manage unsubscribes of your subusers.
+
+    client.sub_user.unsubscribes.add(:user => "sub_user", :email => "email@example.com")
+
+    client.sub_user.unsubscribes.get(:user => "sub_user")
+
+    client.sub_user.unsubscribes.delete(:user => "sub_user", :email => "email@example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-subuser-api-v1/email-list-management/subusers-unsubscribes/
+
+=== Parse Email
+This module allows you to setup subusers parse settings
+
+    client.sub_user.parse_emails.add(:user => "sub_user", :hostname => "www.example.com", :url => "www.domain.com/parse.php", :spam_check => 1)
+
+    client.sub_user.parse_emails.get(:user => "sub_user")
+
+    client.sub_user.parse_emails.delete(:user => "sub_user", :hostname => "www.example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/parse-settings/
+
+=== Event Notification URL
+This module allows you to manage subusers event notification url.
+
+    client.sub_user.event_notification.set(:user => "sub_user", :url => "http://www.yourposturlhere.com")
+
+    client.sub_user.event_notification.get(:user => "sub_user")
+
+    client.sub_user.event_notification.delete(:user => "sub_user", :url => "http://www.yourposturlhere.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/event-notification-url/
+
+
+=== Stats
+This module allows you to see statistics regarding your subusers.
+
+    client.sub_user.stats.get(:user => "sub_user")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/statistics/
+
+=== Limits
+This module allows you to manage the rate of emails your subusers are able to send
+
+    client.sub_user.limits.get(:user => "sub_user")
+    
+    client.sub_user.limits.set_credits(:user => "sub_user", :credits=> "200", :period=> "daily")
+    
+    client.sub_user.limits.reset(:user => "sub_user", :credits=> "400", :period=> "daily")
+    
+    client.sub_user.limits.increment_credits(:user => "sub_user", :credits=> "400")
+    
+    client.sub_user.limits.decrement_credits(:user => "sub_user", :credits=> "400")
+
+To remove all limits from your sub_user
+
+    client.sub_user.limits.delete(:user => "sub_user")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/account-limits/
+
+
+=== Monitor Records
+Make sure your subusers arent sending out spam by getting a sample of their outgoing messages
+
+    client.sub_user.monitor_records.create(:name => "testmonitor", :frequency => 10000, :email => "test@test.com")
+    
+    client.sub_user.monitor_records.edit(:name => "testmonitor", :new_frequency => 10)
+    
+    client.sub_user.monitor_records.add_user(:user => "sub_user", :name => "testmonitor")
+    
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/monitor-records/
+
+=== IP Management
+List all IP addresses you have under your account and retrieve details about them
+
+To obtain a complete list of all IP's and which are free, taken or available. See params in the link
+
+    client.sub_user.ip_management.get(:user => "sub_user")
+
+To get the ip that is using your sub_user
+  
+    client.sub_user.ip_management.usage_ip(:user => "sub_user")
+    
+To assign one ip to your sub_user    
+  
+    client.sub_user.ip_management.assign_ip(:user => "sub_user", :ip => ["IP1", "IP2"])
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/ip-management/
+
+=== WhiteLabel
+Manage whitelabel settings for your subusers
+
+To retrieve a list of all whitelabel domains
+
+    client.sub_user.whitelabel.get(:user => "sub_user")
+
+To set a subusers whitelabel domain
+
+    client.sub_user.whitelabel.add(:user => "sub_user", :mail_domain => "email.sendgrid.com")
+
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/whitelabel/
+    
+
+=== IFrame
+Allow users to manage your subusers via iframe using our site
+
+    client.sub_user.iframe.get(:user => "sub_user")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/automatic-login/
+
+
+=== Parse Email
+This module allows you to setup subusers parse settings.
+
+    client.sub_user.parse_emails.add(:user => "sub_user", :hostname => "www.example.com", :url => "www.domain.com/parse.php", :spam_check => 1)
+
+    client.sub_user.parse_emails.get(:user => "sub_user")
+
+    client.sub_user.parse_emails.delete(:user => "sub_user", :hostname => "www.example.com")
+
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/parse-settings/
+
+
+=== Authentication
+This module allows you to check subusers password to see if its valid.
+
+    client.sub_user.auth.login(:user => "sub_user", :password => "somepass").
+    
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/authenticate-a-subuser/
+
+
+=== Apps
+This module allows you to setup subusers app settings.
+
+    client.sub_user.apps.list(:user => "sub_user")
+    
+    client.sub_user.apps.activate(:user => "sub_user", :name => "opentrack")
+
+    client.sub_user.apps.deactivate(:user => "sub_user", :name => "opentrack")
+    
+    client.sub_user.apps.current_settings(:user => "sub_user", :name => "eventnotify")
+    
+    client.sub_user.apps.customize(:user => "sub_user", :name => "eventnotify", :processed => "0", :dropped => "1", :deferred => "1", :delivered => "0", :bounce => "1", :click => "1", :open => "1", :unsubscribe => "1", :spamreport => "1", :url => "http://someurl.com/listener"))    
+    
+* options are available here: http://docs.sendgrid.com/documentation/api/customer-subuser-api/customer-api/filter-apps/
+
+
+== Helper
+
+=== Create Sub User
+this helper allows you to create a sub_user and enable apps that you want, passing a array with the sub_user data
+
+define the data
+
+    user_hash = {:website => "someurl.com", :password => "somepass", :confirm_password => "somepass",
+               :first_name => "home", :last_name => "simpson", :address => "555 anystreet", :city =>  "any city",
+               :state => "CA" , :zip => "91234", :email => "email@email.com", :country => "US", :phone => "555-555"}
+  
+    apps = { :opentrack => {:name => "eventnotify", :processed => "0", :dropped => "1", :deferred => "1",
+                          :delivered => "0", :bounce => "1", :click => "1", :open => "1", :unsubscribe => "1", :spamreport => "1", 
+                          :url => "https://agencieshq.com/sendgrid/v1/listener"},
+           :clicktrack => {:enable_text => "1"},
+           :opentrack => {}
+    }
+
+    users = {"username" => {:account => user_hash, :applications => apps, :assigned_ips => ["IP"]}}
+    
+call the helper
+    
+    create_sub_user_account("sendgrid user", "sendgrid pass", users)
+
+=== Run SendGrid Query
+this helper allows you run a sengrid request and raise if it doesn't return successfull
+
+    run_sendgrid_query("sendgrid user", "sendgrid pass") do
+      #some sendgrid request
+      @client.sub_user.apps.activate(:user => "user", :name => "twitter")
+    end
+
+== HTTP Return codes
+
+=== 4xx
+
+The API call had an error in the parameters. The gem will return ApiException raise.
+
+=== 5xx
+
+The API call was unsuccessful. The gem will return ApiException raise.
+
+== CONTRIBUTORS:
+
+* Kyle J. Ginavan.
+* Mauro Torres - http://github.com/chebyte

data/Rakefile

@@ -0,0 +1,5 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+Bundler::GemHelper.install_tasks
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/base.rb

@@ -0,0 +1,41 @@
+module SendGridWebApi
+  autoload :Faraday, 'middlewares/sendgrid_response'
+  
+  class Base
+    attr_accessor :api_user, :api_key
+
+    def initialize api_user, api_key
+      @api_user = api_user
+      @api_key  = api_key
+    end
+    
+    def make_request_url url, options
+      "#{url}?#{builder_options(options)}"
+    end
+
+    def builder_options options
+      options.merge!(:api_user => @api_user, :api_key => @api_key)
+      to_query(options)
+    end
+
+    def query_api url, options
+      session.get(make_request_url(url, options)).body
+    end
+
+    def query_post_api url, options
+      builder_options(options)
+      session.post(url, builder_options(options)).body
+    end
+    
+    def to_query(options)
+      Faraday::Utils.build_nested_query(options)
+    end
+
+    def session
+      @connection ||= ::Faraday.new base_url do |conn|
+        conn.use Faraday::Response::SendGridWebApi
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/helper.rb

@@ -0,0 +1,36 @@
+module SendGridWebApi::Helper
+  extend self  
+  
+  def run_sendgrid_query(username, password)
+    @client = SendGridWebApi::Client.new(username, password)
+    result = yield
+    raise "it returns the following errors: #{result}" unless result.eql?({"message"=>"success"})
+  end
+
+  ###this accepts subuser array
+  def create_sub_user_account(username, password, users)
+    users.each do |user, data|
+      #load users
+      run_sendgrid_query(username, password) do
+        @client.sub_user.management.add(data[:account].merge!(:username => user))
+      end
+            
+      #active user for send email
+      run_sendgrid_query(username, password){@client.sub_user.management.enable(:user => user)}
+    
+      #assign ip
+      unless data[:assigned_ips].empty?
+        run_sendgrid_query(username, password){@client.sub_user.ip_management.assign_ip :user => user, :ip => data[:assigned_ips]}
+      end
+      #load apps
+      unless data[:applications].empty?
+        data[:applications].each do |app_name, options|
+          run_sendgrid_query(username, password){@client.sub_user.apps.activate(:user => user, :name => app_name)}
+          unless options.empty?
+            run_sendgrid_query(username, password){@client.sub_user.apps.customize(options.merge!(:user => user, :name => app_name))}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/middlewares/sendgrid_response.rb

@@ -0,0 +1,42 @@
+require 'json' unless defined?(JSON)
+
+#api exception
+class ApiException < StandardError;end
+class AuthenticationError < StandardError;end
+
+module Faraday
+  class Response::SendGridWebApi < Response::Middleware
+        
+    def error_message(result)
+      if result[/^[a-z ]+$/i]
+        error_msg = result
+      else
+        error_msg = JSON.parse(result)["error"] || JSON.parse(result)["errors"]
+      end
+      error_msg.to_s
+    end
+
+    def parse_body(body)
+      JSON.parse(body)
+    end
+
+    def check_status(env)
+      status = env[:status].to_s
+      if  status == "403" || status == "401"
+        raise AuthenticationError.new(error_message(env[:body]))
+      elsif status =~ /^5/
+        raise ApiException.new("The API call was unsuccessful. You should retry later.")
+      elsif status =~ /^4/
+        raise ApiException.new(error_message(env[:body]))
+      end
+    end
+
+    def call(env)
+      @app.call(env).on_complete do
+        check_status(env)
+        env[:body] = parse_body(env[:body])
+      end
+    end
+    
+  end
+end

data/lib/sendgrid_webapi.rb

@@ -0,0 +1,5 @@
+require 'faraday'
+require 'base'
+require 'helper'
+require 'webapi_client'
+require 'subuser_client'

data/lib/sub_user/apps.rb

@@ -0,0 +1,31 @@
+module SendGridWebApi::SubUserModules
+  class App < SendGridWebApi::SubUser
+    APP_URL = "apiv2/customer.apps.json"
+    
+    def list options = {}
+      options.merge!({:task => "getavailable"}) unless options[:task]
+      query_api(APP_URL, options)
+    end
+
+    def activate options = {}
+      options.merge!({:task => "activate"}) unless options[:task]
+      query_api(APP_URL, options)
+    end
+
+    def deactivate options = {}
+      options.merge!({:task => "deactivate"}) unless options[:task]
+      query_api(APP_URL, options)
+    end
+
+    def current_settings options = {}
+      options.merge!({:task => "getsettings"}) unless options[:task]
+      query_api(APP_URL, options)
+    end
+
+    def customize options = {}
+      options.merge!({:task => "setup"}) unless options[:task]
+      query_post_api(APP_URL, options)
+    end
+
+  end
+end

data/lib/sub_user/auth.rb

@@ -0,0 +1,10 @@
+module SendGridWebApi::SubUserModules
+  class Auth < SendGridWebApi::SubUser
+    
+    def login options = {}
+      auth_url = "apiv2/customer.auth.json"
+      query_api(auth_url, options)
+    end
+        
+  end
+end

data/lib/sub_user/bounces.rb

@@ -0,0 +1,15 @@
+module SendGridWebApi::SubUserModules
+  class Bounce < SendGridWebApi::SubUser
+    BOUNCE_URL = "api/user.bounces.json"
+    
+    def get options = {}
+      options.merge!({:task => "get"}) unless options[:task]
+      query_api(BOUNCE_URL, options)
+    end
+  
+    def delete options = {}
+      options.merge!({:task => "delete"}) unless options[:task]
+      query_api(BOUNCE_URL, options)    
+    end
+  end
+end

data/lib/sub_user/event_notification.rb

@@ -0,0 +1,20 @@
+module SendGridWebApi::SubUserModules
+  class EventNotification < SendGridWebApi::SubUser
+    EVENT_URL = "apiv2/customer.eventposturl.json"
+    
+    def get options = {}
+      options.merge!({:task => "get"}) unless options[:task]
+      query_api(EVENT_URL, options)
+    end
+
+    def set options = {}
+      options.merge!({:task => "set"}) unless options[:task]
+      query_api(EVENT_URL, options)
+    end
+
+    def delete options = {}
+      options.merge!({:task => "delete"}) unless options[:task]
+      query_api(EVENT_URL, options)
+    end
+  end  
+end

data/lib/sub_user/iframe.rb

@@ -0,0 +1,8 @@
+module SendGridWebApi::SubUserModules
+  class Iframe < SendGridWebApi::SubUser
+    def get options = {}
+      iframe_url = "apiv2/customer.geturl.json"
+      query_api(iframe_url, options)
+    end
+  end  
+end

data/lib/sub_user/invalid_emails.rb

@@ -0,0 +1,15 @@
+module SendGridWebApi::SubUserModules
+  class InvalidEmail < SendGridWebApi::SubUser
+    INVALID_EMAILS_URL = "apiv2/customer.invalidemails.json"
+    
+    def get options = {}
+      options.merge!({:task => "get"}) unless options[:task]
+      query_api(INVALID_EMAILS_URL, options)
+    end
+
+    def delete options = {}
+      options.merge!({:task => "delete"}) unless options[:task]
+      query_api(INVALID_EMAILS_URL, options)    
+    end
+  end
+end

data/lib/sub_user/ip_management.rb

@@ -0,0 +1,23 @@
+module SendGridWebApi::SubUserModules
+  class IpManagement < SendGridWebApi::SubUser
+    def get options = {}
+      options.merge!({:list => "all"}) unless options[:list]
+      ip_management_get_url = "apiv2/customer.ip.json"
+      query_api(ip_management_get_url, options)
+    end
+
+    def usage_ip options = {}
+      options.merge!({:task => "list"}) unless options[:task]
+      ip_management_get_url = "apiv2/customer.sendip.json"
+      query_api(ip_management_get_url, options)
+    end
+
+    def assign_ip options = {}
+      options.merge!({:task => "append"}) unless options[:task]
+      options.merge!({:set  => "specify"}) unless options[:set]
+      ip_management_get_url = "apiv2/customer.sendip.json"
+      query_api(ip_management_get_url, options)
+    end
+
+  end
+end