Azure Functions SendGrid bindings

This article explains how to send email by using SendGrid bindings in Azure Functions. Azure Functions supports an output binding for SendGrid.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

Packages - Functions 1.x

The SendGrid bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SendGrid NuGet package, version 2.x. Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

The following table tells how to add support for this binding in each development environment.

Development environment To add support in
Functions 1.x
Local development - C# class library Install the package
Local development - C# script, JavaScript, F# Automatic
Portal development Automatic

Packages - Functions 2.x and higher

The SendGrid bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SendGrid NuGet package, version 3.x. Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Add support in you preferred development environment using the following methods.

Development environment Application type To add support
Visual Studio C# class library Install the NuGet package
Visual Studio Code Based on core tools Register the extension bundle

Installing the Azure Tools extension is recommended.
Any other editor/IDE Based on core tools Register the extension bundle
Azure Portal Online only in portal Installs when adding a binding

See Update your extensions to update existing binding extensions without having to republish your function app.

Example

The following example shows a C# function that uses a Service Bus queue trigger and a SendGrid output binding.

Synchronous

[FunctionName("SendEmail")]
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] Message email,
    [SendGrid(ApiKey = "CustomSendGridKeyAppSettingName")] out SendGridMessage message)
{
var emailObject = JsonConvert.DeserializeObject<OutgoingEmail>(Encoding.UTF8.GetString(email.Body));

message = new SendGridMessage();
message.AddTo(emailObject.To);
message.AddContent("text/html", emailObject.Body);
message.SetFrom(new EmailAddress(emailObject.From));
message.SetSubject(emailObject.Subject);
}

public class OutgoingEmail
{
    public string To { get; set; }
    public string From { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

Asynchronous

[FunctionName("SendEmail")]
public static async void Run(
 [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] Message email,
 [SendGrid(ApiKey = "CustomSendGridKeyAppSettingName")] IAsyncCollector<SendGridMessage> messageCollector)
{
 var emailObject = JsonConvert.DeserializeObject<OutgoingEmail>(Encoding.UTF8.GetString(email.Body));

 var message = new SendGridMessage();
 message.AddTo(emailObject.To);
 message.AddContent("text/html", emailObject.Body);
 message.SetFrom(new EmailAddress(emailObject.From));
 message.SetSubject(emailObject.Subject);
 
 await messageCollector.AddAsync(message);
}

public class OutgoingEmail
{
 public string To { get; set; }
 public string From { get; set; }
 public string Subject { get; set; }
 public string Body { get; set; }
}

You can omit setting the attribute's ApiKey property if you have your API key in an app setting named "AzureWebJobsSendGridApiKey".

Attributes and annotations

In C# class libraries, use the SendGrid attribute.

For information about attribute properties that you can configure, see Configuration. Here's a SendGrid attribute example in a method signature:

[FunctionName("SendEmail")]
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] OutgoingEmail email,
    [SendGrid(ApiKey = "CustomSendGridKeyAppSettingName")] out SendGridMessage message)
{
    ...
}

For a complete example, see C# example.

Configuration

The following table lists the binding configuration properties available in the function.json file and the SendGrid attribute/annotation.

function.json property Attribute/annotation property Description Optional
type n/a Must be set to sendGrid. No
direction n/a Must be set to out. No
name n/a The variable name used in function code for the request or request body. This value is $return when there is only one return value. No
apiKey ApiKey The name of an app setting that contains your API key. If not set, the default app setting name is AzureWebJobsSendGridApiKey. No
to To The recipient's email address. Yes
from From The sender's email address. Yes
subject Subject The subject of the email. Yes
text Text The email content. Yes

Optional properties may have default values defined in the binding and either added or overridden programmatically.

When you're developing locally, app settings go into the local.settings.json file.

host.json settings

This section describes the global configuration settings available for this binding in versions 2.x and higher. The example host.json file below contains only the version 2.x+ settings for this binding. For more information about global configuration settings in versions 2.x and beyond, see host.json reference for Azure Functions.

Note

For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "sendGrid": {
            "from": "Azure Functions <samples@functions.com>"
        }
    }
}
Property Default Description
from n/a The sender's email address across all functions.

Next steps