AuthServer
Transactional Email
Stored templates, safe rendering, send API, delivery history, and dashboard operations.
Transactional email is the audited template system for operational messages and built-in AuthServer email. Every SqlOS implementation automatically gets templates for Email OTP, magic links, organization invitations, and password reset emails during startup.
Follow Send transactional email to create, preview, send, retry, and inspect a real product template. This page remains the compact contract and operations reference.
Use Brand hosted authentication and email when the task is shared product identity across AuthPage and the three built-in auth templates. This page covers template and delivery behavior.
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.
Templates use constrained {variable} placeholders in subject, HTML, and text bodies.
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.
Open SqlOS Dashboard > Communications.
auth.email-otp, auth.magic-link, auth.invitation, and auth.password-reset are created automatically and can be customized like other templates.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 declares and validates the host retention policy value, but the current service does not consume it or run a destructive cleanup worker.
Email OTP, magic links, 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.