Skip to main content

Email & SMTP

OPS Beginner

Configure email sending with SMTP in EZ-Console.

Overview​

EZ-Console supports email sending via SMTP for notifications, password resets, MFA codes, and other system emails. SMTP settings can be configured through the admin console.

Accessing SMTP Settings​

Navigate to: System Settings → Email & SMTP

SMTP Configuration​

Basic SMTP Settings​

smtp:
  host: "smtp.example.com"
  port: 587
  username: "[email protected]"
  password: "your-password"
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

Configuration Options​

  • host: SMTP server hostname (required)
  • port: SMTP server port (default: 587 for TLS, 465 for SSL, 25 for plain)
  • username: SMTP username (required)
  • password: SMTP password (required)
  • from_email: Sender email address (required)
  • from_name: Sender display name (optional)
  • use_tls: Use TLS encryption (default: true)
  • use_ssl: Use SSL encryption (default: false)

Common SMTP Providers​

Gmail​

smtp:
  host: "smtp.gmail.com"
  port: 587
  username: "[email protected]"
  password: "your-app-password"  # Use App Password, not regular password
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

Note: For Gmail, you need to:

  1. Enable 2-Step Verification
  2. Generate an App Password
  3. Use the App Password instead of your regular password

Outlook/Office 365​

smtp:
  host: "smtp.office365.com"
  port: 587
  username: "[email protected]"
  password: "your-password"
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

SendGrid​

smtp:
  host: "smtp.sendgrid.net"
  port: 587
  username: "apikey"
  password: "your-sendgrid-api-key"
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

Amazon SES​

smtp:
  host: "email-smtp.us-east-1.amazonaws.com"  # Use your region
  port: 587
  username: "your-ses-smtp-username"
  password: "your-ses-smtp-password"
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

Custom SMTP Server​

smtp:
  host: "mail.example.com"
  port: 587
  username: "[email protected]"
  password: "secure-password"
  from_email: "[email protected]"
  from_name: "EZ-Console"
  use_tls: true

Configuration via UI​

  1. Navigate to System Settings → Email & SMTP
  2. Enter SMTP server details
  3. Click Test Connection to verify
  4. Click Save to apply settings

Configuration via API​

Get SMTP Settings​

GET /api/system/settings/smtp

Response:

{
  "code": "0",
  "data": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "[email protected]",
    "from_email": "[email protected]",
    "from_name": "EZ-Console",
    "use_tls": true
  }
}

Update SMTP Settings​

PUT /api/system/settings/smtp

Request Body:

{
  "host": "smtp.example.com",
  "port": 587,
  "username": "[email protected]",
  "password": "your-password",
  "from_email": "[email protected]",
  "from_name": "EZ-Console",
  "use_tls": true
}

Testing SMTP Connection​

Via UI​

  1. Go to System Settings → Email & SMTP
  2. Enter SMTP settings
  3. Click Test Connection
  4. Check test email in your inbox

Via API​

POST /api/system/settings/smtp/test

Request Body:

{
  "to": "[email protected]",
  "subject": "Test Email",
  "body": "This is a test email from EZ-Console"
}

Email Templates​

EZ-Console uses email templates for system emails:

  • Password Reset: Sent when user requests password reset
  • MFA Code: Sent for email-based MFA
  • Welcome Email: Sent to new users (if enabled)
  • Account Locked: Sent when account is locked

Using Email in Code​

Send Email via Service​

import (
    "context"
    "github.com/sven-victor/ez-console/server"
)

func SendNotification(ctx context.Context, svc server.Service, to []string, subject, body string) error {
    smtpSettings, err := svc.GetSMTPSettings(ctx)
    if err != nil {
        return err
    }
    
    return svc.SendEmail(ctx, smtpSettings, to, subject, body)
}

Troubleshooting​

Connection Failed​

Symptom: Cannot connect to SMTP server

Solutions:

  1. Verify host and port are correct
  2. Check firewall rules
  3. Verify credentials
  4. Try different ports (587, 465, 25)

Authentication Failed​

Symptom: Authentication error

Solutions:

  1. Verify username and password
  2. For Gmail, use App Password
  3. Check if account requires 2FA
  4. Verify account is not locked

Emails Not Received​

Symptom: Emails sent but not received

Solutions:

  1. Check spam folder
  2. Verify sender email is not blocked
  3. Check SMTP server logs
  4. Verify recipient email is valid

TLS/SSL Errors​

Symptom: TLS handshake failed

Solutions:

  1. Verify use_tls or use_ssl settings
  2. Check port matches encryption type
  3. Verify certificate is valid
  4. Try different port

Security Best Practices​

1. Use App Passwords​

For services like Gmail, use App Passwords instead of regular passwords.

2. Encrypt Connections​

Always use TLS or SSL for SMTP connections.

3. Secure Credentials​

Store SMTP passwords securely, never in code or config files.

4. Limit Access​

Restrict SMTP settings to admin users only.

Need help? Ask in GitHub Discussions.