Skip to main content

Email Notifications

Send emails via SMTP, SendGrid, or AWS SES with Liquid templates.

Step 1: Install the Package​

dotnet add package PrimusSaaS.Notifications --version 2.0.0

Step 2: Configure Program.cs​

Choose your email provider:

Option A: SMTP​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseSmtp(builder.Configuration.GetSection("Notifications:Smtp"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Option B: SendGrid​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseSendGrid(builder.Configuration.GetSection("Notifications:SendGrid"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Option C: AWS SES​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseAmazonSes(builder.Configuration.GetSection("Notifications:Ses"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Step 3: Configure appsettings.json​

SMTP Configuration​

{
  "Notifications": {
    "Smtp": {
      "Host": "smtp.example.com",
      "Port": 587,
      "Username": "your-username",
      "Password": "your-password",
      "EnableSsl": true,
      "FromAddress": "noreply@example.com",
      "FromName": "My App"
    }
  }
}

SendGrid Configuration​

{
  "Notifications": {
    "SendGrid": {
      "ApiKey": "SG.your-api-key",
      "FromAddress": "noreply@example.com",
      "FromName": "My App"
    }
  }
}
How to get your SendGrid API Key
  1. Go to SendGrid Dashboard
  2. Navigate to Settings API Keys
  3. Click Create API Key
  4. Select Restricted Access and enable Mail Send
  5. Copy the generated key (starts with SG.)

AWS SES Configuration​

{
  "Notifications": {
    "Ses": {
      "AccessKeyId": "AKIA...",
      "SecretAccessKey": "your-secret-key",
      "Region": "us-east-1",
      "FromAddress": "noreply@example.com",
      "FromName": "My App"
    }
  }
}
How to get your AWS SES credentials
  1. Go to AWS IAM Console
  2. Create a user with AmazonSESFullAccess policy
  3. Generate access keys for programmatic access
  4. Verify your sender email in SES console
  5. Request production access if needed (sandbox has limits)

Step 4: Create a Template​

NotificationTemplates/WelcomeEmail/EmailSubject.liquid​

Welcome to {{ app.name }}, {{ recipient.name }}!

NotificationTemplates/WelcomeEmail/EmailBody.liquid​

<!DOCTYPE html>
<html>
<body>
  <h1>Welcome, {{ recipient.name }}!</h1>
  <p>Thanks for joining {{ app.name }}.</p>
  <p><a href="{{ data.activationLink }}">Activate your account</a></p>
</body>
</html>

Step 5: Send an Email​

public class AccountService
{
    private readonly INotificationService _notifications;

    public AccountService(INotificationService notifications)
    {
        _notifications = notifications;
    }

    public async Task SendWelcomeEmail(string email, string name, string activationLink)
    {
        var result = await _notifications.SendAsync("WelcomeEmail", new
        {
            recipient = new { email, name },
            app = new { name = "My App" },
            data = new { activationLink }
        });

        if (!result.Success)
        {
            // Handle failure
            Console.WriteLine($"Failed: {result.FailureReason}");
        }
    }
}

Advanced: Direct Email (No Template)​

Send emails without templates:

app.MapPost("/send-direct", async (INotificationService notifications) =>
{
    var result = await notifications.SendEmailAsync(
        "recipient@example.com",
        "Hello!",
        "<p>This is a test email.</p>");
    
    return result.Success ? Results.Ok() : Results.Problem(result.FailureReason);
});

Advanced: Multiple Providers (Fallback)​

Configure multiple email providers for failover:

builder.Services.AddPrimusNotifications(n => n
    .UseSendGrid(builder.Configuration.GetSection("Notifications:SendGrid"))
    .UseSmtp(builder.Configuration.GetSection("Notifications:Smtp")) // Fallback
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

If SendGrid fails, SMTP will be used automatically.

Next Steps​

Want to...See Guide
Send SMSSMS Setup
Tenant-scoped notificationsMulti-Tenancy