Strongly typed library for SendGrid's v3 API
C# PowerShell
Latest commit 297ef02 Jan 5, 2017 @Jericho committed on GitHub Merge pull request #108 from Jericho/release/0.18.0
Release/0.18.0

README.md

StrongGrid

Join the chat at https://gitter.im/StrongGrid/Lobby

License Build status Coverage Status CodeFactor

About

StrongGrid is a strongly typed library for SendGrid's v3 API.

It started out in February 2016 as a fork of SendGrid's own library. I submited a pull request to SendGrid in March 2016 but it was not accepted and eventually closed in June 2016.

In October 2016 I decided to release this library as a nuget package since SendGrid's library was still using dynamic and lacking strong typing.

StrongGrid includes a client that allows you to interact with all the "resources" in the SendGrid API (e.g.: send an email, manage lists, contacts and segments, search for contacts matching criteria, create API keys, etc.).

StrongGrid also includes a parser for webhook sent from SendGrid to your own WebAPI. This parser supports the two types of webhooks that SendGrid can post to your API: the event webhook and the inbound parse webhook.

If you information about how to setup the SendGrid webhooks, please consult the following resources:

Nuget

StrongGrid is available as a Nuget package:

NuGet Version

Pre-release packages are available on my MyGet feed:

MyGet Pre Release

Installation

The easiest way to include StrongGrid in your C# project is by adding the nuget package to your project:

PM> Install-Package StrongGrid

Once you have the StrongGrid library properly referenced in your project, add the following namespace:

using StrongGrid;

.NET framework suport

StrongGrid supports the 4.5.2 .NET framework as well as .Net Core.

Usage

Client

You declare your client variable like so:

var apiKey = "... your api key...";
var client = new Client(apiKey);

If you need to use a proxy, you can pass it to the Client:

var apiKey = "... your api key...";
var proxy = new WebProxy("http://myproxy:1234");
var client = new Client(apiKey, proxy);

You have access to numerous 'resources' (such as Contacts, Lists, Segments, Settings, Whitelabel, etc) off of the Client and each resource offers several methods to such as retrieve, create, update, delete, etc.

Here are a few example:

// Create a new contact (contacts are sometimes refered to as 'recipients')
var contactId = await client.Contacts.CreateAsync(email, firstName, lastName, customFields);

// Send an email
await client.Mail.SendToSingleRecipientAsync(to, from, subject, htmlContent, textContent);

// Retreive all the API keys in your account
var apiKeys = await client.ApiKeys.GetAllAsync();

// Add an email address to a suppression group
await client.Suppressions.AddAddressToUnsubscribeGroupAsync(groupId, "test1@example.com");

// Get statistics between the two specific dates
var globalStats = await client.Statistics.GetGlobalStatisticsAsync(startDate, endDate);

// Create a new email template
var template = await client.Templates.CreateAsync("My template");

Parser

Here's a basic example of an API controller which parses the webhook from SendGrid into an array of Events:

namespace WebApplication1.Controllers
{
    [Route("api/SendGridWebhooks")]
    public class SendGridController : Controller
    {
        [HttpPost]
        [Route("Events")]
        public async Task<IActionResult> ReceiveEvents()
        {
            var parser = new WebhookParser();
            var events = await parser.ParseWebhookEventsAsync(Request.Body).ConfigureAwait(false);

            ... do something with the events ...

            return Ok();
        }
    }
}

Here's a basic example of an API controller which parses the webhook from SendGrid into an InboundEmail:

namespace WebApplication1.Controllers
{
    [Route("api/SendGridWebhooks")]
    public class SendGridController : Controller
    {
        [HttpPost]
        [Route("InboundEmail")]
        public IActionResult ReceiveInboundEmail()
        {
            var parser = new WebhookParser();
            var inboundEmail = parser.ParseInboundEmailWebhook(Request.Body);

            ... do something with the inbound email ...

            return Ok();
        }
    }
}