= 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] {<img src="https://badge.fury.io/rb/sendgrid_webapi.png" alt="Gem Version" />}[http://badge.fury.io/rb/sendgrid_webapi] {<img src="https://codeclimate.com/github/kylejginavan/sendgrid_webapi.png" />}[https://codeclimate.com/github/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:

for sendgrid v3 support

    gem 'sendgrid_webapi', '0.0.3'

for sendgrid v2 support

    gem 'sendgrid_webapi', '0.0.2'

== Usage examples

=== Creating client object:

    client = SendGridWebApi::Client.new("apikey")

== Modules

=== Bounces
This module allows you to retrieve and delete email addresses that have bounced from emails that you've delivered.

    # Retrieve all of your bounces.
    # A maximum of 500 bounces will be returned per query.
    # You can use the offset and limit parameters to retrieve more or less than 500 results.
    # You can use the start_time and end_time parameters to filter by time frames.
    # * https://docs.sendgrid.com/api-reference/bounces-api/retrieve-all-bounces
    # i.e client.bounces.get({ "on_behalf_of": "sub_user_email"})
    # i.e using limit/offset: client.bounces.get({ on_behalf_of: "sub_user_email", limit: 100, offset: 1 })
    client.bounces.get (options)

    # This method will delete all bounces from the given email.
    # * https://docs.sendgrid.com/api-reference/bounces-api/delete-a-bounce
    # i.e: client.bounces.delete( { on_behalf_of: "sub_user_email", email: "email@to.delete" })
    client.bounces.delete(options)

    # Deprecated: Count is no longer supported on SendGrid v3.
    # As an alternative, SendGrid recommends to query depending on time frames since `get` limit is 500.
    # Deprecated, under the hood it's doing a get an returning the count
    client.blocks.count

* options are available here: https://docs.sendgrid.com/api-reference/bounces-api

=== 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.
    # Retrieve all of your blocks.
    # A maximum of 500 blocks will be returned per query.
    # You can use the offset and limit parameters to retrieve more or less than 500 results.
    # You can use the start_time and end_time parameters to filter by time frames.
    #* https://docs.sendgrid.com/api-reference/blocks-api/retrieve-all-blocks
    # i.e: client.blocks.get({ on_behalf_of: "sub_user_email", limit: 100, offset: 1 })
    client.blocks.get(options)
    

    # This method will delete all blocks from the given email
    # * https://docs.sendgrid.com/api-reference/blocks-api/delete-blocks
    # i.e: client.blocks.delete( { on_behalf_of: "sub_user_email", email: "email@example.com" })
    client.blocks.delete(options)
    
    # Deprecated: Count is no longer supported on SendGrid v3.
    # As an alternative, SendGrid recommends to query depending on time frames since `get` limit is 500.
    client.blocks.count

* options are available here: https://docs.sendgrid.com/api-reference/blocks-api

=== Invalid Email
This module allows you to retrieve and delete email addresses that you've sent to that are invalid email addresses.
    # Retrieve a list of all invalid email addresses.
    # You can use the offset and limit parameters to retrieve a custom number of results.
    # You can use the start_time and end_time parameters to filter by time frames.
    # * https://docs.sendgrid.com/api-reference/invalid-e-mails-api/retrieve-all-invalid-emails
    # i.e: client.invalid_emails.get({ on_behalf_of: "sub_user_email", limit: 100, offset: 1 })
    client.invalid_emails.get(options)

    # This method will delete all invalid_emails from the given email
    # * https://docs.sendgrid.com/api-reference/invalid-e-mails-api/delete-a-specific-invalid-email
    # i.e: client.invalid_emails.delete( { on_behalf_of: "sub_user_email", email: "email@example.com" })
    client.invalid_emails.delete(options)

* options are available here: https://docs.sendgrid.com/api-reference/invalid-e-mails-api

=== Spam Report
This module allows you to retrieve and delete email addresses that have marked your emails as SPAM.
    # Retrieve a list of all spam reports.
    # You can use the offset and limit parameters to retrieve a custom number of results.
    # You can use the start_time and end_time parameters to filter by time frames.
    # * https://docs.sendgrid.com/api-reference/spam-reports-api/retrieve-all-spam-reports
    # i.e: client.spam.get({ on_behalf_of: "sub_user_email", limit: 100, offset: 1 })
    client.spam.get(options)

    # This method will delete all spam_reports from the given email.
    # * https://docs.sendgrid.com/api-reference/spam-reports-api/delete-a-specific-spam-report
    # i.e: client.spam.delete( { on_behalf_of: "sub_user_email", email: "email@example.com" })
    client.spam.delete(options)

* options are available here: http://sendgrid.com/docs/API_Reference/Web_API/spam_reports.html

=== Unsubscribes
This module allows you to add, retrieve and delete email addresses that were unsubscribed from your emails.

    
    # Example @email_client.send(:unsubscribes).delete( { email: "test@example.com", on_behalf_of: "sub_user_email" })
    # * https://docs.sendgrid.com/api-reference/suppressions-global-suppressions/add-recipient-addresses-to-the-global-suppression-group
    # i.e: client.unsubscribes.add( { on_behalf_of: "sub_user_email, recipient_emails: ["test@example.com"] })
    client.unsubscribes.add(options)

    # Retrieve a list of all email address that are globally suppressed.
    # You can use the offset and limit parameters to retrieve a custom number of results.
    # You can use the start_time and end_time parameters to filter by time frames.
    # * https://docs.sendgrid.com/api-reference/suppressions-global-suppressions/retrieve-all-global-suppressions
    # client.unsubscribes.get({ on_behalf_of: "sub_user_email", limit: 100, offset: 1 })
    client.unsubscribes.get(options)


    # This method will delete all unsubscribes from the given email
    # * https://docs.sendgrid.com/api-reference/suppressions-global-suppressions/delete-a-global-suppression
    # i.e: client.unsubscribes.delete( { on_behalf_of: "sub_user_email", email: "email@example.com" })
    client.unsubscribes.delete(options)

* options are available here: http://sendgrid.com/docs/API_Reference/Web_API/unsubscribes.html

=== Parse Email
This module allows you to add, edit, or delete your email parse settings.

    client.parse_email.add(:hostname => "www.example.com", :url => "www.domain.com/parse.php", :spam_check => 1)

    client.parse_email.get(options)

    client.parse_email.delete(:hostname => "www.example.com")

* options are available here: http://sendgrid.com/docs/API_Reference/Web_API/parse_settings.html

=== 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://sendgrid.com/docs/API_Reference/Webhooks/event.html


=== 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://sendgrid.com/docs/API_Reference/Web_API/Statistics/index.html

=== 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://sendgrid.com/docs/API_Reference/Web_API/profile.html


=== 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://sendgrid.com/docs/Code_Examples/ruby.html

== SubUser

=== Creating client object:

    client = SendGridWebApi::Client.new("apikey")

    client.sub_user


== Modules

=== Management SubUsers
Retrieve/Create/Enable/Disable your subusers. Change a subuser email address and username. Docs can be found here: http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/index.html

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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/subusers.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/subuser_bounces.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/invalid_emails.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/subuser_spam_reports.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/subuser_unsubscribes.html

=== Parse Email
This module allows you to setup subusers parse settings

    client.sub_user.parse_email.add(:user => "sub_user", :hostname => "www.example.com", :url => "www.domain.com/parse.php", :spam_check => 1)

    client.sub_user.parse_email.get(:user => "sub_user")

    client.sub_user.parse_email.delete(:user => "sub_user", :hostname => "www.example.com")

* options are available here: http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/parse_settings.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/event_notification_url.html


=== Stats
This module allows you to see statistics regarding your subusers.

    client.sub_user.stats.get(:user => "sub_user")

* options are available here: http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/statistics.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/account_limits.html


=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/monitor_records.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/ip_management.html

=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/whitelabel.html


=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/automatic_login.html


=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/authenticate_a_subuser.html


=== 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://sendgrid.com/docs/API_Reference/Customer_Subuser_API/apps.html


=== Apikey
This module allows you to manage apikeys

    client.apikey.management.get

    client.apikey.management.get({ on_behalf_of: "SUB_USERNAME" })

    client.apikey.management.get({ apikey_id: "APIKEY_ID" })

    client.apikey.management.get({ on_behalf_of: "SUB_USERNAME" })

    client.apikey.management.create({ "name" => "APIKEY NAME", "scopes" => ["mail.send"] })

    client.apikey.management.create({ on_behalf_of: "SUB_USERNAME", "name" => "APIKEY NAME", "scopes" => ["mail.send"] })

    client.apikey.management.update("APIKEY_ID", { "name" => "NEW APIKEY NAME"})

    client.apikey.management.update("APIKEY_ID", { on_behalf_of: "SUB_USERNAME", "name" => "NEW APIKEY NAME"})

    client.apikey.management.delete("APIKEY_ID")

    client.apikey.management.delete("APIKEY_ID", { on_behalf_of: "SUB_USERNAME" })

* options are available here: https://sendgrid.com/docs/api-reference/

== 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