SMTP Configuration Guide

Complete guide to configuring email notifications for ATStatus. This guide covers all major email providers with step-by-step instructions.

Overview

ATStatus supports any SMTP server. This guide provides detailed configuration instructions for the most common email providers. Choose your provider from the list below or use the generic settings for other providers.

Supported Providers

• Microsoft 365 / Exchange Online
• Gmail / Google Workspace
• cPanel / Webmail
• DirectAdmin
• Generic SMTP Server

Environment Variables

Add these variables to your .env file to configure SMTP:

Microsoft 365 / Exchange Online

Step 1: Prepare Your Account

You have two options for authenticating with Microsoft 365:

Option A: App Password (Recommended for Personal Accounts)

1. Go to Microsoft Account Security
2. Click Advanced security options
3. Under "Additional security", enable Two-step verification (required for app passwords)
4. After enabling 2FA, go back to Advanced security options
5. Under "App passwords", click Create a new app password
6. Copy the generated 16-character password immediately (you won't see it again)

Option B: SMTP AUTH with Organization Account

If you're using a Microsoft 365 organization account, your admin may need to enable SMTP AUTH:

1. Sign in to Microsoft 365 Admin Center
2. Go to Users → Active users
3. Select the user account you'll use for sending emails
4. Click the Mail tab
5. Under "Email apps", click Manage email apps
6. Enable Authenticated SMTP
7. Click Save changes

Step 2: Configure ATStatus

Add these settings to your .env file:

# Microsoft 365 SMTP Configuration
SMTP_HOST="smtp.office365.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="your-email@yourdomain.com"
SMTP_PASS="your-app-password-or-account-password"
SMTP_FROM="your-email@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

Microsoft 365 Troubleshooting

Gmail / Google Workspace

Step 1: Enable 2-Factor Authentication

App passwords require 2-factor authentication to be enabled:

1. Go to Google Account Security
2. Under "How you sign in to Google", click 2-Step Verification
3. Follow the prompts to enable 2-Step Verification
4. Choose your preferred verification method (phone, authenticator app, etc.)

Step 2: Create an App Password

1. Go to Google App Passwords
2. You may need to sign in again
3. Under "Select app", choose Other (Custom name)
4. Enter a name like ATStatus
5. Click Generate
6. Copy the 16-character password (spaces don't matter)

Step 3: Configure ATStatus

# Gmail SMTP Configuration
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="xxxx xxxx xxxx xxxx"
SMTP_FROM="your-email@gmail.com"
SMTP_FROM_NAME="Status Alerts"

Alternative: SSL Configuration (Port 465)

# Gmail SMTP with SSL
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="465"
SMTP_SECURE="true"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="xxxx xxxx xxxx xxxx"
SMTP_FROM="your-email@gmail.com"
SMTP_FROM_NAME="Status Alerts"

Google Workspace Additional Steps

If you're using Google Workspace (business), you may need to enable SMTP relay:

1. Sign in to Google Admin Console
2. Go to Apps → Google Workspace → Gmail → Routing
3. Under "SMTP relay service", click Configure
4. Add a new SMTP relay configuration
5. Set "Allowed senders" to "Only registered Apps users in my domains"
6. Enable "Require SMTP Authentication"
7. Click Save

Gmail Troubleshooting

cPanel / Webmail

Step 1: Find Your SMTP Settings

1. Log in to your cPanel dashboard
2. Go to Email → Email Accounts
3. Click Connect Devices next to your email account
4. Note the "Outgoing Server" details

Step 2: Create an Email Account (if needed)

1. In cPanel, go to Email → Email Accounts
2. Click Create
3. Enter the username (e.g., alerts)
4. Set a strong password and note it down
5. Set the mailbox quota (250 MB is usually enough)
6. Click Create

Step 3: Configure ATStatus

# cPanel SMTP Configuration
SMTP_HOST="mail.yourdomain.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="alerts@yourdomain.com"
SMTP_PASS="your-email-password"
SMTP_FROM="alerts@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

Alternative: SSL Configuration (Port 465)

# cPanel SMTP with SSL
SMTP_HOST="mail.yourdomain.com"
SMTP_PORT="465"
SMTP_SECURE="true"
SMTP_USER="alerts@yourdomain.com"
SMTP_PASS="your-email-password"
SMTP_FROM="alerts@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

cPanel Troubleshooting

DirectAdmin

Step 1: Find Your SMTP Settings

1. Log in to DirectAdmin
2. Go to Email Manager
3. Click Email Accounts
4. Click on your email account
5. Click Email Client Configuration
6. Note the SMTP server and port

Step 2: Create an Email Account (if needed)

1. In DirectAdmin, go to Email Manager → Email Accounts
2. Click Create Mail Account
3. Enter the username (e.g., alerts)
4. Set a strong password
5. Set the quota (optional)
6. Click Create

Step 3: Configure ATStatus

# DirectAdmin SMTP Configuration
SMTP_HOST="mail.yourdomain.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="alerts@yourdomain.com"
SMTP_PASS="your-email-password"
SMTP_FROM="alerts@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

With SSL (Port 465)

# DirectAdmin SMTP with SSL
SMTP_HOST="mail.yourdomain.com"
SMTP_PORT="465"
SMTP_SECURE="true"
SMTP_USER="alerts@yourdomain.com"
SMTP_PASS="your-email-password"
SMTP_FROM="alerts@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

DirectAdmin Troubleshooting

Generic SMTP Server

For other SMTP providers, use these general guidelines:

Common Port Settings

Generic Configuration Template

# Generic SMTP Configuration
SMTP_HOST="smtp.yourprovider.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="your-username"
SMTP_PASS="your-password"
SMTP_FROM="sender@yourdomain.com"
SMTP_FROM_NAME="Status Alerts"

Email Deliverability

To ensure your status notifications reach recipients and don't end up in spam, configure these DNS records for your sending domain.

SPF Record

SPF (Sender Policy Framework) tells email servers which servers are allowed to send email for your domain.

# Example SPF record (add as TXT record for your domain)
v=spf1 include:spf.protection.outlook.com include:_spf.google.com ~all

DKIM (DomainKeys Identified Mail)

DKIM adds a digital signature to your emails to verify they haven't been tampered with. This is usually configured in your email provider's admin panel.

• Microsoft 365: Enable DKIM in Microsoft 365 Defender → Email authentication
• Google Workspace: Enable in Admin Console → Apps → Gmail → Authenticate email
• cPanel/DirectAdmin: Usually auto-configured, check Email Deliverability in your control panel

DMARC Record

DMARC (Domain-based Message Authentication, Reporting & Conformance) tells email servers what to do with emails that fail SPF or DKIM checks.

# Example DMARC record (add as TXT record for _dmarc.yourdomain.com)
v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourdomain.com

Testing Your Configuration

After configuring SMTP, test it from the ATStatus admin panel:

1. Log in to the admin panel at /admin
2. Go to Settings → Notifications
3. Look for the Test Email option
4. Enter a test recipient email address
5. Click Send Test Email
6. Check the recipient's inbox (and spam folder)

Common Issues & Solutions

Connection Timeouts

• Cause: Firewall blocking outbound SMTP ports
• Solution: Ensure ports 587 and/or 465 are open on your server. Contact your hosting provider if needed.

Authentication Failures

• Cause: Wrong credentials, using account password instead of app password
• Solution: Generate a new app password and ensure you're using the full email address as the username.

Certificate Errors

• Cause: SSL certificate doesn't match the hostname
• Solution: Use the server's actual hostname instead of your domain (e.g., server123.host.com instead of mail.yourdomain.com)

Emails Going to Spam

• Cause: Missing or incorrect SPF/DKIM/DMARC records
• Solution: Configure proper DNS records as described in the Email Deliverability section.

Rate Limiting / Sending Limits

• Cause: Most email providers limit the number of emails you can send per day
• Solution: For high-volume notifications, consider a dedicated email service like SendGrid, Mailgun, or Amazon SES.

Security Best Practices

• Use App Passwords: Always use app-specific passwords instead of your main account password
• Use TLS/SSL: Always use encrypted connections (port 587 with STARTTLS or port 465 with SSL)
• Dedicated Account: Create a dedicated email account for sending notifications rather than using a personal account
• Monitor Usage: Regularly check your email account for unusual activity
• Rotate Credentials: Periodically regenerate app passwords, especially if you suspect they may have been compromised

Next Steps

Once SMTP is configured, you can:

• Configure notification templates in the admin panel
• Set up subscriber lists for incident notifications
• Enable automated incident notifications
• Test notifications by creating a test incident