AWS SES Email Service

Overview

This skill implements email delivery via AWS SES for APIs:

• AWS SES Integration - Production-ready email delivery

• HTML Templates - File-based templates with placeholder replacement

• Result Pattern - No exceptions, returns Result<T> for error handling

• Enable/Disable Toggle - Development mode without actual sending

Quick Reference

Component Purpose Location

IEmailService

Email abstraction interface Application/Abstractions/Email

AwsSesEmailService

AWS SES implementation Infrastructure/Email

EmailOptions

AWS SES configuration Infrastructure/Email

EmailErrors

Error definitions Application/Abstractions/Email

Email Structure

/Application/Abstractions/ ├── Email/ │ ├── IEmailService.cs │ └── EmailErrors.cs

/Infrastructure/ ├── Email/ │ ├── EmailOptions.cs │ └── AwsSesEmailService.cs

/Api/ ├── EmailTemplates/ │ ├── appointment-reminder.html │ ├── appointment-reminder-es.html │ ├── test-results-ready.html │ ├── prescription-ready.html │ ├── welcome.html │ └── password-reset.html

Template: Email Service Interface

// src/{name}.application/Abstractions/Email/IEmailService.cs using {name}.domain.abstractions;

namespace {name}.application.Abstractions.Email;

/// <summary> /// Service for sending emails via AWS SES /// Returns Result pattern for error handling (no exceptions) /// </summary> public interface IEmailService { /// <summary> /// Send an email using a template file with placeholder replacements /// </summary> /// <param name="toEmail">Recipient email address</param> /// <param name="subject">Email subject</param> /// <param name="templateName">Name of the template file (without extension)</param> /// <param name="placeholders">Dictionary of placeholder keys and replacement values</param> /// <param name="cancellationToken">Cancellation token</param> /// <returns>Result indicating success or failure</returns> Task<r> SendTemplatedEmailAsync( string toEmail, string subject, string templateName, Dictionary<string, string> placeholders, CancellationToken cancellationToken = default);

/// <summary>
/// Send an email with raw HTML content
/// </summary>
/// <param name="toEmail">Recipient email address</param>
/// <param name="subject">Email subject</param>
/// <param name="htmlBody">HTML content of the email</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>Result indicating success or failure</returns>
Task<r> SendHtmlEmailAsync(
    string toEmail,
    string subject,
    string htmlBody,
    CancellationToken cancellationToken = default);

}

Template: Email Errors

// src/{name}.application/Abstractions/Email/EmailErrors.cs using {name}.domain.abstractions;

namespace {name}.application.Abstractions.Email;

public static class EmailErrors { public static readonly Error SendFailed = new( "Email.SendFailed", "Failed to send email. Please try again later.");

public static readonly Error TemplateNotFound = new(
    "Email.TemplateNotFound",
    "Email template not found.");

public static readonly Error InvalidRecipient = new(
    "Email.InvalidRecipient",
    "Invalid recipient email address.");

public static readonly Error EmailDisabled = new(
    "Email.Disabled",
    "Email sending is currently disabled.");

}

Template: Email Options

// src/{name}.infrastructure/Email/EmailOptions.cs namespace {name}.infrastructure.Email;

public sealed class EmailOptions { public const string SectionName = "Email";

/// <summary>
/// AWS region for SES (e.g., "us-east-1")
/// </summary>
public string AwsRegion { get; init; } = "us-east-1";

/// <summary>
/// AWS access key ID (optional - use IAM role in production)
/// </summary>
public string? AwsAccessKeyId { get; init; }

/// <summary>
/// AWS secret access key (optional - use IAM role in production)
/// </summary>
public string? AwsSecretAccessKey { get; init; }

/// <summary>
/// Email address to send from
/// </summary>
public string FromAddress { get; init; } = string.Empty;

/// <summary>
/// Display name for the sender (e.g., "Support Team")
/// </summary>
public string FromName { get; init; } = string.Empty;

/// <summary>
/// Whether email sending is enabled (disable for development)
/// </summary>
public bool Enabled { get; init; } = false;

/// <summary>
/// Path to email templates directory (relative to app base)
/// </summary>
public string TemplatesPath { get; init; } = "EmailTemplates";

}

appsettings.json

{ "Email": { "AwsRegion": "us-east-1", "AwsAccessKeyId": "", "AwsSecretAccessKey": "", "FromAddress": "noreply@healthcare.example.com", "FromName": "Supoort Team", "Enabled": true, "TemplatesPath": "EmailTemplates" } }

Template: AWS SES Email Service Implementation

// src/{name}.infrastructure/Email/AwsSesEmailService.cs using Amazon; using Amazon.SimpleEmailV2; using Amazon.SimpleEmailV2.Model; using {name}.application.Abstractions.Email; using {name}.domain.abstractions; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options;

namespace {name}.infrastructure.Email;

internal sealed class AwsSesEmailService : IEmailService { private readonly EmailOptions _options; private readonly ILogger<AwsSesEmailService> _logger; private readonly IAmazonSimpleEmailServiceV2 _sesClient; private readonly string _templatesPath;

public AwsSesEmailService(
    IOptions<EmailOptions> options,
    ILogger<AwsSesEmailService> logger)
{
    _options = options.Value;
    _logger = logger;

    // Initialize SES v2 client
    var region = RegionEndpoint.GetBySystemName(_options.AwsRegion);

    if (!string.IsNullOrEmpty(_options.AwsAccessKeyId) &&
        !string.IsNullOrEmpty(_options.AwsSecretAccessKey))
    {
        // Use explicit credentials (dev/staging)
        _sesClient = new AmazonSimpleEmailServiceV2Client(
            _options.AwsAccessKeyId,
            _options.AwsSecretAccessKey,
            region);
    }
    else
    {
        // Use IAM role or environment credentials (production)
        _sesClient = new AmazonSimpleEmailServiceV2Client(region);
    }

    // Set templates path relative to application base directory
    _templatesPath = Path.Combine(
        AppDomain.CurrentDomain.BaseDirectory, 
        _options.TemplatesPath);
}

public async Task<r> SendTemplatedEmailAsync(
    string toEmail,
    string subject,
    string templateName,
    Dictionary<string, string> placeholders,
    CancellationToken cancellationToken = default)
{
    // Load template file
    var templatePath = Path.Combine(_templatesPath, $"{templateName}.html");

    if (!File.Exists(templatePath))
    {
        _logger.LogError("Email template not found: {TemplatePath}", templatePath);
        return Result.Failure(EmailErrors.TemplateNotFound);
    }

    var htmlBody = await File.ReadAllTextAsync(templatePath, cancellationToken);

    // Replace placeholders using {{key}} syntax
    foreach (var (key, value) in placeholders)
    {
        htmlBody = htmlBody.Replace($"{{{{{key}}}}}", value);
    }

    return await SendHtmlEmailAsync(toEmail, subject, htmlBody, cancellationToken);
}

public async Task<r> SendHtmlEmailAsync(
    string toEmail,
    string subject,
    string htmlBody,
    CancellationToken cancellationToken = default)
{
    // Development mode - log but don't send
    if (!_options.Enabled)
    {
        _logger.LogWarning(
            "Email disabled. Would send to {Email}: {Subject}",
            toEmail, subject);
        return Result.Success();
    }

    // Validate recipient
    if (string.IsNullOrWhiteSpace(toEmail))
    {
        _logger.LogWarning("Cannot send email: recipient address is empty");
        return Result.Failure(EmailErrors.InvalidRecipient);
    }

    try
    {
        // Format sender address
        var fromAddress = string.IsNullOrEmpty(_options.FromName)
            ? _options.FromAddress
            : $"{_options.FromName} <{_options.FromAddress}>";

        var request = new SendEmailRequest
        {
            FromEmailAddress = fromAddress,
            Destination = new Destination
            {
                ToAddresses = new List<string> { toEmail }
            },
            Content = new EmailContent
            {
                Simple = new Message
                {
                    Subject = new Content { Data = subject, Charset = "UTF-8" },
                    Body = new Body
                    {
                        Html = new Content { Data = htmlBody, Charset = "UTF-8" }
                    }
                }
            }
        };

        var response = await _sesClient.SendEmailAsync(request, cancellationToken);

        _logger.LogInformation(
            "Email sent to {Email}. MessageId: {MessageId}",
            toEmail, response.MessageId);

        return Result.Success();
    }
    catch (MessageRejectedException ex)
    {
        _logger.LogError(ex, "Email rejected for {Email}", toEmail);
        return Result.Failure(EmailErrors.SendFailed);
    }
    catch (MailFromDomainNotVerifiedException ex)
    {
        _logger.LogError(ex, "From domain not verified: {FromAddress}", _options.FromAddress);
        return Result.Failure(EmailErrors.SendFailed);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Failed to send email to {Email}", toEmail);
        return Result.Failure(EmailErrors.SendFailed);
    }
}

}

Template: Dependency Injection Registration

// src/{name}.infrastructure/DependencyInjection.cs private static void AddEmail(IServiceCollection services, IConfiguration configuration) { // Configure email options services.Configure<EmailOptions>(configuration.GetSection(EmailOptions.SectionName));

// Register email service
services.AddScoped<IEmailService, AwsSesEmailService>();

}

Email Templates

Template: Appointment Reminder

<!-- EmailTemplates/appointment-reminder.html --> <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Appointment Reminder</title> </head> <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;"> <div style="max-width: 600px; margin: 0 auto; padding: 20px;"> <h1 style="color: #2c5aa0;">Appointment Reminder</h1>

    <p>Dear {{patient_name}},</p>
    
    <p>This is a reminder of your upcoming appointment:</p>
    
    <div style="background-color: #f5f5f5; padding: 15px; border-radius: 5px; margin: 20px 0;">
        <p><strong>Date:</strong> {{appointment_date}}</p>
        <p><strong>Time:</strong> {{appointment_time}}</p>
        <p><strong>Provider:</strong> {{provider_name}}</p>
        <p><strong>Location:</strong> {{clinic_address}}</p>
        <p><strong>Appointment Type:</strong> {{appointment_type}}</p>
    </div>
    
    <h3>Before Your Visit</h3>
    <ul>
        <li>Please arrive 15 minutes early</li>
        <li>Bring your insurance card and photo ID</li>
        <li>Bring a list of current medications</li>
    </ul>
    
    <p>If you need to reschedule or cancel, please contact us at least 24 hours in advance.</p>
    
    <p>
        <a href="{{cancel_url}}" style="color: #2c5aa0;">Cancel Appointment</a> | 
        <a href="{{reschedule_url}}" style="color: #2c5aa0;">Reschedule</a>
    </p>
    
    <hr style="border: none; border-top: 1px solid #ddd; margin: 30px 0;">
    
    <p style="font-size: 12px; color: #666;">
        {{clinic_name}}<br>
        {{clinic_phone}}<br>
        <em>This is an automated message. Please do not reply directly to this email.</em>
    </p>
</div>

</body> </html>

Template: Test Results Ready

<!-- EmailTemplates/test-results-ready.html --> <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Test Results Available</title> </head> <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;"> <div style="max-width: 600px; margin: 0 auto; padding: 20px;"> <h1 style="color: #2c5aa0;">Your Test Results Are Ready</h1>

    <p>Dear {{patient_name}},</p>
    
    <p>Your test results from <strong>{{test_date}}</strong> are now available for review.</p>
    
    <div style="background-color: #e8f4f8; padding: 15px; border-radius: 5px; margin: 20px 0;">
        <p><strong>Test Type:</strong> {{test_type}}</p>
        <p><strong>Ordered By:</strong> {{ordering_provider}}</p>
    </div>
    
    <p>
        <a href="{{portal_url}}" style="display: inline-block; background-color: #2c5aa0; color: white; padding: 12px 24px; text-decoration: none; border-radius: 5px;">
            View Results in Patient Portal
        </a>
    </p>
    
    <p style="margin-top: 20px;">
        <strong>Note:</strong> For questions about your results, please contact your healthcare 
        provider directly or send a message through the patient portal.
    </p>
    
    <hr style="border: none; border-top: 1px solid #ddd; margin: 30px 0;">
    
    <p style="font-size: 12px; color: #666;">
        <strong>HIPAA Notice:</strong> This email contains protected health information (PHI). 
        It is intended only for the individual named above. If you received this in error, 
        please delete it and notify us immediately.
    </p>
</div>

</body> </html>

Template: Welcome Email

<!-- EmailTemplates/welcome.html --> <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Welcome to {{clinic_name}}</title> </head> <body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;"> <div style="max-width: 600px; margin: 0 auto; padding: 20px;"> <h1 style="color: #2c5aa0;">Welcome to {{clinic_name}}</h1>

    <p>Dear {{patient_name}},</p>
    
    <p>Thank you for registering with us. Your patient portal account has been created.</p>
    
    <h3>Getting Started</h3>
    <ul>
        <li>Complete your health history</li>
        <li>Add your insurance information</li>
        <li>Review your upcoming appointments</li>
        <li>Set up prescription refill reminders</li>
    </ul>
    
    <p>
        <a href="{{portal_url}}" style="display: inline-block; background-color: #2c5aa0; color: white; padding: 12px 24px; text-decoration: none; border-radius: 5px;">
            Access Patient Portal
        </a>
    </p>
    
    <h3>Contact Us</h3>
    <p>
        Phone: {{clinic_phone}}<br>
        Email: {{clinic_email}}<br>
        Address: {{clinic_address}}
    </p>
    
    <hr style="border: none; border-top: 1px solid #ddd; margin: 30px 0;">
    
    <p style="font-size: 12px; color: #666;">
        Questions? Contact our support team at {{support_email}}
    </p>
</div>

</body> </html>

Usage Examples

Sending Appointment Reminder

public class SendAppointmentReminderHandler { private readonly IEmailService _emailService;

public async Task<Result> Handle(SendReminderCommand command, CancellationToken ct)
{
    var placeholders = new Dictionary<string, string>
    {
        ["patient_name"] = command.PatientName,
        ["appointment_date"] = command.AppointmentDate.ToString("MMMM d, yyyy"),
        ["appointment_time"] = command.AppointmentTime.ToString("h:mm tt"),
        ["provider_name"] = command.ProviderName,
        ["clinic_address"] = command.ClinicAddress,
        ["appointment_type"] = command.AppointmentType,
        ["cancel_url"] = $"https://portal.example.com/cancel/{command.AppointmentId}",
        ["reschedule_url"] = $"https://portal.example.com/reschedule/{command.AppointmentId}",
        ["clinic_name"] = "HealthCare Medical Center",
        ["clinic_phone"] = "(555) 123-4567"
    };

    var result = await _emailService.SendTemplatedEmailAsync(
        toEmail: command.PatientEmail,
        subject: $"Appointment Reminder - {command.AppointmentDate:MMM d}",
        templateName: "appointment-reminder",
        placeholders: placeholders,
        cancellationToken: ct);

    if (result.IsFailure)
    {
        // Log failure but don't throw
        _logger.LogWarning("Failed to send reminder to {Email}", command.PatientEmail);
    }

    return result;
}

}

Sending Test Results Notification

public class NotifyTestResultsReadyHandler { private readonly IEmailService _emailService; private readonly ISecurityAuditService _auditService;

public async Task<Result> Handle(NotifyResultsCommand command, CancellationToken ct)
{
    var placeholders = new Dictionary<string, string>
    {
        ["patient_name"] = command.PatientName,
        ["test_date"] = command.TestDate.ToString("MMMM d, yyyy"),
        ["test_type"] = command.TestType,
        ["ordering_provider"] = command.OrderingProvider,
        ["portal_url"] = $"https://portal.example.com/results/{command.ResultId}"
    };

    var result = await _emailService.SendTemplatedEmailAsync(
        toEmail: command.PatientEmail,
        subject: "Your Test Results Are Ready",
        templateName: "test-results-ready",
        placeholders: placeholders,
        cancellationToken: ct);

    // HIPAA: Audit the notification
    await _auditService.LogAsync(
        eventType: "PHI_ACCESS_NOTIFICATION",
        severity: "INFO",
        eventDescription: $"Test results notification sent for {command.TestType}",
        userId: command.PatientId,
        metadata: new { TestId = command.ResultId });

    return result;
}

}

Localized Templates

// Use template naming convention for localization public async Task<Result> SendAppointmentReminderAsync( string email, string patientName, DateTime appointmentDate, string language, CancellationToken ct) { // Template names: appointment-reminder.html, appointment-reminder-es.html var templateName = language.ToLower() switch { "es" => "appointment-reminder-es", "fr" => "appointment-reminder-fr", _ => "appointment-reminder" };

var subject = language.ToLower() switch
{
    "es" => "Recordatorio de Cita",
    "fr" => "Rappel de Rendez-vous",
    _ => "Appointment Reminder"
};

return await _emailService.SendTemplatedEmailAsync(
    toEmail: email,
    subject: subject,
    templateName: templateName,
    placeholders: new Dictionary<string, string>
    {
        ["patient_name"] = patientName,
        ["appointment_date"] = appointmentDate.ToString("MMMM d, yyyy")
    },
    cancellationToken: ct);

}

Anti-Patterns to Avoid

// ❌ WRONG: Throwing exceptions on failure if (!File.Exists(templatePath)) throw new EmailTemplateNotFoundException(templateName);

// ✅ CORRECT: Return Result for graceful handling if (!File.Exists(templatePath)) return Result.Failure(EmailErrors.TemplateNotFound);

// ❌ WRONG: Logging email content _logger.LogInformation("Sending email: {Body}", htmlBody);

// ✅ CORRECT: Log only metadata _logger.LogInformation("Sending email to {Email}: {Subject}", toEmail, subject);

// ❌ WRONG: Hardcoding template paths var path = "/app/templates/email.html";

// ✅ CORRECT: Use configuration var path = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, _options.TemplatesPath);

Related Skills

• domain-events-generator - Trigger emails from events
• quartz-background-jobs - Scheduled email jobs
• outbox-pattern - Reliable email delivery