chebyte/sendgrid_webapi

SendGrid WEB API gem for Rails 3 <img src=“https://secure.travis-ci.org/kylejginavan/sendgrid_webapi.png”/>¶ ↑

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 protected]", :foor => "bar")

• options are available here: 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 protected]", :foor => "bar")

• options are available here: 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 protected]", :foor => "bar")

• options are available here: 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 protected]", :foor => "bar")

• options are available here: 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 protected]", :foor => "bar")

client.unsubscribes.get(options)

client.unsubscribes.delete(:email => "[email protected]", :foor => "bar")

• options are available here: 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: 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: 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: 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 => "[email protected]")

client.profile.set_email(:email => "[email protected]")

• options are available here: docs.sendgrid.com/documentation/api/web-api/webapiprofile

Mail¶ ↑

This module allows you to send email.

client.mail.send(:to => "[email protected]", :subject => "test", :text => "some body", :from => "[email protected]")

• options are available here: 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 => "[email protected]", :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: 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 protected]")

• options are available here: 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 protected]")

• options are available here: 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 protected]")

• options are available here: 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 protected]")

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

client.sub_user.unsubscribes.delete(:user => "sub_user", :email => "[email protected]")

• options are available here: 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: 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: 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: 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: 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 => "[email protected]")

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: 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: 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: 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: 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: 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: 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: 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 protected]", :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 - github.com/chebyte