Complete guide to configure email delivery with SMTP, SendGrid, Gmail, Amazon SES, and Mailgun

Email Configuration

Configure email delivery for your Vyral platform to send transactional emails like verification codes, notifications, password resets, and monetization alerts. This guide covers complete setup for all supported email providers.

Supported Email Providers

Vyral supports multiple email delivery methods:

Gmail/Google Workspace - Easy setup with App Passwords
SendGrid - Reliable transactional email API service
Mailgun - Developer-friendly email API with analytics
Amazon SES - Cost-effective AWS email service
Custom SMTP - Any SMTP-compatible provider (Office 365, Yahoo, custom servers)

Quick Start

Choose your preferred email provider and follow the setup guide:

Gmail / Google Workspace Setup

Gmail is recommended for small to medium-scale applications. For high-volume sending, consider SendGrid or Amazon SES.

Prerequisites

A Gmail or Google Workspace account
2-Factor Authentication enabled on your account
An App Password generated for mail access

Step 1: Enable 2-Factor Authentication

Go to Google Account Security

Click on "2-Step Verification" under "How you sign in to Google"

Follow the setup wizard to enable 2FA using your phone

Step 2: Generate App Password

Visit Google App Passwords

Select "Mail" from the dropdown menu

Select "Other (Custom name)" and enter "Vyral Platform"

Click "Generate" and copy the 16-character password

Important: Save the app password immediately. Google will not show it again.

Step 3: Configure in Admin Dashboard

Go to your Admin Dashboard → Email Settings
Select "Gmail" as the provider
Enter your configuration:

Test

Sending Limits

Account Type	Daily Limit	Per Minute
Free Gmail	500 emails	20 emails
Google Workspace	2,000 emails	60 emails

Troubleshooting Gmail

Authentication Failed

Error: "535-5.7.8 Username and Password not accepted"

Solutions:

Ensure you're using the App Password, not your regular password
Remove spaces from the app password
Verify 2FA is enabled on your account
Check if the app password hasn't been revoked

Account Locked

Error: "Please log in via your web browser"

Solutions:

Visit accounts.google.com/DisplayUnlockCaptcha
Click "Continue" to allow access
Try sending again within 10 minutes

SendGrid Setup

SendGrid is recommended for production applications with high email volume and delivery requirements.

Prerequisites

A SendGrid account (free tier available)
Domain verification for better deliverability
API key with Mail Send permissions

Step 1: Create SendGrid Account

Complete account verification (may take 24-48 hours)

Choose your pricing plan (free tier includes 100 emails/day)

Step 2: Verify Your Sender Domain

Go to Settings → Sender Authentication

Click "Authenticate Your Domain"

Follow the DNS setup instructions for your domain provider

Verify DNS records are properly configured

Step 3: Create API Key

Navigate to Settings → API Keys

Click "Create API Key"

Name it "Vyral Platform"

Select "Restricted Access"

Enable only "Mail Send" permission

Save the API key securely

Step 4: Configure in Admin Dashboard

Test

Using SMTP Instead of API

If you prefer SMTP over the API:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=SG.xxxxxxxxxxxxxxxxxxxxxx
SMTP_USE_TLS=true

Pricing Tiers

Plan	Monthly Price	Emails/Month	Features
Free	$0	100/day	Basic features
Essentials	$19.95	50,000	Email validation, analytics
Pro	$89.95	100,000	Advanced analytics, dedicated IP

Advanced Features

Email Templates: Use SendGrid's dynamic templates
Webhooks: Track opens, clicks, bounces
IP Warmup: Gradually increase sending volume
Suppressions: Manage unsubscribes and bounces

Mailgun Setup

Mailgun offers powerful email APIs with excellent deliverability and detailed analytics.

Prerequisites

A Mailgun account
Verified domain (required for production)
API key from Mailgun dashboard

Step 1: Create Mailgun Account

Verify your email address

Add payment method (required even for free tier)

Step 2: Add and Verify Domain

Go to Sending → Domains

Click "Add New Domain"

Enter your domain (e.g., mg.yourdomain.com)

Select your region (US or EU)

Add the provided DNS records to your domain:

SPF record for authentication
DKIM records for signing
MX records for receiving (optional)
CNAME for tracking (optional)

Click "Verify DNS Settings" once propagated

Step 3: Get API Credentials

Navigate to Settings → API Keys

Copy your Private API Key

Note your domain name from the Domains page

Step 4: Configure in Admin Dashboard

Test

Using SMTP Instead of API

SMTP_HOST=smtp.mailgun.org  # or smtp.eu.mailgun.org for EU
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SMTP_USE_TLS=true

Regional Configuration

Region	API Base URL	SMTP Server
US	api.mailgun.net	smtp.mailgun.org
EU	api.eu.mailgun.net	smtp.eu.mailgun.org

Pricing

Plan	Monthly Price	Emails/Month	Features
Trial	Free (3 months)	5,000	Full features
Foundation	$35	50,000	Email validation
Growth	$80	100,000	Advanced analytics

Advanced Features

Email Validation: Verify addresses before sending
Inbound Routing: Receive and parse emails
Logs Retention: 3-day retention (upgradeable)
Webhooks: Real-time event notifications

Amazon SES Setup

Amazon SES offers the most cost-effective solution for high-volume email sending with AWS integration.

Prerequisites

An AWS account
Verified sender email or domain
IAM user with SES permissions

Step 1: Enable Amazon SES

Navigate to Amazon SES service

Select your preferred region (e.g., us-east-1, eu-west-1)

Request production access (sandbox limits: 200 emails/day)

Step 2: Verify Domain or Email

Option A: Verify Domain (Recommended)

Go to Configuration → Verified identities

Click "Create identity"

Select "Domain" and enter your domain

Add the provided DNS records:

DKIM CNAME records (3 records)
Optional: Custom MAIL FROM domain

Wait for verification (usually within 72 hours)

Option B: Verify Email Address

Go to Configuration → Verified identities

Click "Create identity"

Select "Email address" and enter your email

Check inbox and click verification link

Step 3: Create IAM User and Credentials

Go to IAM → Users → Add User

Name: "vyral-ses-user"

Select "Programmatic access"

Attach policy: "AmazonSESFullAccess" or create custom:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ses:SendEmail",
      "ses:SendRawEmail"
    ],
    "Resource": "*"
  }]
}

Save Access Key ID and Secret Access Key

Step 4: Generate SMTP Credentials (Optional)

In SES Console, go to SMTP Settings

Click "Create SMTP Credentials"

Name: "vyral-smtp-user"

Download credentials CSV file

Step 5: Configure in Admin Dashboard

Using API (Recommended)

{
  "provider": "amazonses",
  "fromEmail": "[email protected]",
  "fromName": "Your Platform Name",
  "amazonSESConfig": {
    "region": "us-east-1",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "...",
    "sessionToken": ""  // Optional, for temporary credentials
  }
}

Using SMTP

# Regional SMTP endpoints
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIA...  # SMTP username from Step 4
SMTP_PASSWORD=...       # SMTP password from Step 4
SMTP_USE_TLS=true

Regional Endpoints

Region	SMTP Endpoint	API Endpoint
US East (N. Virginia)	email-smtp.us-east-1.amazonaws.com	email.us-east-1.amazonaws.com
US West (Oregon)	email-smtp.us-west-2.amazonaws.com	email.us-west-2.amazonaws.com
EU (Ireland)	email-smtp.eu-west-1.amazonaws.com	email.eu-west-1.amazonaws.com
Asia Pacific (Mumbai)	email-smtp.ap-south-1.amazonaws.com	email.ap-south-1.amazonaws.com

Sandbox vs Production

Feature	Sandbox	Production
Daily limit	200 emails	50,000+
Recipients	Verified only	Any
Sending rate	1 email/sec	14+ emails/sec

Pricing

Email sending: $0.10 per 1,000 emails
Incoming email: $0.10 per 1,000 emails
Data transfer: $0.12 per GB (attachments)

Moving to Production

Go to Account dashboard → Request production access

Fill out the request form:

Use case description
Expected volume
How you handle bounces/complaints
Your opt-in process

Wait for approval (24-48 hours)

SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Name"

Office 365 requires authentication with the same email used as the sender address.

Yahoo Mail

SMTP_HOST=smtp.mail.yahoo.com
SMTP_PORT=587  # or 465 for SSL
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Name"

Yahoo requires an App Password. Enable 2FA and generate one from Account Security settings.

Zoho Mail

SMTP_HOST=smtp.zoho.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Name"

ProtonMail Bridge

SMTP_HOST=127.0.0.1
SMTP_PORT=1025
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=bridge-password
SMTP_USE_TLS=false
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Name"

Self-Hosted Mail Servers

Postfix

SMTP_HOST=mail.yourdomain.com
SMTP_PORT=587
SMTP_USERNAME=smtp-user
SMTP_PASSWORD=smtp-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Platform"

Mail-in-a-Box

SMTP_HOST=box.yourdomain.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=admin-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME="Your Platform"

Configure in Admin Dashboard

Test

Port Configuration Guide

Port	Protocol	Use Case
25	SMTP	Unencrypted (not recommended)
465	SMTPS	SSL/TLS encryption
587	SMTP	STARTTLS encryption (recommended)
2525	SMTP	Alternative for ISP blocking

Testing Your Email Configuration

Method 1: Admin Dashboard Test

Navigate to Admin Dashboard → Email Settings

Click "Test Email Configuration"

Enter a test email address

Check your inbox (and spam folder) for the test email

Method 2: API Test

# Test email configuration via API
curl -X POST https://api.yourdomain.com/api/admin/email/test \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "testEmail": "[email protected]",
    "config": {
      "fromEmail": "[email protected]",
      "fromName": "Test Platform"
    }
  }'

Method 3: Command Line Test

# For Gmail
swaks --to [email protected] \
      --from [email protected] \
      --server smtp.gmail.com:587 \
      --auth LOGIN \
      --auth-user [email protected] \
      --auth-password "app-password" \
      --tls

# For SendGrid
swaks --to [email protected] \
      --from [email protected] \
      --server smtp.sendgrid.net:587 \
      --auth LOGIN \
      --auth-user apikey \
      --auth-password "SG.xxxx" \
      --tls

v=spf1 include:_spf.google.com include:sendgrid.net include:mailgun.org include:amazonses.com ~all

Adjust based on your email providers. Common includes:

Gmail: include:_spf.google.com
SendGrid: include:sendgrid.net
Mailgun: include:mailgun.org
Amazon SES: include:amazonses.com

DKIM (DomainKeys Identified Mail)

Each provider will give you DKIM records to add:

# Example SendGrid DKIM
s1._domainkey.yourdomain.com CNAME s1.domainkey.u123456.wl.sendgrid.net
s2._domainkey.yourdomain.com CNAME s2.domainkey.u123456.wl.sendgrid.net

DMARC (Domain-based Message Authentication)

Add DMARC policy after SPF and DKIM are working:

_dmarc.yourdomain.com TXT "v=DMARC1; p=quarantine; rua=mailto:[email protected]"

Policy options:

p=none - Monitor only
p=quarantine - Send suspicious emails to spam
p=reject - Block suspicious emails

2. Sender Reputation Management

Warm-Up Schedule for New Domains

Day	Volume	Recipients
1-3	50/day	Engaged users only
4-7	100/day	Active users
8-14	250/day	Recent users
15-21	500/day	All segments
22-30	1000/day	Full list
30+	Gradual increase	Monitor metrics

Monitor Key Metrics

Bounce Rate: Keep below 2%
Complaint Rate: Keep below 0.1%
Unsubscribe Rate: Keep below 0.5%
Open Rate: Target above 20%
Click Rate: Target above 2.5%

3. Content Best Practices

Subject Lines

✅ Do:

Keep under 50 characters
Be clear and honest
Personalize when possible
A/B test variations

❌ Don't:

Use ALL CAPS
Excessive punctuation!!!
Spam trigger words (FREE, URGENT, ACT NOW)
Misleading content

Email Body

✅ Do:

Include text and HTML versions
Optimize for mobile (600px width)
Use alt text for images
Include clear unsubscribe link
Balance text-to-image ratio (60:40)

❌ Don't:

Use only images
Hide unsubscribe links
Use tiny fonts (< 14px)
Include too many links
Use URL shorteners

4. List Hygiene

Regular Maintenance

Remove hard bounces immediately
Suppress complainers permanently
Re-engage inactive users (30-60-90 day campaigns)
Remove unengaged users after 6 months
Validate new emails before adding

Email Validation Services

Consider using validation services for better deliverability:

SendGrid Email Validation
Mailgun Email Validation
ZeroBounce
NeverBounce

Email Templates

Vyral includes pre-built email templates for common scenarios:

Available Templates

Template	Purpose	Variables
`email_verification`	Verify new user accounts	`{{.Username}}`, `{{.VerificationCode}}`, `{{.VerificationLink}}`
`password_reset`	Reset forgotten passwords	`{{.Username}}`, `{{.ResetLink}}`, `{{.ExpiryTime}}`
`welcome`	Welcome new users	`{{.Username}}`, `{{.PlatformName}}`
`gift_received`	Notify about received gifts	`{{.Username}}`, `{{.SenderName}}`, `{{.GiftName}}`, `{{.GiftValue}}`
`subscription_new`	New subscription notification	`{{.Username}}`, `{{.SubscriberName}}`, `{{.TierName}}`
`subscription_cancelled`	Subscription cancellation	`{{.Username}}`, `{{.SubscriberName}}`, `{{.TierName}}`
`tip_received`	Direct tip notification	`{{.Username}}`, `{{.SenderName}}`, `{{.Amount}}`
`security_alert`	Account security notices	`{{.Username}}`, `{{.Device}}`, `{{.Location}}`, `{{.Time}}`
`stream_started`	Live stream notification	`{{.Username}}`, `{{.StreamerName}}`, `{{.StreamTitle}}`
`payment_success`	Payment confirmation	`{{.Username}}`, `{{.Amount}}`, `{{.Description}}`
`payment_failed`	Payment failure notice	`{{.Username}}`, `{{.Amount}}`, `{{.Reason}}`

Customizing Templates

Templates are stored in MongoDB and can be customized via the Admin Dashboard:

Go to Admin Dashboard → Email Templates
Select the template to edit
Modify subject and body (HTML)
Use variables with {{.VariableName}} syntax
Preview and test before saving

Creating Custom Templates

// Example: Creating a custom template via API
POST /api/admin/email/templates
{
  "name": "custom_notification",
  "subject": "{{.Title}} - {{.PlatformName}}",
  "body": "<html>...</html>",
  "variables": ["Title", "Content", "Username", "PlatformName"],
  "isActive": true
}

Using regular password instead of App Password
App Password revoked or expired
2FA not enabled

Solutions:

Enable 2FA on your Google account
Generate new App Password
Remove spaces from the password
Use full email as username

Daily Limit Exceeded

Error: "User has exceeded daily sending quota"

Solutions:

Wait 24 hours for quota reset
Upgrade to Google Workspace
Use multiple Gmail accounts with rotation
Switch to dedicated email service

Account Temporarily Locked

Error: "Please log in via your web browser"

Solutions:

Visit Unlock Captcha
Sign in to Gmail web interface
Complete any security challenges
Try again within 10 minutes

SendGrid Troubleshooting

401 Unauthorized

Causes:

Invalid API key
API key lacks permissions
Account suspended

Solutions:

Verify API key is correct
Check API key has "Mail Send" permission
Ensure account is verified and active
Generate new API key if needed

Domain Not Authenticated

Warning: Emails sent without authentication

Solutions:

Complete domain authentication in SendGrid
Add all required DNS records
Wait for DNS propagation (up to 48 hours)
Verify in SendGrid dashboard

Rate Limit Exceeded

Error: "429 Too Many Requests"

Solutions:

Implement exponential backoff
Batch emails efficiently
Upgrade SendGrid plan for higher limits
Use SendGrid's batch send API

Mailgun Troubleshooting

Domain Not Verified

Error: "Domain is not allowed to send"

Solutions:

Add and verify domain in Mailgun
Complete DNS verification
Ensure using correct domain in API calls
Check domain is active (not disabled)

Invalid API Key

Error: "Forbidden - Invalid API key"

Solutions:

Use Private API key (not public)
Check key matches region (US/EU)
Ensure key hasn't been revoked
Verify account has valid payment method

EU Region Issues

Error: Connection to api.mailgun.net fails

Solutions:

Use api.eu.mailgun.net for EU domains
Update SMTP to smtp.eu.mailgun.org
Ensure region setting matches domain location

Amazon SES Troubleshooting

Still in Sandbox

Limitations: Can only send to verified emails

Solutions:

Request production access
Provide detailed use case
Explain bounce/complaint handling
Wait for approval (24-48 hours)

Invalid Credentials

Error: "The security token included in the request is invalid"

Solutions:

Verify Access Key ID and Secret
Check IAM user has SES permissions
Ensure using correct region
For SMTP: Use SMTP credentials, not IAM credentials

Sending Rate Exceeded

Error: "Maximum sending rate exceeded"

Solutions:

Implement rate limiting in your code
Request sending rate increase
Use SES configuration sets for better control
Distribute sending over time

General Troubleshooting

Emails Not Being Received

Diagnostic Steps:

Check Email Logs
- Admin Dashboard → Email Logs
- Look for error messages
- Verify email addresses are correct
Test Different Providers
- Try sending to Gmail, Outlook, Yahoo
- Check if issue is provider-specific

Verify DNS Records

# Check SPF
dig TXT yourdomain.com | grep spf

# Check DKIM
dig TXT selector._domainkey.yourdomain.com

# Check DMARC
dig TXT _dmarc.yourdomain.com

Use Email Testing Tools

High Bounce Rate

Common Causes and Solutions:

Invalid Email Addresses
- Implement email validation before sending
- Clean your email list regularly
- Use double opt-in for new subscribers
DNS Issues
- Verify SPF, DKIM, DMARC records
- Ensure reverse DNS is configured
- Check domain isn't blacklisted
Content Issues
- Avoid spam trigger words
- Balance text and images
- Include unsubscribe link
- Test with spam checkers

Monitoring and Analytics

Email Metrics Dashboard

Monitor these key metrics in your Admin Dashboard:

Metric	Good	Warning	Critical
Delivery Rate	> 98%	95-98%	< 95%
Open Rate	> 20%	15-20%	< 15%
Click Rate	> 2.5%	1-2.5%	< 1%
Bounce Rate	< 2%	2-5%	> 5%
Complaint Rate	< 0.1%	0.1-0.5%	> 0.5%
Unsubscribe Rate	< 0.5%	0.5-2%	> 2%

Setting Up Webhooks

Configure webhooks to track email events in real-time:

SendGrid Webhooks

{
  "url": "https://api.yourdomain.com/webhooks/sendgrid",
  "events": ["delivered", "opened", "clicked", "bounced", "complained", "unsubscribed"]
}

Mailgun Webhooks

{
  "url": "https://api.yourdomain.com/webhooks/mailgun",
  "events": ["delivered", "opened", "clicked", "bounced", "complained", "unsubscribed"]
}

Email Logs Retention

Configure log retention in your database:

// Recommended retention periods
{
  "delivered": "30 days",
  "opened": "90 days",
  "clicked": "90 days",
  "bounced": "180 days",
  "complained": "permanent",
  "unsubscribed": "permanent"
}

Security Considerations

Protecting API Keys

Never commit API keys or passwords to version control!

Use Environment Variables

# .env file (add to .gitignore)
SENDGRID_API_KEY=SG.xxxxx
MAILGUN_API_KEY=key-xxxxx

Rotate Keys Regularly
- Set up key rotation schedule (every 90 days)
- Monitor for unauthorized usage
- Revoke compromised keys immediately
Restrict Key Permissions
- SendGrid: Only "Mail Send" permission
- Mailgun: Create sending-only keys
- Amazon SES: Use IAM with minimal permissions

Rate Limiting

Implement rate limiting to prevent abuse:

// Example rate limits
{
  "perUser": {
    "hourly": 10,
    "daily": 50
  },
  "perIP": {
    "hourly": 20,
    "daily": 100
  },
  "global": {
    "hourly": 1000,
    "daily": 10000
  }
}

Email Validation

Always validate email addresses before sending:

// Basic validation regex
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

// Advanced validation
- Check MX records
- Verify domain exists
- Detect disposable emails
- Check against bounce list

Migration Guide

Switching Email Providers

Prepare New Provider

Set up account and verify domain
Configure DNS records
Generate API keys
Test with small batch

Parallel Running

Route 10% traffic to new provider
Monitor metrics for both providers
Gradually increase percentage
Compare deliverability rates

Full Migration

Switch 100% traffic to new provider
Keep old provider active for 30 days
Update documentation
Archive old credentials securely

Backup Email Provider

Configure automatic failover:

// Failover configuration
{
  "primary": {
    "provider": "sendgrid",
    "weight": 90
  },
  "secondary": {
    "provider": "mailgun",
    "weight": 10
  },
  "failoverTriggers": {
    "errorRate": 5,
    "responseTime": 5000
  }
}

Next Steps

Email Configuration Complete!

Your email system is now fully configured. Here's what to do next:

Test Your Configuration

Send test emails to multiple providers
Verify templates are working
Check spam scores

Set Up Monitoring

Configure webhooks for events
Set up alerts for failures
Monitor delivery rates

Configure Other Services

Storage Settings - File uploads and media
Branding - Customize appearance
Localization - Multi-language support
CoTURN Server - Video calling

Email Configuration

On this page