Be sure to perform the following prerequisites to complete this tutorial. You can skip ahead if you've already completed these tasks.
- Sign up for a SendGrid account.
- Enable Two-factor authentication.
- Create and store a SendGrid API Key with Mail Send > Full Access permissions.
- Complete Domain Authentication.
- Install Ruby.
Twilio SendGrid requires customers to enable Two-factor authentication (2FA). You can enable 2FA with SMS or by using the Authy app. See the 2FA section of our authentication documentation for instructions.
Unlike a username and password — credentials that allow access to your full account — an API key is authorized to perform a limited scope of actions. If your API key is compromised, you can also cycle it (delete and create another) without changing your other account credentials.
Visit our API Key documentation for instructions on creating an API key and storing an API key in an environment variable. To complete this tutorial, you can create a Restricted Access API key with Mail Send > Full Access permissions only, which will allow you to send email and schedule emails to be sent later. You can edit the permissions assigned to an API key later to work with additional services.
Once your API key is assigned to an environment variable — this quickstart uses
SENDGRID_API_KEY — you can proceed to the next step.
export SENDGRID_API_KEY=<Your API Key>
To ensure our customers maintain the best possible sender reputations and to uphold legitimate sending behavior, we require customers to verify their Sender Identities by completing Domain Authentication. A Sender Identity represents your 'From' email address—the address your recipients see as the sender of your emails.
To get started quickly, you may be able to skip Domain Authentication and begin by completing Single Sender Verification. Single Sender Verification is recommended for testing only. Some email providers have DMARC policies that restrict email from being delivered using their domains. For the best experience, please complete Domain Authentication. Domain Authentication is also required to upgrade from a free account.
Before installing Ruby, you can see if you already have a version on your machine.
The Twilio SendGrid Ruby helper library supports Ruby versions 2.4 through the current version of Ruby 2.x, excluding version 2.6.0.
Check your Ruby version by opening your terminal (also known as a command line or console) and typing the following command.
If you have Ruby installed, the terminal will print something like the following output.
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-darwin19]
You may already have a version of Ruby included on your operating system. For example, MacOS includes a version of Ruby for its own system uses. It is not recommended to develop your application using the MacOS system installation of Ruby.
If you do not already have a version of Ruby installed, visit the Ruby website to download and install a version appropriate for your operating system.
Using a Twilio SendGrid helper library is the fastest way to deliver your first email.
Start by creating a project folder for this app. The following examples will use a folder called
Next, navigate into the
send_mail directory where you will complete the rest of the tutorial.
The RubyGems package manager is included when installing Ruby. You can use RubyGems to install the Twilio SendGrid helper library and save it as a project dependency. If you want to verify that RubyGems is installed, you can type the following into the terminal.
The terminal should print something like the following output.
To install the Twilio SendGrid helper library, type the following command into the terminal.
gem install sendgrid-ruby
The terminal will output something like the following output.
Fetching ruby_http_client-3.5.2.gem Fetching sendgrid-ruby-6.4.0.gem Successfully installed ruby_http_client-3.5.2 Successfully installed sendgrid-ruby-6.4.0 Parsing documentation for ruby_http_client-3.5.2 Installing ri documentation for ruby_http_client-3.5.2 Parsing documentation for sendgrid-ruby-6.4.0 Installing ri documentation for sendgrid-ruby-6.4.0 Done installing documentation for ruby_http_client, sendgrid-ruby after 0 seconds 2 gems installed
You're now ready to write some code. First, create a
send_mail.rb file in your project directory.
The following Ruby block contains all the code needed in your
send_mail.rb file to successfully deliver a message with the SendGrid Mail Send API. You can copy this code, modify the
from variables, and run the code if you like. We'll break down each piece of this code in the following sections.
require 'sendgrid-ruby' include SendGrid from = SendGrid::Email.new(email: 'email@example.com', name: "Test") # Change to your verified sender to = SendGrid::Email.new(email: 'firstname.lastname@example.org', name: "Test") # Change to your recipient subject = 'Sending with Twilio SendGrid is Fun' content = SendGrid::Content.new(type: 'text/html', value: 'and easy to do anywhere, even with <strong>Ruby</strong>.') mail = SendGrid::Mail.new(from, subject, to, content) sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) response = sg.client.mail._('send').post(request_body: mail.to_json) puts response.status_code puts response.headers
Your API call must have the following components.
- A host (the host for Web API v3 requests is always
- An API key passed in an Authorization Header
- A request (when submitting data to a resource via
PUT, you must submit your request body in JSON format)
send_mail.rb file, require the SendGrid helper library, and include the SendGrid module. The library will handle setting the Host,
https://api.sendgrid.com/v3/, for you.
require 'sendgrid-ruby' include SendGrid
Now you're ready to set up the
subject, and message body
content. These values are passed to the API in a Personalizations object when using the v3 Mail Send API. You can assign each of these values to variables, and the SendGrid library will handle creating a
personalizations object for you.
subject variable is a string. However, you will set the
to variables using the helper library's
name and an
to value to an address with an inbox you can access.
content variable is set with the
Content method. The
Content method takes a
type, which can be either
text/html, and a
value, which is a string of the content you wish to send in the message body.
from = SendGrid::Email.new(email: 'email@example.com', name: "Test") # Change to your verified sender to = SendGrid::Email.new(email: 'firstname.lastname@example.org', name: "Test") # Change to your recipient subject = 'Sending with Twilio SendGrid is Fun' content = SendGrid::Content.new(type: 'text/html', value: 'and easy to do anywhere, even with <strong>Ruby</strong>.')
To properly construct the message, pass each of the previous variables into the SendGrid library's
mail = SendGrid::Mail.new(from, subject, to, content)
Next, use the API key you set up earlier. Remember, the API key is stored in an environment variable, so you can use Ruby's
ENV class to access it. Assign the key to a variable named
sg using the helper library's
API method. The helper library will pass your key to the v3 API in an Authorization Header using Bearer token authentication.
sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
Lastly, you need to make a request to the SendGrid Mail Send API to deliver your message.
The helper library uses SendGrid's ruby-http-client library to construct the request URL by chaining together portions of your desired path. The path to the SendGrid v3 Mail Send endpoint is
https://api.sendgrid.com/v3/mail/send. The helper library sets the client for you, so the
https://api.sendgrid.com/v3 portion is taken care of by typing
sg.client. The next parts of the path are
/send. You can chain the words
client to build the rest of the URL.
With the URL built,
ruby-http-client then allows you to chain on the type of HTTP request you wish to make with a method matching the name of the HTTP verb appropriate for your desired endpoint. To send a message, you should make an HTTP
POST request, so you can use
post() method takes a
request_body, which you should set to a JSON version of your message. You can assign this full call to a variable named
response. You can also print the response status code and headers.
# Send an HTTP POST request to /mail/send response = sg.client.mail._('send').post(request_body: mail.to_json) puts response.status_code puts response.headers
With all this code in place, you can run your
mail_send.rb file in your terminal to send the email.
If you receive a
202 status code printed to the console, your message was sent successfully. Check the inbox of the
to address, and you will see your demo message.
If you don’t see the email, you may need to check your spam folder.
If you receive an error message, you can reference our response message documentation for clues about what may have gone wrong.
All responses are returned in JSON format. We specify this by sending the Content-Type Header. The Web API v3 provides a selection of response codes, content-type headers, and pagination options to help you interpret the responses to your API requests.
Get additional onboarding support. Save time, increase the quality of your sending, and feel confident you are set up for long-term success with SendGrid Onboarding Services.
This is just the beginning of what you can do with our APIs. To learn more, check the resources below.