# sendgrid-ruby is the official Ruby client for the SendGrid v3 API

> sendgrid-ruby is the MIT licensed Ruby library from Twilio SendGrid that wraps the Web API v3, offering a mail helper for building payloads, a fluent client for the rest of the endpoints and a raw JSON path when you want none of that. It is thin by design, with a single dependency, and its release history has been quiet since version 6.7.0 in December 2023 even though the repository still sees commits.

**sendgrid/sendgrid-ruby** — The Official Twilio SendGrid Led, Community Driven Ruby API Library

- Repository: https://github.com/sendgrid/sendgrid-ruby
- Website: https://sendgrid.com
- Stars: 634 · Forks: 324
- Language: Ruby
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/sendgrid-sendgrid-ruby

## A thin wrapper over the v3 web API

sendgrid-ruby is the official Ruby library for the Twilio SendGrid Web API v3, described in the project as Twilio SendGrid led and community driven. Version 3.x of the library provides full support for the v3 endpoints, including the v3 `/mail/send` endpoint. What it deliberately is not is an email framework. There is no template engine, no queue, no retry policy, and no abstraction over the request body, because the library's job ends at the HTTP boundary. The dependency list reflects that, with the runtime dependency being the SendGrid Ruby HTTP client. Everything else is the API surface itself, and the repository shows the shape of it in the `examples/` directory, with a folder per API area such as `alerts/`, `campaigns/`, `mail/`, `senders/`, `stats/`, `suppression/` and `scopes/`, plus a `helpers/` directory that holds the opinionated pieces. For a reader deciding whether to use it, that split between helpers and raw endpoints is the whole design.

## Two ways to send a message

The quick start shows the same request written two ways. With the mail helper, you build objects for the sender, the recipient, the subject and the content, assemble them into a `SendGrid::Mail` and post the JSON:

```ruby
require 'sendgrid-ruby'
include SendGrid

from = SendGrid::Email.new(email: 'test@example.com')
to = SendGrid::Email.new(email: 'test@example.com')
subject = 'Sending with Twilio SendGrid is Fun'
content = SendGrid::Content.new(type: 'text/plain', value: 'and easy to do anywhere, even with Ruby')
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.body
puts response.parsed_body
puts response.headers
```

Without the helper, you parse a JSON document yourself and post it to the same path. The documentation is clear about which to use. The helper is the minimum needed code, and for more complex scenarios the advice is not to use that constructor but to build your own personalization object, with a full example in the `examples/helpers/mail/` directory. The reason is that the constructor form takes a single recipient and a single content block, while a real transactional email has multiple personalizations, substitutions and dynamic template data. Either way the response object exposes the status code, the raw body, the parsed body and the headers, which is the same four-field shape you get from every call in the library.

## A fluent client, and a path straight to the endpoint

For everything that is not mail send, the client exposes a fluent interface, where the call reads like the API path:

```ruby
require 'sendgrid-ruby'
sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
response = sg.client.suppression.bounces.get()
puts response.status_code
puts response.body
puts response.parsed_body
puts response.headers
```

The same request without the fluent interface goes through a generic accessor, `sg.client._("suppression/bounces").get()`, which takes the path as a string. The `_` method is the escape hatch that matters, because it means an endpoint the client does not model yet is still reachable without waiting for a library release. That is the practical reason to use the vendor client rather than hand-written HTTP for a large API surface. The client is instantiated once with an API key and then reused, and the key is read from the environment in the examples, which is the configuration pattern the setup section teaches.

## Installation and the API key

The prerequisites are Ruby 2.4 or newer, with version 2.6.0 called out as an exception, and a Twilio SendGrid service, which starts at the free level. The library goes into a Gemfile and then bundler does the work:

```bash
gem 'sendgrid-ruby'
```

```bash
bundle
```

Or it can be installed directly with `gem install sendgrid-ruby`. The API key is handled through the environment, and the setup section shows the pattern of writing it to a file that is not committed:

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

The repository carries a `.env_sample` at the root as well, and the general shape of the configuration is the same one you would expect in a Rails application. The key is never hard coded in the examples, and the `ENV` lookup appears in every snippet, which is a small piece of good hygiene that costs nothing to follow.

## Helpers for inbound mail and settings

Sending is only half of the API, and the library covers the other half with a small set of helpers. The inbound parse webhook is handled by the helper in `lib/sendgrid/helpers/inbound`, which matters for anyone receiving forwarded email and parsing it into a form. The settings helper lives in `lib/sendgrid/helpers/settings`, and the mail send helper is documented as building a request object payload for a v3 `/mail/send` call. Beyond the code, the repository ships the supporting material a team needs to get moving: a `use-cases/` directory with examples of common API use cases such as sending an email with a transactional template, a `USAGE.md` with library usage documentation, an `UPGRADE.md`, a `TROUBLESHOOTING.md` for common library issues, a `mail_helper_v3.md`, and a `CHANGELOG.md` where all updates are recorded. There is also a how-to link for migrating from the v2 API to the v3 mail send endpoint, which is the document to read if you are moving an existing integration.

## The test suite runs against a mock server

The Makefile shows how the project is built and tested, and the interesting target is `test-docker`, which does not hit the real API. It downloads a script and runs it in a container:

```bash
.curl -s https://raw.githubusercontent.com/sendgrid/sendgrid-oai/HEAD/prism/prism.sh -o prism.sh
version=$(version) bash ./prism.sh
```

The `install` target pins bundler to a specific version before running `bundle install`, and the plain `test` target runs the suite through `bundle exec rake`, with `test-integ` depending on it. The Dockerfile builds on a `ruby:latest` base by default, overridable through the `version` build argument, installs make and git for JRuby, copies in a certificate for the CA store, and runs `make install`. The repository is otherwise a conventional Ruby gem layout, with `lib/`, `spec/`, `test/`, `examples/`, `use-cases/`, `gemfiles/` for testing against multiple dependency sets, a `config.ru` for the rack entry point, and RuboCop configuration in `.rubocop.yml` and `.rubocop_todo.yml`. The first-timers file and the pull request template are the community signals that the contribution flow is deliberate.

## MIT licensed, with a quiet release line since 2023

The licence is MIT, which is the permissive end of the scale and a good fit for a client library that most teams will never need to modify. The maintenance picture is the part to weigh. The tagged releases are 6.6.1 on 2022-02-09, 6.6.2 on 2022-03-09 and 6.7.0 on 2023-12-01, and the last push to the repository was on 2026-06-25 with the repository not archived. So the gem itself has not been published in a while even though the repository is still receiving commits, which usually means work is landing on the default branch without a release being cut. The documentation says the project represents the beginning of a new path for Twilio SendGrid, that it should be community driven and SendGrid led, and it asks for issues and pull requests to steer what gets built. For an adopter the sensible reading is that the library is in a maintenance posture rather than an active development one, and that the `CHANGELOG.md` and the release page are where you check what actually changed.

## Conclusion

Ruby teams sending transactional email through SendGrid will find this the library the vendor ships and supports, with a documented migration path from v2 to v3, a mail helper that keeps payloads readable and a fluent client that covers the rest of the API. It is the wrong choice if you want a higher level sending abstraction, since the library stays close to the wire format and leaves template rendering, retries and queueing to you. Before you adopt it, read UPGRADE.md and the v2 to v3 migration guide rather than the hello world example, and check the version you pin against the CHANGELOG, since the last tagged release is 6.7.0 from 2023.

## FAQ

### How do I install sendgrid-ruby?

Add `gem 'sendgrid-ruby'` to your Gemfile and run `bundle`, or install it directly with `gem install sendgrid-ruby`. The library requires Ruby 2.4 or newer, with version 2.6.0 called out as an exception, and a Twilio SendGrid account.

### How do I set the SendGrid API key?

The setup section puts it in the environment. The documented pattern writes `export SENDGRID_API_KEY='YOUR_API_KEY'` to a file, adds that file to .gitignore, sources it, and reads the key with `ENV['SENDGRID_API_KEY']` when creating `SendGrid::API.new`.

### When should I use the mail helper instead of raw JSON?

The helper is the minimum code for a simple message, but the documentation says that for more complex scenarios you should not use that constructor and should build your own personalization object instead. A full example is in the examples/helpers/mail directory.

### Can I call an endpoint the client does not model?

Yes. The general v3 usage without the fluent interface goes through `sg.client._("suppression/bounces").get()`, which takes the API path as a string, so any endpoint can be reached even if the library does not have a named method for it.

### How are the tests run without sending real email?

The Makefile's test-docker target downloads a prism script and runs it in a container, and the plain test target runs `bundle exec rake`. The Dockerfile builds on a ruby:latest base and runs make install as its build step.

## Sources

- [License: MIT](https://github.com/sendgrid/sendgrid-ruby/blob/main/LICENSE)
- [Project website](https://sendgrid.com)
- [README](https://github.com/sendgrid/sendgrid-ruby/blob/main/README.md)
- [Releases](https://github.com/sendgrid/sendgrid-ruby/releases)
- [sendgrid/sendgrid-ruby on GitHub](https://github.com/sendgrid/sendgrid-ruby)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sendgrid-sendgrid-ruby