Announcements

August 2017

Subscribe to email notifications for releases and breaking changes.

Overview

This library allows you to quickly and easily use the SendGrid Web API v3 via C# with .NET.

Version 9.X.X+ of this library provides full support for all SendGrid Web API v3 endpoints, including the new v3 /mail/send.

We want this library to be community driven, and SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create issues and pull requests or simply upvote or comment on existing issues or pull requests.

For updates to this library, see our CHANGELOG and releases.

Subscribe to email release notifications to receive emails about releases and breaking changes.

We appreciate your continued support, thank you!

Installation
Quick Start
Usage
Use Cases
Announcements
Roadmap
How to Contribute
Troubleshooting
About
License

Installation

Prerequisites

.NET version 4.5.2 and higher
.NET Core 1.0 and higher
.NET Standard 1.3 support
A SendGrid account, sign up for free to send up to 40,000 emails for the first 30 days or check out our pricing.

Obtain an API Key

Grab your API Key from the SendGrid UI.

Setup Environment Variables to Manage Your API Key

Do not hard code your SendGrid API Key into your code. Instead, use something like an environment variable or Web.config.

The examples found below in this quick start and in the example projects all make use of storing their API keys as an environment variable.

Environment variables are usually part of the OS and are available to programs within that same OS. It gives the option to bypass hardcoding credentials, making them easy to manage.

The following example will go through adding an environment variable in Windows 10.

Looking at the code example from the Quick Start, we see that the second line of the Execute() method tries to retrieve an environment variable like so:

var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");

NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY isn't a variable of your OS environment yet, so let's add it.

Press win + R (or search for "run"), fill in "SystemPropertiesAdvanced", press enter and then click "Environment variables".

You'll get two lists of variables, but we'll focus on the User Variables for this example.

Click the "New" button beneath the User Variables list. Give it the name NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY (or rename the variable in both the environment and code to a more generic name).

For value, insert your SendGrid API key. Click "Ok", and once again in the Variable Overview and lastly, close the system properties window.

You may need to restart your IDE to make use of the new variable.

Now, if all went well, you can access the just added variable in your C# SendGrid projects! Ready for some examples?

Install Package

To use SendGrid in your C# project, you can either download the SendGrid C# .NET libraries directly from our Github repository. If you have the NuGet package manager installed, you can grab them automatically:

PM> Install-Package SendGrid

Once you have the SendGrid library installed, you can include calls to them in your code. For sample implementations, see the .NET Core Example and the .NET 4.5.2 Example folders.

Dependencies

Please see the .nuspec file.

Quick Start

Hello Email

The following is the minimum needed code to send an simple email. Use this example, and modify the apiKey, from and to variables:

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

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);
            var from = new EmailAddress("[email protected]", "Example User");
            var subject = "Sending with 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);
        }
    }
}

After executing the above code, response.StatusCode should be 202 and you should have an email in the inbox of the to recipient. You can check the status of your email in the UI. Alternatively, we can post events to a URL of your choice using our Event Webhook. This gives you data about the events that occur as SendGrid processes your email.

For more advanced cases, you can build the SendGridMessage object yourself with these minimum required settings:

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

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

	    static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);
            var msg = new SendGridMessage()
            {
                From = new EmailAddress("[email protected]", "DX Team"),
                Subject = "Sending with SendGrid is Fun",
                PlainTextContent = "and easy to do anywhere, even with C#",
                HtmlContent = "<strong>and easy to do anywhere, even with C#</strong>"
            };
            msg.AddTo(new EmailAddress("[email protected]", "Test User"));
            var response = await client.SendEmailAsync(msg);
        }
    }
}

You can find an example of all of the email features here.

General v3 Web API Usage

using System;
using System.Threading.Tasks;
using SendGrid;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
            var client = new SendGridClient(apiKey);
            var queryParams = @"{
                'limit': 100
            }";
            var response = await client.RequestAsync(method: SendGridClient.Method.GET,
                                                     urlPath: "suppression/bounces",
                                                     queryParams: queryParams);
	    }
    }
}

Web Proxy

var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
var proxy = new WebProxy("http://proxy:1337");
var client = new SendGridClient(proxy, apiKey);

Usage

Use Cases

Here are some examples of common API use cases, such as how to send an email with a transactional template.

Roadmap

If you are interested in the future direction of this project, please take a look at our open issues and pull requests. We would love to hear your feedback!

How to Contribute

We encourage contribution to our library (you might even score some nifty swag), please see our CONTRIBUTING guide for details.

Quick links:

Troubleshooting

Please see our troubleshooting guide for common library issues.

About

sendgrid-csharp is guided and supported by the SendGrid Developer Experience Team.

sendgrid-csharp is maintained and funded by SendGrid, Inc. The names and logos for sendgrid-csharp are trademarks of SendGrid, Inc.

License

The MIT License (MIT)

kostyahrytsyuk / sendgrid-csharp Goto Github PK

sendgrid-csharp's Introduction