This Gem allows you to quickly and easily send emails through SendGrid's Web API using native Ruby.
You can read our official documentation on the Web API's Mail feature here.
Add this line to your application's Gemfile:
gem 'sendgrid-ruby'
And then execute:
$ bundle
Or install it yourself as:
$ gem install sendgrid-ruby
Create a new client with your SendGrid Username and Password.
require 'sendgrid-ruby'
# As a hash
client = SendGrid::Client.new(api_user: 'SENDGRID_USERNAME', api_key: 'SENDGRID_PASSWORD')
# Or as a block
client = SendGrid::Client.new do |c|
c.api_user = 'SENDGRID_USERNAME'
c.api_key = 'SENDGRID_PASSWORD'
endCreate a new Mail object and send:
mail = SendGrid::Mail.new do |m|
m.to = '[email protected]'
m.from = '[email protected]'
m.subject = 'Hello world!'
m.text = 'I heard you like pineapple.'
end
puts client.send(mail)
# {"message":"success"}You can also create a mail object with a hash:
client.send(SendGrid::Mail.new(to: '[email protected]', from: '[email protected]', subject: 'Hello world!', text: 'Hi there!', html: '<b>Hi there!</b>'))
# {"message":"success"}Attachments can be added to a mail object with the add_attachment method. The first parameter is the path to the file, the second (optional) parameter is the desired name of the file. If a file name is not provided, it will use the original filename.
mail.add_attachment('/tmp/report.pdf', 'july_report.pdf')params = {
:to,
:to_name,
:from,
:from_name,
:subject,
:text,
:html,
:cc,
:bcc,
:reply_to,
:date,
:smtpapi,
:attachments
}Params can be set in the usual Ruby ways, including a block or a hash.
mail = SendGrid::Mail.new do |m|
m.to = '[email protected]'
m.from = '[email protected]'
end
client.send(SendGrid::Mail.new(to: '[email protected]', from: '[email protected]'))Using the :to param, we can pass a single email address as a string, or an array of email address strings.
mail = SendGrid::Mail.new
mail.to = '[email protected]'
# or
mail.to = ['Example Dude <[email protected]>', '[email protected]']
# or
mail.to = ['[email protected]', '[email protected]']mail = SendGrid::Mail.new
mail.from = '[email protected]'As with :to, :cc can take a single string or an array of strings.
mail = SendGrid::Mail.new
mail.cc = ['[email protected]', '[email protected]']As with :to and :cc, :bcc can take a single string or an array of strings.
mail = SendGrid::Mail.new
mail.bcc = ['[email protected]', '[email protected]']mail = SendGrid::Mail.new
mail.subject = 'This is a subject string'Using the :text param allows us to add plain text to our email body.
mail = SendGrid::Mail.new
mail.text = 'WHATTUP KITTY CAT!?'Using the :html param allows us to add html content to our email body.
mail = SendGrid::Mail.new
mail.html = '<html><body>Stuff in here, yo!</body></html>'To utilize the X-SMTPAPI header, we have directly integrated the smtpapi-ruby gem.
You can directly generate an x-smtpapi add_to header instead of using to :to param. Please note, this will override all params.
mail = SendGrid::Mail.new
mail.smtpapi.add_to('[email protected]')
mail.smtpapi.add_to('[email protected]')mail.smtpapi.set_tos(['[email protected]', '[email protected]'])mail = SendGrid::Mail.new
mail.smtpapi.add_substitution('keep', array('secret')) # sub = {keep: ['secret']}
mail.smtpapi.add_substitution('other', array('one', 'two')) # sub = {keep: ['secret'], other: ['one', 'two']}mail = SendGrid::Mail.new
mail.smtpapi.set_substitutions({'keep' => 'secret'}) # sub = {keep: ['secret']}mail = SendGrid::Mail.new
mail.smtpapi.add_unique_arg('cat', 'dogs')mail = SendGrid::Mail.new
mail.smtpapi.set_unique_args({'cow' => 'chicken'})
mail.smtpapi.set_unique_args({'dad' => 'proud'})mail = SendGrid::Mail.new
mail.smtpapi.add_category('tactics') # category = ['tactics']
mail.smtpapi.add_category('advanced') # category = ['tactics', 'advanced']mail = SendGrid::Mail.new
mail.smtpapi.set_categories(['tactics', 'advanced']) # category = ['tactics', 'advanced']mail = SendGrid::Mail.new
mail.smtpapi.add_section('-charge-', 'This ship is useless.'])
mail.smtpapi.add_section('-bomber-', 'Only for sad vikings.'])mail = SendGrid::Mail.new
mail.smtpapi.set_sections({'-charge-' => 'This ship is useless.'})mail = SendGrid::Mail.new
mail.smtpapi.add_filter('footer', 'enable', 1)
mail.smtpapi.add_filter('footer', 'text/html', '<strong>boo</strong>')mail = SendGrid::Mail.new
filter = {
'footer' => {
'setting' => {
'enable' => 1,
"text/plain" => 'You can haz footers!'
}
}
}
mail.smtpapi.set_filters(filter)- Fork it ( https://github.com/[my-github-username]/sendgrid-ruby/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Hit up @rbin or @eddiezane on Twitter with any issues.