Usage Examples & Patterns

Relevant source files

The following files were used as context for generating this wiki page:

• examples/ConsoleNoDi/Program.cs
• examples/WebMinimalApi/Program.cs
• examples/WebControllerApi/Program.cs
• README.md
• examples/README.md
• src/Resend/IResend.cs
• src/Resend/ResendClient.Templates.cs
• src/Resend/ResendClient.Contacts.cs
• tools/Resend.ApiServer/Controllers/AutomationController.cs
• tests/Resend.Tests/SuppressionTests.cs

Resend .NET SDK provides multiple patterns for integrating email delivery into .NET applications. It supports standard ASP.NET Core Dependency Injection (DI), standalone console applications, and advanced asynchronous workflows. Developers choose between direct string-based email composition or external rendering engines for complex HTML content.

The SDK exposes a core interface, IResend, which defines the contract for all supported Resend API operations. This includes email sending, contact management, domain verification, and automation control.

Integration Patterns

Dependency Injection Setup

Most ASP.NET Core applications use the AddResend extension method to register the client in the service container. You provide the API token via configuration options.

using Resend;

builder.Services.AddResend( o => 
{
    o.ApiToken = Environment.GetEnvironmentVariable( "RESEND_APITOKEN" )!;
} );

Sources: README.md:51-60

Console and Non-DI Usage

Applications without a service container instantiate the client manually. This pattern is common in simple scripts or legacy console tools.
Sources: examples/README.md:12, examples/ConsoleNoDi/Program.cs

Implementation Styles Comparison

Style	Context	Requirement
Minimal API	Modern Web Apps	IResend injected into route handlers
Controller API	Enterprise Web Apps	IResend injected into constructors
Razor Pages	Form-based Apps	IResend used in OnPost handlers
Console	Background Tools	Manual instantiation of ResendClient

Sources: examples/README.md:8-17, README.md:65-71

Email Sending Patterns

Basic Email Composition

You send emails by creating an EmailMessage object and passing it to EmailSendAsync. The SDK supports both plain text and HTML bodies.

var message = new EmailMessage();
message.From = "onboarding@resend.dev";
message.To.Add( "delivered@resend.dev" );
message.Subject = "hello world";
message.HtmlBody = "<strong>it works!</strong>";

await _resend.EmailSendAsync( message );

Sources: README.md:105-125, src/Resend/IResend.cs:22

Idempotent Sending

To prevent duplicate emails during network retries, you provide an idempotency key. The API ensures that multiple requests with the same key yield a single submission.

The diagram shows how an idempotency key protects against duplicate email delivery during transient failures.
Sources: src/Resend/IResend.cs:42-53, tests/Resend.Tests/SuppressionTests.cs:268-280

Batch Operations

The SDK allows sending multiple emails in a single request using EmailBatchAsync. You choose between strict validation (fails all if one is invalid) or per-message validation results.
Sources: src/Resend/IResend.cs:78-128

Asynchronous and Durable Patterns

Background Processing

Sending emails directly in request handlers can impact performance. The SDK integrates with background job libraries like Hangfire or Quartz.NET to offload delivery to worker threads.
Sources: examples/README.md:23-45

Durable Workflows

For critical delivery where failure is not an option, the SDK supports durable execution platforms like Temporal. This handles long-running retries and state management across service restarts.

This flowchart illustrates the retry logic typically implemented in durable workflow patterns.
Sources: examples/README.md:36-45

Template Rendering Patterns

Rendering Engines

Instead of hardcoding HTML strings in C#, you use rendering engines to generate dynamic content. The SDK provides examples for:

• Razor: Uses standard ASP.NET Core views for rich HTML structure.
• Fluid (Liquid): Uses a secure template language accessible to non-programmers.

Sources: examples/README.md:52-87

Resource Management

Contact and Audience Lifecycle

The SDK manages contacts via the ResendClient.Contacts module. You can add, retrieve, update, or delete contacts using either a unique identifier or an email address.

This diagram represents the typical lifecycle of a contact within the Resend system.
Sources: src/Resend/ResendClient.Contacts.cs:11-105, src/Resend/IResend.cs:338-400

Suppression Handling

Suppressions prevent delivery to specific addresses due to bounces, complaints, or manual requests. The SDK supports batch additions and removals to manage these lists efficiently.
Sources: src/Resend/IResend.cs:646-720, tests/Resend.Tests/SuppressionTests.cs:240-265

Automation and Webhooks

Automations trigger email sequences based on events. Controllers like AutomationController demonstrate how to structure these flows using steps and edges.

Component	Purpose
Automation Step	A discrete action like "trigger" or "send_email".
Automation Edge	Connects steps to define execution order.
Webhook Event	Notifies the application of email delivery status (e.g., delivered, opened).

Sources: tools/Resend.ApiServer/Controllers/AutomationController.cs:56-105, src/Resend/IResend.cs:725-780