Portal Community
Portal / WebSites / Email System / First-Time Config

First-Time Configuration

Complete step-by-step setup from zero to sending your first email.

8-Step Process

Step 1: Choose Your Provider

Decide: SMTP, AWS SES, or Gmail. See overview for comparison.

Step 2: Gather Credentials

Get username, password, API keys, or OAuth2 tokens from your provider. See provider-specific guides.

Step 3: Register Email Services in DI

// Program.cs
services.AddAiEmailServices();        // Core email orchestration
services.AddSmtpEmailDispatcher();    // SMTP provider
services.AddSesEmailDispatcher();     // AWS SES provider
services.AddGmailEmailDispatcher();   // Gmail OAuth2 provider
services.AddTenantSettingsService();  // For credential name resolution

Step 4: Create Credential in Database

INSERT INTO AIExt_Credentials (
  Name, DisplayMetadata, EncryptedData, TenantID, CredentialTypeID, Enabled
) VALUES (...)

Step 4b: Configure TenantSettings (Optional)

By default, the system uses "email-primary" as the credential name. To use a different name, configure TenantSettings:

-- Configure custom credential name for this tenant
INSERT INTO TenantSettings (TenantID, Key, Value)
VALUES (1, 'EmailCredentialName', 'email-alerts');
-- Now this tenant will use the 'email-alerts' credential instead of 'email-primary'

If not configured, defaults to "email-primary".

Step 5: Use IEmailService in Your Code

private readonly IEmailService _emailService;
private readonly ITenantSettingsService _tenantSettingsService;

// Inject and use:
public async Task SendEmail(int tenantID, string to, CancellationToken ct)
{
    var credentialName = await _tenantSettingsService.GetAsync<string>(
        tenantID, "EmailCredentialName", "email-primary", ct);

    var result = await _emailService.SendAsync(
        tenantID: tenantID,
        to: to,
        subject: "Test",
        html: "<p>Test</p>",
        credentialName: credentialName,
        ct: ct);
}

Step 6: Test with Unit Test

[Test]
public async Task SendEmail_WithValidCredential_Succeeds()
{
    var credentialName = await _tenantSettingsService.GetAsync<string>(
        1, "EmailCredentialName", "email-primary", CancellationToken.None);

    var result = await _emailService.SendAsync(
        tenantID: 1,
        to: "test@example.com",
        subject: "Test",
        html: "<p>Test</p>",
        credentialName: credentialName,
        ct: CancellationToken.None);

    Assert.IsTrue(result.Success);
}

Step 7: Run Integration Tests

Send real emails to test inboxes. Verify delivery time, format, attachments.

Step 8: Deploy to Production

Follow production deployment guide.

Verification Checklist

Next Steps