Skip to content

Latest commit

 

History

History
223 lines (179 loc) · 6.27 KB

SMTP_SETUP.md

File metadata and controls

223 lines (179 loc) · 6.27 KB

SMTP Setup Guide for Malify

This guide will help you configure SMTP to send real emails from your Malify email client.

🚀 SMTP Features Added

Your Malify email client now includes:

  • ✅ Real Email Sending: Send emails to any email address
  • ✅ Multiple SMTP Providers: Support for Gmail, Outlook, Yahoo, and custom SMTP
  • ✅ SMTP Testing: Built-in connection and email testing
  • ✅ Error Handling: Graceful fallback to drafts if SMTP fails
  • ✅ Message Tracking: Track sent emails with message IDs

📧 Quick Setup with Gmail (Recommended)

Step 1: Enable 2-Factor Authentication

  1. Go to Google Account Settings
  2. Enable 2-Factor Authentication if not already enabled

Step 2: Generate App Password

  1. Go to Security → App passwords
  2. Select Mail as the app
  3. Copy the generated 16-character password

Step 3: Update Environment Variables

Add these to your .env.local file:

# SMTP Configuration
SMTP_PROVIDER=gmail
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_16_character_app_password
SMTP_FROM_EMAIL=your_email@gmail.com

Step 4: Restart Your Server

npm run dev

🔧 SMTP Configuration Options

Gmail

SMTP_PROVIDER=gmail
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM_EMAIL=your_email@gmail.com

Outlook/Hotmail

SMTP_PROVIDER=outlook
SMTP_USER=your_email@outlook.com
SMTP_PASS=your_password
SMTP_FROM_EMAIL=your_email@outlook.com

Yahoo Mail

SMTP_PROVIDER=yahoo
SMTP_USER=your_email@yahoo.com
SMTP_PASS=your_app_password
SMTP_FROM_EMAIL=your_email@yahoo.com

Custom SMTP

SMTP_PROVIDER=custom
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@yourdomain.com
SMTP_PASS=your_password
SMTP_FROM_EMAIL=your_email@yourdomain.com

🧪 Testing SMTP

In-App Testing

  1. Open Malify at http://localhost:3000
  2. Click the Mail icon (📧) in the header
  3. Click Test Connection to verify SMTP settings
  4. Enter a test email address and click Send to send a test email

Manual Testing

You can also test SMTP via API:

# Test connection
curl -X GET http://localhost:3000/api/smtp/test

# Send test email
curl -X POST http://localhost:3000/api/smtp/test \
  -H "Content-Type: application/json" \
  -d '{"testEmail": "test@example.com"}'

📨 How It Works

Email Sending Flow

  1. Compose Email: User writes email in the compose modal
  2. SMTP Attempt: System tries to send via configured SMTP
  3. Success: Email is sent and marked as "Sent" in database
  4. Failure: Email is saved as "Draft" with error message
  5. Database Record: All emails are stored regardless of SMTP status

Error Handling

  • If SMTP fails, the email is automatically saved as a draft
  • Users receive clear error messages about SMTP issues
  • Failed emails can be resent after fixing SMTP configuration

🔒 Security Best Practices

App Passwords

  • ✅ Use App Passwords for Gmail, Yahoo (not your regular password)
  • ✅ Enable 2FA before generating app passwords
  • ✅ Rotate passwords regularly

Environment Variables

  • ✅ Never commit .env.local to version control
  • ✅ Use strong passwords for SMTP authentication
  • ✅ Restrict SMTP access to your application only

🛠️ Troubleshooting

Common Issues

"SMTP connection failed"

  • ✅ Check your internet connection
  • ✅ Verify SMTP credentials are correct
  • ✅ Ensure 2FA and app passwords are set up (Gmail/Yahoo)
  • ✅ Check if your email provider requires app passwords

"Authentication failed"

  • ✅ Use app password instead of regular password
  • ✅ Verify username/email is correct
  • ✅ Check if account has SMTP access enabled

"Connection timeout"

  • ✅ Check SMTP host and port settings
  • ✅ Verify firewall isn't blocking SMTP ports
  • ✅ Try different SMTP ports (587, 465, 25)

"Email sent but not received"

  • ✅ Check recipient's spam/junk folder
  • ✅ Verify sender reputation (new domains may be flagged)
  • ✅ Check if recipient's server accepts your domain

Debug Steps

  1. Test Connection: Use the built-in SMTP test feature
  2. Check Logs: Look at server console for detailed error messages
  3. Verify Settings: Double-check all environment variables
  4. Test with Different Provider: Try Gmail if using custom SMTP

📊 SMTP Providers Comparison

Provider Ease of Setup Daily Limit Notes
Gmail ⭐⭐⭐⭐⭐ 500 emails Recommended for development
Outlook ⭐⭐⭐⭐ 300 emails Good alternative to Gmail
Yahoo ⭐⭐⭐ 500 emails Requires app password
Custom ⭐⭐ Varies Best for production

🚀 Production Considerations

For Production Deployment

  1. Use Professional SMTP: Consider services like SendGrid, Mailgun, or AWS SES
  2. Domain Authentication: Set up SPF, DKIM, and DMARC records
  3. Rate Limiting: Implement sending limits to avoid being flagged
  4. Monitoring: Track delivery rates and bounce rates
  5. Compliance: Ensure GDPR/CAN-SPAM compliance

Environment Variables for Production

SMTP_PROVIDER=custom
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASS=your_sendgrid_api_key
SMTP_FROM_EMAIL=noreply@yourdomain.com

📝 API Reference

Send Email

POST /api/emails
{
  "to": "recipient@example.com",
  "cc": "cc@example.com", // optional
  "bcc": "bcc@example.com", // optional
  "subject": "Hello World",
  "body": "This is a test email",
  "isDraft": false
}

Test SMTP Connection

GET /api/smtp/test
// Returns: { connection: { success: boolean, error?: string } }

Send Test Email

POST /api/smtp/test
{
  "testEmail": "test@example.com"
}
// Returns: { result: { success: boolean, messageId?: string, error?: string } }

🎉 You're All Set!

Your Gmail clone now has full SMTP capabilities! You can:

  • Send real emails to anyone
  • Test your SMTP configuration
  • Handle errors gracefully
  • Track sent emails

Need help? Check the troubleshooting section or open the SMTP settings panel in your app for guided setup.