sendgrid-go, the Go client for the Twilio SendGrid v3 API

A client for one hosted API, not a mail sending library

sendgrid-go is the official Twilio SendGrid Golang API library, and the README states its scope plainly, allowing you to quickly and easily use the Twilio SendGrid Web API v3 via Go. Version 3 of the library provides full support for all the Web API v3 endpoints, including the v3 /mail/send endpoint, which is the one most applications actually need. The library also carries a helper for inbound email through the Inbound Parse webhook, so the round trip of receiving a reply and sending a message is covered in one dependency. The project describes itself as the beginning of a new path for Twilio SendGrid, one that is meant to be community driven and Twilio SendGrid led, and the README asks for issues and pull requests to make sure the right things are built in the right order. The audience is a Go team that has chosen SendGrid as its transactional mail provider and wants a typed client for it.

Install, key, environment

The installation is a single go get, and the only runtime dependency is the rest package.

go get github.com/sendgrid/sendgrid-go

The API key is read from the environment rather than hard coded, and the README shows the pattern of writing it to a file, adding that file to .gitignore and sourcing it.

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

There is a second, shorter form of the same idea, copying a sample file to .env in the working directory. The prerequisite is a Twilio SendGrid account, and the README points at the free tier, which allows up to 40,000 emails for the first thirty days and then 100 emails a day free, with a link to the pricing page. The key itself comes from the API keys page in the SendGrid application settings, and the security habit the README is modelling, keeping the key out of version control, is the one worth copying even if you never use this library.

Two ways to send the same message

The quick start offers the same message twice, once with the helper and once without, and the difference is the level of control. With the helper, the mail package builds the request, and the client sends it.

from := mail.NewEmail("Example User", "[email protected]")
to := mail.NewEmail("Example User", "[email protected]")
message := mail.NewSingleEmail(from, subject, to, plainTextContent, htmlContent)
client := sendgrid.NewSendClient(os.Getenv("SENDGRID_API_KEY"))
response, err := client.Send(message)

The NewEmail constructor creates a personalization object for you, and the README points at an example showing how to add to it. Without the helper, you build the request yourself with GetRequest, which takes the key, the path and the base URL, and then you hand it to the API function.

request := sendgrid.GetRequest(os.Getenv("SENDGRID_API_KEY"), "/v3/mail/send", "https://api.sendgrid.com")
request.Method = "POST"
request.Body = []byte(`{ ... }`)
response, err := sendgrid.API(request)

Either way the response carries the status code, the body and the headers, which is the detail that matters when a send fails and you need to know what the API said.

Every other endpoint uses the same request path

Because GetRequest takes a path, the rest of the v3 API is reachable with the same pattern, and the README shows a general usage example against the API keys endpoint.

request := sendgrid.GetRequest(os.Getenv("SENDGRID_API_KEY"), "/v3/api_keys", "https://api.sendgrid.com")
request.Method = "GET"

That is the whole generalisation, a path, a method and a body. The README points out the resources that exist for the rest of the surface, the SendGrid API reference, the library usage document USAGE.md, the examples directory, the v3 mail send helper documentation, the inbound helper, the use-cases directory with examples such as sending with a transactional template, and a migration guide from v2 to the v3 mail send endpoint. The last one matters for anyone arriving from an older integration, since the shape of the request changed with the v3 endpoint.

Examples organised by API area

The examples directory is the most complete map of the API in the repository, and it is organised by the area of the API rather than by feature of the library. There are directories for accesssettings, alerts, apikeys, asm, browsers, campaigns, categories, clients, contactdb, dataresidency, devices, emailactivity, eventwebhook, geo, helpers, ips, mail, mailboxproviders, mailsettings, partnersettings, scopes, senderauthentication, senders, stats and subusers, and inside each of them is a runnable program for that part of the surface. For a team integrating SendGrid, that is more useful than any README, since the first question is always which endpoint to call and the directory list answers it. The top level of the repository holds the library code itself, with sendgrid.go, base_interface.go and twilio_email.go, plus the helpers/ directory, the use-cases/ directory, a proposal/ directory, static/ and a Dockerfile, and the process documents, CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md, FIRST_TIMERS.md, CODE_OF_CONDUCT.md, TROUBLESHOOTING.md, USAGE.md and a CHANGELOG.md.

Testing runs against a Prism mock, not the live API

The Makefile shows how the project tests itself, and the fourth target is the interesting one. The test target runs the coverage script and then checks formatting by diffing the output of gofmt against the tree, so a formatting regression fails the build. The test-integ target depends on the same tests, and test-docker fetches a script from the sendgrid-oai repository and runs it, which is how the integration tests get a server to talk to. The Dockerfile is built around the same idea. It starts from golang:1.21.11, sets GO111MODULE to off, copies a certificate from the prism directory into the system CA store and runs update-ca-certificates so the mock server's certificate is trusted, then copies the source and runs make install. The comment in the file explains the testify checkout, that it uses the last version of testify which works with the older Go versions and then reinstalls to update dependencies. The upshot for a contributor is that the test suite does not need a SendGrid account or a network call, which is a much better position than a library whose tests email real people.

Version lines, supported Go versions and where to ask for help

The README lists the Go implementations the library supports, and the list is short and old, Go 1.14 through 1.19. That is a detail worth checking against your own toolchain before you adopt the dependency. The release history shows two lines, v3.16.1 published on 2025-05-29 and the 4.0.0 release candidates v4.0.0-rc.2 on 2024-10-04 and v4.0.0-rc.3 on 2024-10-24, so a 4.x consumer is still on a candidate rather than a stable release. The repository is not archived and the last push was on 2026-06-25. The licence is MIT, in the LICENSE file, which is the permissive grant a client library normally carries. For questions about using the service rather than the library, the README points at the Twilio SendGrid Support Help Center, and the contributing section asks for pull requests, with a separate FIRST_TIMERS.md file for newcomers, which is a small sign that the project expects outside contributions rather than just bug reports.

Editorial conclusion

sendgrid-go fits a Go service that sends transactional mail through SendGrid and wants either the convenience of the mail helper or direct access to the v3 API without hand writing HTTP requests. It does not fit a team that wants to avoid a vendor dependency, since every call is an API call to one service, and it does not fit a project that needs the newer 4.x API shape without checking what the release candidates changed. Verify three things before you adopt it: which module major version you are pinning, since the 3.x line and the 4.0 release candidates behave differently, that your API key is only in an environment variable and never in the repository, and that your Go version is one the library still supports, since the README lists Go 1.14 through 1.19.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sendgrid/sendgrid-go on GitHub