SendgridToolkit is a Ruby wrapper for the SendGrid Web API
SendgridToolkit provides a class for interacting with each of the following SendGrid API modules:
- Bounces
- InvalidEmails
- Lists
- ListEmails
- SpamReports
- Statistics
- Unsubscribes
Consuming the SendGrid API is as simple as instantiating a class and making the call:
unsubscribes = SendgridToolkit::Unsubscribes.new("username", "api_key")
unsubscribes.add :email => "[email protected]"
Two lines, and voila!
Common actions are documented below under each module. For more details, visit the SendGrid Web API Documentation
- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
- Fork the project
- 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 I don't break it in a future version unintentionally.
- Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Big thanks to James Brennan for refactoring old code and writing the Bounces, InvalidEmails and SpamReports modules.
Via rubygems.org:
$ gem install sendgrid_toolkit
Or add it to your Gemfile
gem 'sendgrid_toolkit', '>= 1.1.1'
Setting your API user and key once globally for all API access:
SendgridToolkit.api_user = "bob"
SendgridToolkit.api_key = "x123y"
If you do this when you create individual API objects you will not need to pass the api_user
or api_key
bounces = SendgridToolkit::Bounces.new
The bounces module provides access to all of your bounces.
Instantiate the Bounces object:
bounces = SendgridToolkit::Bounces.new(api_user, api_key)
Retrieve bounces:
all_bounces = bounces.retrieve
all_bounces
will be an array of hashes, each of which contains the following keys:
email
: the recipient's email addressstatus
: the status of emailreason
: the reason for the bounce, as specified by the recipient's email server
Get the timestamp of each bounce:
all_bounces = bounces.retrieve_with_timestamps
Each hash in all_bounces
will now contain a created
key, which holds a Ruby Time object.
If you believe an email address will no longer bounce and would like SendGrid to deliver future emails to that address, you may delete the Bounce entry:
bounces.delete :email => "[email protected]"
The InvalidEmails module provides access to all of your email addresses.
Instantiate the InvalidEmails object:
invalid_emails_obj = SendgridToolkit::InvalidEmails.new(api_user, api_key)
Retrieve invalid emails:
invalid_emails = invalid_emails_obj.retrieve
invalid_emails
will be an array of hashes, each of which contains the following keys:
email
: the recipient's email addressreason
: the reason the email address is believed to be invalid
Get the timestamp that each email was determined to be invalid:
invalid_emails = invalid_emails_obj.retrieve_with_timestamps
Each hash in invalid_emails
will now contain a created
key, which holds a Ruby Time object.
If you believe a once-invalid email address is now valid and would like SendGrid to deliver future emails to that address, you may delete the InvalidEmail entry:
invalid_emails.delete :email => "[email protected]"
The Lists module lets you manage your recipient lists associated with the marketing email feature via the marketing emails API.
Instantiate the Lists object:
lists_obj = SendgridToolkit::Lists.new(api_user, api_key)
Retrieve lists:
lists = lists_obj.get
lists
will be an array of hashes, each of which contains a list
key, which contain the name of the lists.
Create list:
response = lists_obj.add :list => 'new_list_name'
response
will be a hash containing a message
key, which contains either success
or error
. If it is error, it will additionally contain the errors
key, which contains an array of error messages.
When creating a list you can also specify a custom column name for the name
associated with email addresses.
Example:
response = lists_obj.add :list => 'new_list_name', :name => 'customer_name'
Edit list:
response = lists_obj.edit :list => 'some_old_name', :new_list => 'some_new_name'
response
will be a hash containing a message
key, which contains either success
or error
. If it is error, it will additionally contain the errors
key, which contains an array of error messages.
Delete list:
response = lists_obj.delete :list => 'some_list_name'
response
will be a hash containing a message
key, which contains either success
or error
. If it is error, it will additionally contain the errors
key, which contains an array of error messages.
The ListEmails module lets you manage your emails in your recipient lists associated with the marketing email feature via the marketing emails API.
Instantiate the ListEmails object:
list_emails_obj = SendgridToolkit::ListEmails.new(api_user, api_key)
Get emails:
list_emails = list_emails_obj.get :list => 'some_list_name'
list_emails
will be an array of hashes, each of which contains the following keys:
email
: The email address of the recipientname
: The name of the recipient. This key may be different if you changed the column name
Add email:
response = list_emails_obj.add :list => 'some_list_name', :data => { :email => '[email protected]', :name => 'some_new_person'}
Add multiple emails:
This is limited to 1,000 entries by the API
response = list_emails_obj.add :list => 'some_list_name', :data => [
{ :email => '[email protected]', :name => 'some_new_person1'},
{ :email => '[email protected]', :name => 'some_new_person2'},
{ :email => '[email protected]', :name => 'some_new_person3'}
]
response
will be a hash containing a inserted
key, which contains the number of emails inserted into the list.
Remove email:
response = list_emails_obj.delete :list => 'some_list_name', :email => '[email protected]'
response
will be a hash containing a removed
key, which contains the number of emails removed from the list.
The Mail module lets you send email via the web API.
Call :send_mail
(chosen to avoid conflicts with Object:send) with the standard parameters:
SendgridToolkit::Mail.new(api_user, api_key).send_mail :to => "[email protected]", :from => "[email protected]", :subject => "Some Subject", :text => "Some text"
The complete set of "x-smtpapi" options are also supported. You can use them like:
SendgridToolkit::Mail.new(api_user, api_key).send_mail :to => "[email protected]", :from => "[email protected]", :subject => "Some Subject", :text => "Some text", "x-smtpapi" => {:category => "Retention"}
The SpamReports module provides access to all email addresses that have reported you for spam.
Instantiate the SpamReports object:
spam_reports_obj = SendgridToolkit::SpamReports.new(api_user, api_key)
Retrieve spam reports:
spam_reports = spam_reports_obj.retrieve
spam_reports
will be an array of hashes, each of which contains an email
key, indicating the email address that reported you for spam.
Get the timestamp of each spam report:
spam_reports = spam_reports_obj.retrieve_with_timestamps
Each hash in spam_reports
will now contain a created
key, which holds a Ruby Time object.
If you believe a user will no longer consider your content to be spam, you may delete the SpamReport entry:
spam_reports.delete :email => "[email protected]"
The statistics module provides access to all of your email statistics.
Instantiate the Statistics object:
statistics = SendgridToolkit::Statistics.new(api_user, api_key)
Retrieve statistics:
stats = statistics.retrieve
stats
will be an array of hashes, each of which contains the following keys:
date
: The date to which the statistics in this hash refer torequests
: The number of emails you requested be sentdelivered
: The number of emails delivered to email serversbounces
: The number of emails which were rejected by email serversrepeat_bounces
: The number of emails which bounced repeatedlyblocked
: The number of emails which were suppressed by SendGridspam_drop
: The number of emails which SendGrid dropped as spamclicks
: The number of clicks on links in your emailsunique_clicks
: The number of users who clicked on a link in your emailopens
: The number of users who opened your emailunique_opens
: The number of users who opened your emailspamreports
: The number of users who have reported your emails as spamunsubscribes
: The number of unsubscribes your messages have received (if you are using the subscription tracking apprepeat_unsubscribes
: The number of repeat unsubscribes (if a user unsubscribed, resubscribed and then unsubscribed again)bounces
: The number of emails that bounced
To narrow your retrieval to the past 5 days:
stats = statistics.retrieve :days => 5
To narrow your retrieval to emails within the last month but before one week ago:
stats = statistics.retrieve :start_date => 1.month.ago, :end_date => 1.week.ago
To narrow your search to a particular category (applicable only if you use this SendGrid feature):
stats = statistics.retrieve :category => "NameOfYourCategory"
Note: You may combine a category query with other options, i.e.:
stats = statistics.retrieve :category => "NameOfYourCategory", :days => 5
Receive your all-time statistics:
stats = statistics.retrieve_aggregate
stats
will be a single hash containing all of the aforementioned keys except date
.
If you use SendGrid's category feature, you can list your categories:
cats = statistics.list_categories
cats
is an array of hashes, each of which has a category
key that holds the name of a category.
The unsubscribes module manages your list of unsubscribed email addresses.
Instantiate the Unsubscribes object:
unsubscribes = SendgridToolkit::Unsubscribes.new(api_user, api_key)
List everybody who has unsubscribed from your emails with:
listing = unsubscribes.retrieve
listing
will be an array of hashes, each of which has an email
key.
Get the timestamp when each user unsubscribed:
listing = unsubscribes.retrieve_with_timestamps
Each hash in listing
will now contain a created
key, which holds a Ruby Time object.
Unsubscribe a user from your SendGrid email:
unsubscribes.add :email => "[email protected]"
SendgridToolkit will throw UnsubscribeEmailAlreadyExists
if the email you specified is already on the list
Remove a user from your unsubscribe list:
unsubscribes.delete :email => "email@that_is.unsubscribed"
SendgridToolkit will throw UnsubscribeEmailDoesNotExist
if the email you specified is not on the list
Each class is initialized with api_user
and api_key
parameters. api_user
is your SendGrid account email address, and api_key
is your SendGrid password.
If you don't supply api_user
or api_key
, SendgridToolkit will look for the SMTP_USERNAME
or SMTP_PASSWORD
environment variables. If they are not found, SendgridToolkit will throw NoAPIKeySpecified
or NoAPIUserSpecified
, depending on what you omitted.
If authentication fails during an API request, SendgridToolkit throws AuthenticationFailed
.
API requests are made and responses are received in JSON. All requests are made as POSTs unless noted otherwise (some of SendGrid's examples are via GET, but they support POST)
Each class takes a final options parameter in the form of a hash. You may use this parameter to pass additional options to the SendGrid API. For example, let's say you are using the unsubscribes function:
unsubscribes = SendgridToolkit::Unsubscribes.new(api_user, api_key)
listing = unsubscribes.retrieve
If SendGrid were to add a only_verified
option to this API call, you could call:
listing = unsubscribes.retrieve :only_verified => true
to make use of it.
In addition to unit tests, SendgridToolkit comes with a limited suite of "webconnect" tests that will actually hit SendGrid's servers and perform various actions for purposes of real-world testing. In order to use these tests, you must:
- Create a test account with SendGrid and store the credentials in
TEST_SMTP_USERNAME
andTEST_SMTP_PASSWORD
environment variables. This is so that actions are performed on a test account and not your real SendGrid account. If you forget, don't worry -- the tests will fail but they will not fall back on the account that usesSMTP_USERNAME
andSMTP_PASSWORD
. - Change "xit" it "it" on the tests you wish to run.
Running rspec
out of the box will run the standard suite of tests (all network access is stubbed out).