Skip to content

ohhdear/sendgrid-ruby

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

60 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SendGrid::Ruby

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.

Installation

Add this line to your application's Gemfile:

gem 'sendgrid-ruby'

And then execute:

$ bundle

Or install it yourself using:

$ gem install sendgrid-ruby

Usage

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'
end

Create 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

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')

Available Params

params = {
	:to,
	:to_name,
	:from,
	:from_name,
	:subject,
	:text,
	:html,
	:cc,
	:bcc,
	:reply_to,
	:date,
	:smtpapi,
	:attachments
}

Setting Params

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]'))

:to

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]']

:from

mail = SendGrid::Mail.new
mail.from = '[email protected]'

:cc

As with :to, :cc can take a single string or an array of strings.

mail = SendGrid::Mail.new
mail.cc = ['[email protected]', '[email protected]']

:bcc

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]']

:subject

mail = SendGrid::Mail.new
mail.subject = 'This is a subject string'

Email Bodies:

:text

Using the :text param allows us to add plain text to our email body.

mail = SendGrid::Mail.new
mail.text = 'WHATTUP KITTY CAT!?'

:html

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>'

Using SendGrid's X-SMTPAPI Header

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.new
header.add_to(['[email protected]', '[email protected]'])
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('template', 'enable', 1)	   # necessary for each time the template engine is used
header.add_filter('template', 'template_id', '1234-5678-9100-abcd')
header.set_ip_pool("marketing_ip_pool")
mail.smtpapi = header

Contributing

  1. Fork it ( https://github.com/[my-github-username]/sendgrid-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Hit up @rbin or @eddiezane on Twitter with any issues.

About

Official Ruby Gem for the SendGrid email Web API.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Ruby 100.0%