65
loading...
Send Emails using the SendGrid API with .NET 6 and C#
This blog post was written for Twilio and originally published at the Twilio blog.
Email has been around for decades, but sending emails at scale is still hard. With Twilio SendGrid, you can send emails without worrying about scalability. You can use the SendGrid APIs and SDKs to start sending emails within minutes. You could also use the SMTP protocol if you already have an existing codebase that relies on SMTP. In this post, you will learn how to send emails using the SendGrid .NET SDK and a .NET 6 console application.
You will need the following things to follow along:
Everything you will learn applies even if you’re using an older version of .NET (Core), but you will need to make minor adjustments.
There are two things you need to configure before you can send emails. First, you’ll need to set up Sender Authentication. This will verify that you own the email address or domain that you will send emails from. Second, you’ll need to create a SendGrid API Key with permission to send emails.
It is recommended to configure Domain Authentication which requires you to add a record to your DNS host. To keep things simple, you will use Single Sender Verification instead. This will verify that you own the single email address that you want to send emails from. Single Sender Verification is great for testing purposes, but it is not recommended for production.
Twilio recommends Domain Authentication for production environments. An authenticated domain proves to Inbox Service Providers you own the domain and removes the via sendgrid.net text that inbox providers would otherwise append to your from address.
Go to the SendGrid website and log in. Click on the Settings tab in the side menu. Once the settings tab opens up, click on Sender Authentication.
Click on Get Started under the Single Sender Verification section.
This will open a form on the right-side panel. Fill out the form with your information and email address.
Click Create after filling out the form. Another panel will appear on the right asking you to confirm your email address. An email has been sent to the email address you entered.
Go to your inbox, open the email from SendGrid, and click Verify Single Sender.
Go to your inbox, open the email from SendGrid, and click Verify Single Sender.
Your email address has been verified and you can now use it to send emails!
Back on the SendGrid website, click on API Keys under the Settings tab. Click on Create API Key in the top right corner. This will open another form in the right-side panel. Give your API Key a useful name. You can assign different permissions to the API Key. For optimal security, you should only give the minimum amount of permissions that you need.
Click on Restricted Access.
Click on Restricted Access.
Scroll down to the Mail Send accordion item and click on it to reveal the permissions underneath. Drag the slider to the right for the Mail Send permission.
Scroll to the bottom of the form and click on Create & View. The API key will now be displayed on your screen. You will not be able to retrieve the API key again once you leave this screen.
Copy the secret somewhere safe.
With the sender verified and the API Key created, you’re ready to write some code!
Open a shell on your machine and create a new folder using the following command:
mkdir SendGridMailMove into to the new folder:
cd SendGridMailCreate a new console application using .NET CLI:
dotnet new consoleRun the project using the .NET CLI:
dotnet runYou should see “ Hello, World! ” output to your shell.
Add the SendGrid NuGet package to your project using the .NET CLI:
dotnet add package SendGridOpen up the console project using a code editor or IDE and replace the contents of the Program.cs file with the following:
using SendGrid;
using SendGrid.Helpers.Mail;
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
var client = new SendGridClient(apiKey);
var msg = new SendGridMessage()
{
From = new EmailAddress("[REPLACE WITH YOUR EMAIL]", "[REPLACE WITH YOUR NAME]"),
Subject = "Sending with Twilio SendGrid is Fun",
PlainTextContent = "and easy to do anywhere, especially with C#"
};
msg.AddTo(new EmailAddress("[REPLACE WITH DESIRED TO EMAIL]", "[REPLACE WITH DESIRED TO NAME]"));
var response = await client.SendEmailAsync(msg);
// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email.
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");You will need to put the above code and any subsequent code inside of the
Main method of the Program class if you are using older versions of .NET or older templates of .NET.Update the placeholder strings:
"[REPLACE WITH YOUR EMAIL]" with the email address you verified with your SendGrid account."[REPLACE WITH YOUR NAME]" with your name."[REPLACE WITH DESIRED TO EMAIL]" with the email address you want to send an email towards."[REPLACE WITH DESIRED TO NAME]" with the recipient's name.Save the Program.cs file.
The code above does the following:
apiKey variable.SendGridClient with the apiKey.SendGridMessage object with your email address as sender, and with a subject, and text content.SendGridMessage to the SendGrid API.When the SendGrid API responds with a successful HTTP status code, that does not necessarily mean that the email was successfully received by the recipient. It does however mean that the SendGrid API has accepted your request and will send the email. If the recipient does not receive the email, you can use the Email Activity Feed to find out why.
The application expects the API key to be stored in the SENDGRID_API_KEY environment variable.
Run the following command if you’re using a Bash or similar shell:
Run the following command if you’re using a Bash or similar shell:
export SENDGRID_API_KEY=[REPLACE WITH YOUR API KEY]Run the following command if you’re using PowerShell:
$Env:SENDGRID_API_KEY = "[REPLACE WITH YOUR API KEY]"Run the following command if you're using CMD:
set SENDGRID_API_KEY="[REPLACE WITH YOUR API KEY]"The environment variable will be available for the duration of your shell session. You'll have to set the environment variable again when opening a new shell.
Run the project using the .NET CLI:
dotnet runIf all went well, the output should be " Email queued successfully!".
Open the inbox of the recipient to verify you received the email. If you don't have access, you can use the Email Activity Feed to see the status of the email.
Here's what the email should look like:
Here's what the email should look like:
Chances are you don't always want to send the same email. You can ask for user input to make the application more flexible. Update Program.cs to match the content below:
using SendGrid;
using SendGrid.Helpers.Mail;
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
var client = new SendGridClient(apiKey);
Console.Write("To: ");
var toEmail = Console.ReadLine();
Console.Write("Subject: ");
var subject = Console.ReadLine();
Console.Write("Body: ");
var body = Console.ReadLine();
var msg = new SendGridMessage()
{
From = new EmailAddress("[REPLACE WITH YOUR EMAIL]", "[REPLACE WITH YOUR NAME]"),
Subject = subject,
PlainTextContent = body
};
msg.AddTo(new EmailAddress(toEmail));
var response = await client.SendEmailAsync(msg);
// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email.
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");The updated code asks for user input using
Console.ReadLine to get the subject, body, and recipient email address. Run the project again and answer the prompts:dotnet runCurrently, the sender's email address and the name are hardcoded, and the SendGrid API Key is configured through an environment variable. This is perfectly fine for a proof of concept, but you'll want to make the project more configurable. That's why you'll take advantage of the very pluggable configuration system that ships as part of .NET.
Add the following NuGet packages using the .NET CLI:
dotnet add package Microsoft.Extensions.Hosting
dotnet add package Microsoft.Extensions.Configuration.UserSecretsUpdate the Program.cs file to match the content below:
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SendGrid;
using SendGrid.Helpers.Mail;
using IHost host = Host.CreateDefaultBuilder(args).Build();
var config = host.Services.GetRequiredService<IConfiguration>();
var apiKey = config.GetValue<string>("SendGridApiKey");
var fromEmail = config.GetValue<string>("FromEmail");
var fromName = config.GetValue<string>("FromName");
if(string.IsNullOrEmpty(apiKey)) throw new Exception("SendGridApiKey should not be null or empty");
if(string.IsNullOrEmpty(fromEmail)) throw new Exception("FromEmail should not be null or empty");
if(string.IsNullOrEmpty(fromName)) throw new Exception("FromName should not be null or empty");
Console.Write("To:");
var toEmail = Console.ReadLine();
Console.Write("Subject:");
var subject = Console.ReadLine();
Console.Write("Body:");
var body = Console.ReadLine();
var client = new SendGridClient(apiKey);
var msg = new SendGridMessage()
{
From = new EmailAddress(fromEmail, fromName),
Subject = subject,
PlainTextContent = body
};
msg.AddTo(new EmailAddress(toEmail));
var response = await client.SendEmailAsync(msg);
// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email.
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");Host.CreateDefaultBuilder(args).Build(); will use multiple configuration sources by default, but most importantly:Read more about the default configuration sources at Microsoft Docs.
Create a new file named appsettings.json and add the following contents:
{
"FromEmail": "[ENTER YOUR FROM EMAIL]",
"FromName": "[ENTER YOUR FROM NAME]"
}This file will be used to configure the sender's email and name.
Using a JSON file as configuration works well to configure sender details, but is not a good fit for the API key. You can use user secrets for the API key.
Run the following command to initialize user secrets for your project:
dotnet user-secrets initRun the following command to set the API key as a user secret:
dotnet user-secrets set SendGridApiKey [PASTE IN YOUR SENDGRID API KEY]You can also set the sender email address as a user secret if you don't want to store your email address in the JSON file:
dotnet user-secrets set FromEmail [ENTER YOUR FROM EMAIL]The user secrets configuration will override the appsettings.json configuration.
As mentioned before, the user secrets will only be loaded when the environment is set as "Development". To do this, you can set an environment variable "DOTNET_ENVIRONMENT" to "Development". You can also pass it in as a command-line argument like this:
dotnet run --environment DevelopmentThe result should be exactly the same, but your application configuration is very flexible now.
If you deploy this console application somewhere else, the configuration can be changed using environment variables, command-line arguments, and JSON files.
User secrets are a great way to store secrets and load them into your configuration with .NET. User secrets prevent you from accidentally checking in your secrets to source control by storing the secrets outside of your project source. It is important to note that these secrets are still stored in plain text, just elsewhere in your personal folder.
You've made your application more configurable using the default host builder, but you can also further integrate SendGrid into your application. The SendGrid SDK for .NET has an extra NuGet package that will add the SendGrid client to the dependency injection container.
This is most commonly used for ASP.NET, but as you can see, you can also use ASP.NET's great built-in features by manually adding them into your console applications.
This is most commonly used for ASP.NET, but as you can see, you can also use ASP.NET's great built-in features by manually adding them into your console applications.
Run the following command to add the SendGrid dependency injection package:
dotnet add package SendGrid.Extensions.DependencyInjectionUpdate the Program.cs file:
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SendGrid;
using SendGrid.Helpers.Mail;
using SendGrid.Extensions.DependencyInjection;
using IHost host = Host.CreateDefaultBuilder(args)
.ConfigureServices((context, services) => services.AddSendGrid(options =>
options.ApiKey = context.Configuration.GetValue<string>("SendGridApiKey")
))
.Build();
var config = host.Services.GetRequiredService<IConfiguration>();
var apiKey = config.GetValue<string>("SendGridApiKey");
var fromEmail = config.GetValue<string>("FromEmail");
var fromName = config.GetValue<string>("FromName");
if(string.IsNullOrEmpty(apiKey)) throw new Exception("SendGridApiKey should not be null or empty");
if(string.IsNullOrEmpty(fromEmail)) throw new Exception("FromEmail should not be null or empty");
if(string.IsNullOrEmpty(fromName)) throw new Exception("FromName should not be null or empty");
Console.Write("To: ");
var toEmail = Console.ReadLine();
Console.Write("Subject: ");
var subject = Console.ReadLine();
Console.Write("Body: ");
var body = Console.ReadLine();
var client = host.Services.GetRequiredService<ISendGridClient>();
var msg = new SendGridMessage()
{
From = new EmailAddress(fromEmail, fromName),
Subject = subject,
PlainTextContent = body
};
msg.AddTo(new EmailAddress(toEmail));
var response = await client.SendEmailAsync(msg);
// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email.
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");You can configure additional services inside of the lambda passed to
ConfigureServices.Inside of this lambda, SendGrid is added as a service. To configure the options of SendGrid, another lambda is used and passed into
AddSendGrid. The lambda-inception can be tricky, so make sure to verify all your parentheses match the code above.Instead of constructing the
SendGridClient as you did before, the program now requests an instance of ISendGridClient from the dependency injection container using host.Services.GetRequiredService<ISendGridClient>().If you extend this application even further, you can also use constructor injection to receive any service.
Run the application again to verify everything still works as expected:
dotnet run --environment DevelopmentTwilio SendGrid helps you send and receive emails at scale.
You learned how to send emails using the SendGrid API and .NET 6 by following these steps:
Using what you learned here, you can also start integrating SendGrid into your ASP.NET Core applications. Twilio has a lot of other products you can integrate. Check out this tutorial on how to receive text messages using Twilio Programmable SMS and forward them using SendGrid emails with C# and ASP.NET Core.
Check out the following resources for more information on the topics and tools presented in this tutorial:
Niels Swimberghe is a Belgian software engineer and technical content creator at Twilio, working from the United States. Get in touch with Niels on Twitter @RealSwimburger and follow Niels’ personal blog on .NET, Azure, and web development at swimburger.net.
65