SendGrid C# Library

The SendGridPermissionsBuilder is used to define the scopes for new or existing API keys. You can add permissions using SendGridPermission enums, which by default include all associated scopes.

Key capabilities include:

• Granular Scopes: Use ScopeOptions.ReadOnly to limit a permission to read-only access.
• Exclusion Filters: Use .Exclude(predicate) to ensure certain scopes (like api_keys) are never included, even if requested by a permission enum.
• Manual Scope Inclusion: Use .Include(IEnumerable<string>) or .Include(params string[]) to add specific raw scope strings directly.
• Integration: Use the CreateApiKey extension method on SendGridClient to commit the builder's configuration to a new API key.

var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
var client = new SendGridClient(apiKey);
var builder = new SendGridPermissionsBuilder();

// Example: Add Alerts (all scopes) and Marketing Campaigns (read-only)
builder.AddPermissionsFor(SendGridPermission.Alerts);
builder.AddPermissionsFor(SendGridPermission.MarketingCampaigns, ScopeOptions.ReadOnly);

await client.CreateApiKey(builder, "Alerts & Read-Only Marketing Campaigns API Key");

Transactional templates can have multiple versions, each with its own subject and content. Users can have up to 300 versions across all templates.

Create a new version

Use POST /templates/{template_id}/versions to create a new version for a specific template.

Edit a version

Use PATCH /templates/{template_id}/versions/{version_id} to update an existing version.

Retrieve a version

Use GET /templates/{template_id}/versions/{version_id} to fetch details of a specific version.

Delete a version

Use DELETE /templates/{template_id}/versions/{version_id} to remove a version.

Activate a version

Use POST /templates/{template_id}/versions/{version_id}/activate to make a specific version the active one for the template.

// Example: Create a new version
string data = @"{
  'active': 1, 
  'html_content': '<%body%>', 
  'name': 'example_version_name', 
  'plain_content': '<%body%>', 
  'subject': '<%subject%>'
}";
var json = JsonConvert.DeserializeObject<Object>(data);
data = json.ToString();
var template_id = "test_url_param";
var response = await client.RequestAsync(method: SendGridClient.Method.POST, urlPath: "templates/" + template_id + "/versions", requestBody: data);

// Example: Activate a version
var template_id = "test_url_param";
var version_id = "test_url_param";
var response = await client.RequestAsync(method: SendGridClient.Method.POST, urlPath: "templates/" + template_id + "/versions/" + version_id + "/activate");

By default, retry behavior is disabled. To handle transient errors (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout), you must instantiate SendGridClient using SendGridClientOptions and configure ReliabilitySettings.

ReliabilitySettings Parameters:

• RetryCount: Number of retries (in addition to the initial attempt). Max is 5. Setting 1 results in 2 total attempts.
• MinimumBackOff: Minimum time to wait between retries.
• MaximumBackOff: Maximum time to wait between retries (Max 30 seconds).
• DeltaBackOff: Random delta used for exponential delay calculation to avoid synchronized retries.

var options = new SendGridClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY"),
    ReliabilitySettings = new ReliabilitySettings(2, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(3))
};

var client = new SendGridClient(options);

To run the Inbound Parse listener on your local machine, follow these steps:

1. Clone and Prepare: Clone the repository and navigate to the example directory.

   git clone https://github.com/sendgrid/sendgrid-csharp.git
   cd sendgrid-csharp/examples/inbound-webhook-handler
   dotnet restore

2. Run the Listener: Start the project using the Inbound.csproj file.

   dotnet run --project .\Src\Inbound\Inbound.csproj

3. Expose via ngrok: Since the server starts on a local port, use ngrok to create a public URL for SendGrid to hit.

   ngrok http PORT_NUMBER

4. Configure SendGrid: Update your SendGrid Incoming Parse settings:
   • HOSTNAME: Use the domain where you configured MX records (e.g., inbound.yourdomain.com).
   • URL: Use the ngrok URL appended with /inbound (e.g., http://XXXXXXX.ngrok.io/inbound).

Once configured, sending an email to [anything]@inbound.yourdomain.com will trigger the listener.

# Clone and prepare
git clone https://github.com/sendgrid/sendgrid-csharp.git
cd sendgrid-csharp/examples/inbound-webhook-handler
dotnet restore

# Run the listener
dotnet run --project .\Src\Inbound\Inbound.csproj

# Expose to the internet
ngrok http PORT_NUMBER

To use the Twilio Email client, you must first obtain a Twilio account and set up environment variables for authentication. The TwilioEmailClient provides the same interface as the SendGrid client.

Authentication Options:

1. API Key and Secret
2. Account SID and Auth Token

Environment Variable Setup (Linux/Mac):

echo "export TWILIO_API_KEY='YOUR_TWILIO_API_KEY'" > twilio.env
echo "export TWILIO_API_SECRET='YOUR_TWILIO_API_SECRET'" >> twilio.env
source ./twilio.env

Environment Variable Setup (Windows):

setx TWILIO_API_KEY "YOUR_TWILIO_API_KEY"
setx TWILIO_API_SECRET "YOUR_TWILIO_API_SECRET"

// Using API Key/Secret
var mailClient = new TwilioEmailClient(Environment.GetEnvironmentVariable("TWILIO_API_KEY"), Environment.GetEnvironmentVariable("TWILIO_API_SECRET"));

// OR using Account SID/Auth Token
var mailClient = new TwilioEmailClient(Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID"), Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN"));