= SendGrid WEB API gem for Rails 3
{
}[http://travis-ci.org/kylejginavan/sendgrid_webapi] {
}[http://badge.fury.io/rb/sendgrid_webapi] {
}[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
=== 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
=== 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)
=== 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)
=== 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)
=== 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")
=== 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)
=== 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)
=== 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")
=== Mail This module allows you to send email.
client.mail.send(:to => "test@test.com", :subject => "test", :text => "some body", :from => "test@example.com")
== 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")
=== 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")
=== 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")
=== 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")
=== 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")
=== 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")
=== 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")
=== Stats This module allows you to see statistics regarding your subusers.
client.sub_user.stats.get(:user => "sub_user")
=== 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")
=== 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")
=== 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"])
=== 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")
=== IFrame Allow users to manage your subusers via iframe using our site
client.sub_user.iframe.get(:user => "sub_user")
=== Authentication This module allows you to check subusers password to see if its valid.
client.sub_user.auth.login(:user => "sub_user", :password => "somepass").
=== 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"))
=== 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" })
== 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:
FAQs
Unknown package
We found that sendgrid_webapi demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.