sendgrid-ruby

The use-cases/ directory contains documentation and code examples for various implementation scenarios. Use these guides to implement specific features such as transactional templates, Twilio integrations, or domain authentication.

Available categories include:

• Email Use Cases: Transactional Templates, Legacy Templates, and Personalizations.
• Twilio Use Cases: Twilio Setup, sending emails via Twilio Email (Pilot), and sending SMS messages.
• Non-Email Use Cases: Domain Authentication setup and viewing Email Statistics.

The sendgrid/helpers/settings module provides a way to quickly and easily construct a Settings object. This object is used to retrieve or update your Twilio SendGrid Settings via the Web API v3.

ruby examples/helpers/settings/example.rb

IP Access Management allows you to control which IP addresses can access your account via the UI or API. You can whitelist specific IPs, retrieve activity logs, or manage existing whitelist rules.

# Example: Retrieve activity
params = JSON.parse('{"limit": 1}')
response = sg.client.access_settings.activity.get(query_params: params)

The Mail helper class provides a high-level abstraction for constructing complex Mail objects required by the Twilio SendGrid Web API v3. It simplifies the process of defining senders, recipients, content, and attachments without manually constructing large JSON payloads.

# Note: Refer to the full example for complete implementation details
# Ensure SENDGRID_API_KEY is set in your environment.

The Inbound Parse helper consists of three main components:

• app.rb: A Sinatra-based server that listens for POST requests (defaulting to http://localhost:9292). When a POST is received, it parses the inbound data and prints the key/value pairs.
• config.yml: A configuration file used to load application environment variables and customize server settings.
• send.rb & /sample_data: A utility for sending simulated inbound parse data, allowing for development and testing without waiting for MX record propagation.

Suppression groups (also known as unsubscribe groups) allow you to categorize your email content (e.g., 'Daily Newsletters', 'Invoices') so recipients can opt out of specific categories without unsubscribing from everything.

Key constraints:

• Each user can create up to 25 different suppression groups.
• The name and description provided during creation are visible to recipients.
• You can only delete groups that have not been attached to sent mail in the last 60 days.

It is highly recommended to use environment variables to store your Twilio SendGrid API key.

When using ENV['SENDGRID_API_KEY'], the library references the name of the environment variable. If you pass a string directly, it must be the actual API key value.

# Recommended: uses the environment variable named SENDGRID_API_KEY
sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])

# Not recommended: uses the literal string as the key
sg = SendGrid::API.new(api_key: 'YOUR_ACTUAL_API_KEY')

Prerequisites

• Ruby version >= 2.4 (Note: version 2.6.0 has known issues; see troubleshooting guide).
• A Twilio SendGrid service account.

Setup Environment Variables

Set your SENDGRID_API_KEY in your environment. It is recommended to use an environment file:

echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env

Install Package

Add the gem to your Gemfile:

gem 'sendgrid-ruby'

Then run:

bundle

Or install it directly via gem:

gem install sendgrid-ruby

To use the Inbound Parse helper, you must install the main sendgrid-ruby package and also add sinatra to your Gemfile. The helper uses Sinatra to run a listener server.

Add the following to your Gemfile:

gem 'sinatra', '>= 1.4.7', '< 3'

To use the SendGrid Ruby library, require the gem and initialize a new SendGrid::API instance using your API key. It is recommended to use an environment variable for security.

require 'sendgrid-ruby'

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])