SMTP Configuration | BizFirst Email System

Best For General-purpose transactional email. Use SMTP if you already have an email provider or corporate mail server.

SMTP Configuration Parameters

Parameter	Type	Required	Example	Notes
`provider`	string	✅	smtp	Must be "smtp"
`host`	string	✅	smtp.gmail.com	SMTP server hostname
`port`	int	✅	587	25, 465, or 587
`ssl`	bool	✅	false	false=STARTTLS, true=SMTPS
`fromEmail`	string	✅	noreply@example.com	Sender email address
`fromName`	string	❌	My App	Display name for sender

Provider-Specific Configuration

Gmail (Free, Quota 100/day)

{
  "provider": "smtp",
  "host": "smtp.gmail.com",
  "port": 587,
  "ssl": false,
  "fromEmail": "your-email@gmail.com",
  "fromName": "Your App"
}

Credentials: Use app-specific password (not your regular Gmail password). Generate at myaccount.google.com/apppasswords

Office 365

{
  "provider": "smtp",
  "host": "smtp.office365.com",
  "port": 587,
  "ssl": false,
  "fromEmail": "noreply@yourdomain.onmicrosoft.com",
  "fromName": "Your Company"
}

Credentials: Use Office 365 account email and password. May require enabling "Allow less secure apps".

Custom SMTP Server

{
  "provider": "smtp",
  "host": "mail.company.local",
  "port": 25,
  "ssl": false,
  "fromEmail": "system@company.local",
  "fromName": "System Notifications"
}

Credentials: Depends on your server. Often username/password or no auth (internal network).

Port Selection Guide

Port	Protocol	SSL Field	Use Case
25	SMTP (unencrypted)	false	Internal networks, no TLS
465	SMTPS (implicit SSL)	true	Older servers, immediate encryption
587	SMTP + STARTTLS	false	Modern servers, upgrade after connect

Credential Creation

Choose a credential name (e.g., "email-primary", "email-smtp", etc.). Configure which name each tenant uses via TenantSettings with Key='EmailCredentialName'.

INSERT INTO AIExt_Credentials (
  Name,
  DisplayMetadata,
  EncryptedData,  -- Your SMTP password (AES-256-GCM encrypted)
  TenantID,
  CredentialTypeID,  -- 1 for PasswordRecord
  Enabled
) VALUES (
  'email-primary',  -- Or any name you configure in TenantSettings
  '{
    "provider": "smtp",
    "host": "smtp.gmail.com",
    "port": 587,
    "ssl": false,
    "fromEmail": "noreply@yourdomain.com",
    "fromName": "Your App"
  }',
  0x...,  -- Encrypted password
  1,      -- TenantID
  1,      -- PasswordRecord type
  1
);

Troubleshooting

"Authentication failed"

Gmail: Use app-specific password, not regular password
Office 365: Verify email address and password
Custom: Check username format (may need domain\username)

"Connection timeout"

Verify host is correct and reachable: telnet host port
Check firewall allows outbound connections
Verify port number is correct for your provider

"TLS failed"

Port 587 requires ssl: false (STARTTLS)
Port 465 requires ssl: true (implicit SSL)
Port 25 typically unencrypted

Testing Your Configuration

// Test with direct call
var result = await _emailService.SendAsync(
    tenantID: 1,
    to: "your-email@example.com",
    subject: "SMTP Test",
    html: "<p>If you see this, SMTP is working!</p>",
    credentialName: "email-smtp",
    ct: CancellationToken.None
);

if (result.Success)
    Console.WriteLine("✅ SMTP is working!");
else
    Console.WriteLine($"❌ Error: {result.ErrorMessage}");

Next Steps

First-Time Configuration — Full setup walkthrough
Credentials Design — Encryption and vault architecture
Tenant-Specific Providers — Per-tenant configuration