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 using:
$ gem install sendgrid-ruby
Create a new client with your SendGrid API Key.
require'sendgrid-ruby'# As a hashclient=SendGrid::Client.new(api_key: 'YOUR_SENDGRID_APIKEY')# Or as a blockclient=SendGrid::Client.newdo |c|
c.api_key='YOUR_SENDGRID_APIKEY'endCreate a new Mail object and send:
mail=SendGrid::Mail.newdo |m|
m.to='test@sendgrid.com'm.from='taco@cat.limo'm.subject='Hello world!'m.text='I heard you like pineapple.'endres=client.send(mail)putsres.codeputsres.body# 200# {"message"=>"success"}You can also create a Mail object with a hash:
res=client.send(SendGrid::Mail.new(to: 'example@example.com',from: 'taco@cat.limo',subject: 'Hello world!',text: 'Hi there!',html: '<b>Hi there!</b>'))putsres.codeputsres.body# 200# {"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')Inline content can be added to a Mail object with the add_content method. The first parameter is the path to the file, the second parameter is the cid to be referenced in the html.
mail=SendGrid::Mail.newdo |m|
m.to='test@sendgrid.com'm.from='taco@cat.limo'm.subject='Hello world!'m.text='I heard you like the beach.'m.html='I heard you like the beach <div><img src="cid:beach"></div>'endmail.add_content('/tmp/beach.jpg','beach')result=client.send(mail)params={:to,:to_name,:from,:from_name,:subject,:text,:html,:cc,:cc_name,:bcc,:bcc_name,:reply_to,:date,:smtpapi,:attachments,:template}Params can be set in the usual Ruby ways, including a block or a hash.
mail=SendGrid::Mail.newdo |m|
m.to='rbin@sendgrid.com'm.from='taco@rbin.codes'endclient.send(SendGrid::Mail.new(to: 'rbin@sendgrid.com',from: 'taco@cat.limo'))Using the :to param, we can pass a single email address as a string, or an array of email address strings.
mail=SendGrid::Mail.newmail.to='taco@rbin.codes'# ormail.to=['Example Dude <example@email.com>','john@email.com']# ormail.to=['rbin@sendgrid.com','taco@cat.limo']mail=SendGrid::Mail.newmail.from='me@sendgrid.com'As with :to, :cc can take a single string or an array of strings.
mail=SendGrid::Mail.newmail.cc=['robin@sendgrid.com','taco@cat.limo']As with :to and :cc, :bcc can take a single string or an array of strings.
mail=SendGrid::Mail.newmail.bcc=['robin@sendgrid.com','taco@cat.limo']mail=SendGrid::Mail.newmail.subject='This is a subject string'Using the :text param allows us to add plain text to our email body.
mail=SendGrid::Mail.newmail.text='WHATTUP KITTY CAT!?'Using the :html param allows us to add html content to our email body.
mail=SendGrid::Mail.newmail.html='<html><body>Stuff in here, yo!</body></html>'The :template param allows us to specify a template object for this email to use. The initialized Template will automatically be included in the smtpapi header and passed to SendGrid.
template=SendGrid::Template.new('MY_TEMPLATE_ID')mail.template=templateAnother easy way to use the SendGrid Templating system is with the Recipient, Mail, Template, and TemplateMailer objects.
Create some Recipients
users=User.where(email: ['first@gmail.com','second@gmail.com'])recipients=[]users.eachdo |user|
recipient=SendGrid::Recipient.new(user.email)recipient.add_substitution('first_name',user.first_name)recipient.add_substitution('city',user.city)recipients << recipientendCreate a Template
template=SendGrid::Template.new('MY_TEMPLATE_ID')Create a Client
client=SendGrid::Client.new(api_user: my_user,api_key: my_key)Initialize mail defaults and create the TemplateMailer
mail_defaults={from: 'admin@email.com',html: '<h1>I like email</h1>',text: 'I like email',subject: 'Email is great'}mailer=SendGrid::TemplateMailer.new(client,template,recipients)Mail it!
mailer.mail(mail_defaults)To utilize the X-SMTPAPI header, we have directly integrated the SendGridJP/smtpapi-ruby gem. For more information, view our SMTPAPI docs page.
header=Smtpapi::Header.newheader.add_to(['john.doe@example.com','jane.doe@example.com'])header.add_substitution('keep',['secret'])# sub = {keep: ['secret']}header.add_substitution('other',['one','two'])# sub = {keep: ['secret'], other: ['one', 'two']}header.add_unique_arg("unique_code","8675309")header.add_category("Newsletter")header.add_filter('templates','enable',1)# necessary for each time the template engine is usedheader.add_filter('templates','template_id','1234-5678-9100-abcd')header.set_ip_pool("marketing_ip_pool")mail.smtpapi=headerbundle exec rake test
- Confirm tests pass
bundle exec rake test - Bump the version in
lib/sendgrid/version.rbandspec/lib/sendgrid_spec.rb - Update CHANGELOG.md
- Commit Version bump vX.X.X
rake release- Push changes to GitHub
- Release tag on GitHub vX.X.X
- 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