Email / SMTP Configuration

RAMP uses email for:

• Password reset links (RAMP native users)
• User invitation emails
• MFA setup notifications
• System notifications (future)

Email configuration is optional but highly recommended for production deployments.

Prerequisites

• SMTP server access (Gmail, Office 365, SendGrid, custom SMTP)
• SMTP credentials (username and password)
• Network access from RAMP server to SMTP server

---

Quick Start

Edit appsettings.json

{
  "Smtp": {
    "Host": "smtp.gmail.com",
    "Port": 587,
    "EnableSsl": true,
    "Username": "noreply@yourcompany.com",
    "Password": "your-smtp-password",
    "FromAddress": "noreply@yourcompany.com",
    "FromName": "RAMP System"
  }
}

Configuration Reference

Setting	Required	Description	Example
Host	Yes	SMTP server hostname	smtp.gmail.com
Port	Yes	SMTP server port	587 (STARTTLS) or 465 (SSL)
EnableSsl	Yes	Use SSL/TLS encryption	true (recommended)
Username	Yes	SMTP authentication username	noreply@yourcompany.com
Password	Yes	SMTP authentication password	(app password or account password)
FromAddress	Yes	Email address in “From” field	noreply@yourcompany.com
FromName	No	Display name in “From” field	RAMP System

---

Provider-Specific Configuration

Gmail

1. Enable 2-Step Verification

   Go to https://myaccount.google.com/security and enable 2-Step Verification.

2. Create App Password

   1. Go to https://myaccount.google.com/apppasswords
   2. Select “Mail” and “Other (custom name)”
   3. Enter “RAMP” as the name
   4. Click “Generate”
   5. Copy the 16-character password

3. Configure RAMP

   {
     "Smtp": {
       "Host": "smtp.gmail.com",
       "Port": 587,
       "EnableSsl": true,
       "Username": "your-email@gmail.com",
       "Password": "app-password-from-google",
       "FromAddress": "your-email@gmail.com",
       "FromName": "RAMP System"
     }
   }

Gmail Limits:

• 500 emails per day (free accounts)
• 2,000 emails per day (Google Workspace)

Microsoft 365

Get SMTP Credentials:

• Use your Microsoft 365 email and password
• Or create an app password (if 2FA enabled)

Configure RAMP:

{
  "Smtp": {
    "Host": "smtp-mail.outlook.com",
    "Port": 587,
    "EnableSsl": true,
    "Username": "your-email@outlook.com",
    "Password": "your-password",
    "FromAddress": "your-email@outlook.com",
    "FromName": "RAMP System"
  }
}

Microsoft 365 Limits:

• 10,000 recipients per day (Microsoft 365)
• 300 emails per day (Outlook.com free accounts)

SendGrid

1. Create SendGrid Account

   Sign up at https://sendgrid.com and verify your sender identity (domain or single sender).

2. Create API Key

   1. Navigate to Settings -> API Keys
   2. Click “Create API Key”
   3. Name: RAMP
   4. Permissions: “Mail Send” (Full Access)
   5. Copy the API key

3. Configure RAMP

   {
     "Smtp": {
       "Host": "smtp.sendgrid.net",
       "Port": 587,
       "EnableSsl": true,
       "Username": "apikey",
       "Password": "SG.your-api-key-here",
       "FromAddress": "noreply@yourdomain.com",
       "FromName": "RAMP System"
     }
   }

SendGrid Limits:

• 100 emails/day (free tier)
• 40,000-100,000/day (paid plans)

Amazon SES

1. Verify Email/Domain

   Go to AWS SES Console and verify sender email or domain.

2. Create SMTP Credentials

   Navigate to “SMTP Settings” and click “Create SMTP Credentials”. Copy username and password.

3. Configure RAMP

   {
     "Smtp": {
       "Host": "email-smtp.us-east-1.amazonaws.com",
       "Port": 587,
       "EnableSsl": true,
       "Username": "AKIAIOSFODNN7EXAMPLE",
       "Password": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
       "FromAddress": "noreply@yourdomain.com",
       "FromName": "RAMP System"
     }
   }

SES Limits:

• 200 emails/day (sandbox mode)
• 50,000 emails/day (production, adjustable)

Custom SMTP

For corporate SMTP servers:

{
  "Smtp": {
    "Host": "smtp.yourcompany.com",
    "Port": 587,
    "EnableSsl": true,
    "Username": "ramp-service@yourcompany.com",
    "Password": "service-account-password",
    "FromAddress": "noreply@yourcompany.com",
    "FromName": "RAMP System"
  }
}

Common Ports:

• 587: STARTTLS (recommended)
• 465: SSL/TLS
• 25: Unencrypted (not recommended)

---

Secure Password Storage

Danger

Never store SMTP passwords in appsettings.json in production!

User Secrets (Dev)

cd src/RAMP.API
dotnet user-secrets set "Smtp:Password" "your-smtp-password"

Azure Key Vault (Prod)

{
  "AzureKeyVault": {
    "Enabled": true,
    "VaultUri": "https://your-ramp-vault.vault.azure.net/"
  }
}

Store secret as: Smtp--Password

Environment Variables

# Linux
export Smtp__Password="your-smtp-password"

# Windows
set Smtp__Password=your-smtp-password

# Docker
docker run -e Smtp__Password="your-smtp-password" ramp-api

---

Testing Email Configuration

Method 1: Password Reset Test

1. Create a test user with RAMP native authentication
2. Navigate to Admin -> Users
3. Find the test user
4. Click Reset Password
5. Check the user’s email inbox for reset email

Method 2: Backend Logs

Start RAMP and check logs for:

[INFO] SMTP configured: smtp.gmail.com:587
[INFO] Email sent to: testuser@example.com

Method 3: Manual Test (PowerShell)

$smtp = New-Object Net.Mail.SmtpClient("smtp.gmail.com", 587)
$smtp.EnableSsl = $true
$smtp.Credentials = New-Object System.Net.NetworkCredential("your-email@gmail.com", "app-password")
$smtp.Send("your-email@gmail.com", "test@example.com", "Test", "Test email from RAMP")

---

Email Templates

RAMP includes built-in email templates for:

Password Reset Email

• Subject: “Password Reset Request - RAMP”
• Content: Reset link with 24-hour expiration

MFA Setup Email

• Subject: “Multi-Factor Authentication Enabled - RAMP”
• Content: Confirmation and backup code reminder

Welcome Email

• Subject: “Welcome to RAMP”
• Content: Account created, next steps

Note

Template customization is a planned feature for future release.

---

Troubleshooting

Email not sending

Check 1: Verify SMTP configuration

# Test SMTP connection
telnet smtp.gmail.com 587

Check 2: Check application logs for email errors

Check 3: Verify credentials

• Ensure username and password are correct
• For Gmail, use App Password (not account password)
• Check if 2FA is enabled on email account

”Authentication failed” error

Check 1: Verify username format

• Gmail: your-email@gmail.com
• Office 365: your-email@yourdomain.com
• SendGrid: Always apikey (literal string)

Check 2: Check password

• Gmail: Use 16-character app password (no spaces)
• SendGrid: Use full API key starting with SG.
• Office 365: Use account password or app password

”Connection refused” or “Timeout” error

Check 1: Verify port and SSL settings

• Port 587: Use EnableSsl = true
• Port 465: Use EnableSsl = true
• Port 25: Use EnableSsl = false (not recommended)

Check 2: Check firewall

# Test outbound SMTP connection
nc -zv smtp.gmail.com 587

Check 3: Verify network access

• Ensure RAMP server can reach SMTP server
• Check both host firewall and network firewalls

Email goes to spam

Fix 1: Verify sender address

• Use a real, verified email address
• Avoid generic addresses like noreply@gmail.com

Fix 2: Set up SPF and DKIM records

• Configure DNS records for your domain
• See SendGrid/SES documentation

Fix 3: Use professional email provider

• SendGrid, Amazon SES provide better deliverability
• Include proper email headers

---

Security Best Practices

1. Use SSL/TLS — Always set EnableSsl = true and use port 587 or 465
2. Dedicated Email Account — Create a dedicated email account for RAMP, separate from personal/admin accounts
3. Strong Authentication — Enable 2FA on email account, use app passwords instead of account passwords, rotate credentials regularly
4. Secure Credential Storage — Never commit SMTP passwords to source control
5. Monitor Email Activity — Review sent email logs, set up alerts for unusual activity, check for failed delivery attempts
6. Rate Limiting — Be aware of provider limits (Gmail: 500/day, Office 365: 10,000/day, SendGrid: varies by plan)

---

Frequently Asked Questions

Do I need email for RAMP to work?

No. Email is optional, but password reset functionality requires it.

Can I change the “From” address?

Yes. Set Smtp:FromAddress to any address you control and have verified with your SMTP provider.

Can I use multiple SMTP providers?

Not currently. RAMP uses one SMTP configuration. This may be added in a future release.

How do I test without sending real emails?

Use a service like MailHog or Papercut SMTP for local development.

---

Next Steps

• MFA Setup Guide — Configure multi-factor authentication
• Bootstrap Administrators — Set up initial admin accounts
• Application Settings — Full configuration reference

---

Related topics

Application Settings Reference Complete reference for RAMP's appsettings.json configuration

RAMP Native Authentication Configure username/password login with MFA, password reset, and lockout protection