sendgrid-csharp: the official C# client for the SendGrid v3 mail API

One client for the v3 API, not just for sending mail

The repository describes itself as the official Twilio SendGrid C#, .NET Standard, .NET Core API library, and the README is clear about the scope. Version 9 and later provides full support for all Twilio SendGrid Web API v3 endpoints, including the v3 /mail/send endpoint. That last clause matters more than it sounds, because the older mail send call and the new one differ in body format, and a client that only supports the old shape will not talk to the current API. The examples directory in the repository shows the breadth, with folders for access settings, alerts, API keys, browsers, campaigns, categories, clients, contact database, devices, the event webhook, geo lookups, an inbound webhook handler, IP management, mail, mailbox providers, mail settings, partner settings, scopes, sender authentication, senders, stats, subusers, suppression and templates.

Two ways to build a message, and the choice is about control

The Hello Email example shows the minimum needed to send a message.

using System;
using System.Threading.Tasks;
using SendGrid;
using SendGrid.Helpers.Mail;

class Program
{
    static async Task Main()
    {
        var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);
        var from = new EmailAddress("[email protected]", "Example User");
        var subject = "Sending with Twilio SendGrid is Fun";
        var to = new EmailAddress("[email protected]", "Example User");
        var plainTextContent = "and easy to do anywhere, even with C#";
        var htmlContent = "<strong>and easy to do anywhere, even with C#</strong>";
        var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
        var response = await client.SendEmailAsync(msg).ConfigureAwait(false);
    }
}

MailHelper.CreateSingleEmail is the one-liner path. For anything more involved, the README shows constructing a SendGridMessage directly with From, Subject, PlainTextContent and HtmlContent set, then adding recipients with AddTo, which is the route to take when you need attachments, template ids, categories or custom headers. The call is awaited with ConfigureAwait(false), which is the right habit in library code and a small sign of how the samples are written.

The API key belongs in the environment, not in the source

The README is unusually insistent about credential handling, and the guidance is sound. It recommends storing the key in environment variables or in Web.config, explains that this keeps data and configuration separate so the key can change without a code change, and strongly advises against storing sensitive data directly in code. The examples show the programmatic form, reading the variable into a local and setting one.

# Get Environment Variable
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");

# Set Environment Variable
var setKey = Environment.SetEnvironmentVariable("SENDGRID_API_KEY", "YOUR_API_KEY");

For a developer on Windows there is also a six-step UI route through SystemPropertiesAdvanced to add a user variable named SENDGRID_API_KEY, and a command line equivalent with set SENDGRID_API_KEY. The name in the code has to match the name in the environment, which the README calls out explicitly, since a mismatch there is the usual cause of a null key and a confusing authentication failure.

Installing is a dotnet add package, with a separate package for DI

The package comes from NuGet, and the README gives two commands, one for the client itself and one for the dependency injection integration.

dotnet add package SendGrid

# use Twilio SendGrid with HttpClientFactory
dotnet add package SendGrid.Extensions.DependencyInjection

The second package is the one to reach for in an ASP.NET service, since it wires the client into HttpClientFactory rather than having you construct a new HttpClient per call. The prerequisites are listed next to that: .NET Framework 4.0 or later, .NET Core 1.0 or later, and .NET Standard 1.3 or later, and the actual dependency list lives in the .csproj file in src/SendGrid. Sample implementations are included for both a .NET Core project and a .NET 4.5.2 project, which is a useful reference when you are moving between them.

Sending is asynchronous, and 202 is the success code

The README states that after running the example, response.StatusCode should be 202 and the recipient should have the message. That status is worth internalising, because a 202 means the mail has been accepted for delivery rather than delivered, and anything that treats the send call as confirmation of inbox arrival will be wrong. For anything beyond that, the library exposes the wider API surface, and the general v3 usage section covers calling the endpoints directly. The Web Proxy section covers routing through a proxy, which matters in corporate networks, and for delivery events the README points at the Event Webhook, which posts events to a URL of your choice so you can track what happened to a message after the send call returns.

An SMS announcement, and a repository that spans many frameworks

The announcements section at the top of the README notes that you can send SMS messages with Twilio, linking to a use case section, which is a reminder that the platform now covers more than email and that the library is the entry point rather than the whole product. The repository layout shows the range it tries to serve. There are three example projects, ExampleCoreProject, ExampleNet45ASPNetProject and ExampleNet45Project, a SendGrid.sln solution, a src/ directory, tests/ and tools/ directories, and separate USAGE.md, USE_CASES.md, TROUBLESHOOTING.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, PULL_REQUEST_TEMPLATE.md and FIRST_TIMERS.md files. The Dockerfile at the root is a test harness rather than a shipping image, based on mono:latest with a .NET SDK 2.1 layer and a custom certificate copied into the trust store.

The build is plain dotnet, and the release cadence is the real caveat

The Makefile is short and shows the actual toolchain, with a clean target that runs dotnet clean, an install target that checks for the dotnet CLI and exits with a message if it is missing, a test target that builds and tests in Release configuration and uploads coverage to codecov, an integ test target that depends on it, a docker test target that downloads a prism script to mock the API, and a release target that runs dotnet pack. The last push to the repository was on 2026-06-25 and the repository is not archived, but the published releases are 9.29.3 from 2024-04-02, 9.29.2 from 2024-02-14 and 9.29.1 from 2024-01-15. A library on NuGet is what most projects actually install, so a fix that landed after April 2024 is not in the 9.29.3 package, and that gap is worth checking before you pin a version.

Editorial conclusion

sendgrid-csharp fits a .NET team that has chosen SendGrid and wants the official client rather than a hand-rolled HTTP wrapper, because the version 9 series covers the full v3 endpoint set and the two construction paths cover both the one-liner case and the full control case. It is a poor fit if you want to keep the email provider pluggable, since the message and client types are SendGrid's own, and a poor fit if you are on a modern .NET version where the framework targets in the metadata are older than you would like. Verify first which target frameworks your project needs against the prerequisites the README lists, and note that the published 9.x releases date from early 2024 while the last push to the repository was on 2026-06-25, so check the changelog before assuming a fix is in a released package.

Frequently asked questions

Official sources

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