Transactional Email

Transactional email is the audited template system for operational messages and built-in AuthServer email. Every SqlOS implementation automatically gets templates for Email OTP, organization invitations, and password reset emails during startup.

Configure ACS Email#

SqlOS ships an Azure Communication Services sender:

builder.AddSqlOS<AppDbContext>(options =>
{
    options.ConfigureEmail(email =>
    {
        email.AzureCommunicationServicesConnectionString =
            builder.Configuration["SqlOS:Email:AzureCommunicationServicesConnectionString"];
        email.FromAddress = builder.Configuration["SqlOS:Email:FromAddress"];
    });
});

Use scripts/azure/setup-acs-email.sh to create ACS Email resources and DNS verification records.

Template syntax#

Templates use constrained {variable} placeholders in subject, HTML, and text bodies.

• HTML body substitutions are HTML-encoded.
• Subject and text substitutions are plain text replacements.
• Missing variables fail preview and send with a typed validation error.
• Extra variables are ignored.

Send by template key#

await email.SendAsync(new SqlOSSendEmailRequest(
    TemplateKey: "order-shipped",
    To: "user@example.com",
    Variables: new Dictionary<string, object?>
    {
        ["orderId"] = "123",
        ["trackingUrl"] = "https://tracking.example.test/123"
    },
    IdempotencyKey: "order-123-shipped"));

ISqlOSTransactionalEmailService returns the delivery id, status, template key/version, provider message id when available, and sanitized failure detail.

Dashboard#

Open SqlOS Dashboard > Communications.

• Templates: create, edit, activate, deactivate, delete templates without delivery history, and preview rendered output with sample variables.
• Messages: filter delivery log entries by status, template key, recipient, and date range.
• Built-in auth templates: auth.email-otp, auth.invitation, and auth.password-reset are created automatically and can be customized like other templates.

Retention and PII posture#

SqlOS stores delivery history with recipient, template key/version, status, timestamps, provider message id, sanitized error, rendered subject, and rendered text preview. It does not persist arbitrary variables JSON by default because variables can contain secrets.

Rendered HTML bodies are not stored unless options.Email.PersistRenderedHtmlPreview is enabled. options.Email.DeliveryRetention records the host retention policy value; SqlOS does not run a destructive cleanup worker in V0.

Built-in auth email#

Email OTP, organization invitations, and password reset emails use the built-in transactional templates by default. Their rendered bodies are suppressed in delivery history because they contain codes or token-bearing links.

Upgrade behavior is additive for normal AuthServer email configuration. Existing AuthServer.ConfigureEmailOtp(...) ACS settings continue to work; configuring options.Email is optional unless you want separate transactional email credentials.

Existing custom BuildMessage hooks still send through ISqlOSAuthEmailSender. Existing custom ISqlOSAuthEmailSender implementations also remain usable as the default rendered-template sender when no options.Email ACS sender is configured. Hosts that want a separate provider for all transactional templates can register ISqlOSEmailSender directly.