CloudPOS Documentation

# Email Notifications

CloudPOS can send email notifications for various events. This guide covers SMTP configuration and email setup.

# Overview

Email notifications are sent for:

  • Email verification (when user registers)
  • Password reset requests
  • Subscription confirmations
  • Payment success/failure
  • Subscription expiry warnings

# Step 1: Choose Email Provider

  • Free: Yes (with limitations)
  • Setup: Easy
  • Limits: 500 emails/day (free account)

# Option 2: SendGrid

  • Free: 100 emails/day
  • Setup: Moderate
  • Reliability: High

# Option 3: Mailgun

  • Free: 5,000 emails/month
  • Setup: Moderate
  • Reliability: High

# Option 4: AWS SES

  • Free: 62,000 emails/month (within AWS)
  • Setup: Complex
  • Reliability: Very high

# Step 2: Configure SMTP Settings

  1. Login to Admin Panel: http://localhost:5173/admin/login

  2. Navigate to Settings → Email Configuration

  3. Fill in SMTP settings:

    SMTP Host: smtp.gmail.com (for Gmail)

    SMTP Port:

    • 587 for TLS
    • 465 for SSL

    SMTP User: Your email address

    SMTP Password: App password (not regular password)

    Encryption:

    • TLS for port 587
    • SSL for port 465

    From Email: noreply@yourdomain.com

    From Name: CloudPOS

  4. Toggle Is Active to enable

  5. Click Save

# Method 2: Via Environment Variables

Add to .env file:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@cloudpos.com
SMTP_FROM_NAME=CloudPOS

Note: Admin Panel method is recommended as it's easier to update.

# Step 3: Gmail Setup (Example)

# Enable 2-Factor Authentication

  1. Go to: https://myaccount.google.com/security
  2. Enable 2-Step Verification

# Generate App Password

  1. Go to: https://myaccount.google.com/apppasswords
  2. Select app: Mail
  3. Select device: Other (Custom name)
  4. Enter: CloudPOS
  5. Click Generate
  6. Copy the 16-character password (no spaces)
  7. Use this in SMTP_PASSWORD

# Configure in Admin Panel

  • SMTP Host: smtp.gmail.com
  • SMTP Port: 587
  • SMTP User: your-email@gmail.com
  • SMTP Password: xxxx xxxx xxxx xxxx (app password, 16 chars)
  • Encryption: TLS
  • From Email: your-email@gmail.com (or use alias)
  • From Name: CloudPOS

# Step 4: Test Email Sending

# Via Admin Panel

  1. Admin Panel → Settings → Email Configuration
  2. Click Send Test Email
  3. Enter test email address
  4. Click Send
  5. Check inbox (and spam folder)

# Via API (Optional)

curl -X POST http://localhost:3000/api/email/test \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{"to": "test@example.com"}'

# Step 5: Email Templates

CloudPOS includes default email templates for:

  • Email Verification: Sent when user registers
  • Password Reset: Sent when user requests password reset
  • Subscription Confirmation: Sent when subscription is activated
  • Payment Success: Sent when payment succeeds
  • Payment Failed: Sent when payment fails

# Customizing Templates

  1. Admin Panel → Settings → Email Templates
  2. Select template to edit
  3. Modify:
    • Subject: Email subject line
    • Body: HTML email body
    • Variables: Available template variables
  4. Click Save

# Available Variables

Common variables in templates:

  • : Application name
  • : Tenant/company name
  • : User's name
  • : Email verification link
  • : Password reset link
  • : Subscription plan name
  • : Payment amount

# Common SMTP Configurations

# Gmail

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# SendGrid

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASSWORD=your-sendgrid-api-key

# Mailgun

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=postmaster@yourdomain.mailgun.org
SMTP_PASSWORD=your-mailgun-password

# AWS SES

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-ses-smtp-username
SMTP_PASSWORD=your-ses-smtp-password

# Troubleshooting

# Emails Not Sending

Issue: No emails received

Solutions:

  1. Check SMTP settings:

    • Verify host, port, user, password
    • Test with "Send Test Email" in Admin Panel

  2. Check email logs:

    # PM2 logs
pm2 logs cloudpos | grep -i email

# Or check server logs
tail -f logs/pm2-error.log

  3. Check spam folder:

    • Emails might be in spam
    • Add sender to contacts

  4. Verify SMTP credentials:

    • Test with email client (Thunderbird, Outlook)
    • Use same credentials

# Authentication Failed

Error: Invalid login or Authentication failed

Solutions:

  1. Gmail: Use app password, not regular password
  2. Check username: Must be full email address
  3. Check password: No extra spaces
  4. Verify 2FA: Must be enabled for Gmail app passwords

# Connection Timeout

Error: Connection timeout or ECONNREFUSED

Solutions:

  1. Check firewall:

    • Allow outbound port 587 or 465
    • Check server firewall rules

  2. Verify SMTP host:

    • Test: telnet smtp.gmail.com 587
    • Should connect (if telnet installed)

  3. Check port:

    • Port 587 for TLS
    • Port 465 for SSL
    • Some providers use different ports

# Emails Going to Spam

Issue: Emails received but in spam folder

Solutions:

  1. Configure SPF record:

    • Add SPF record to DNS
    • Format: v=spf1 include:_spf.google.com ~all (for Gmail)

  2. Configure DKIM:

    • Set up DKIM signing
    • Add DKIM record to DNS

  3. Use custom domain:

    • Use noreply@yourdomain.com instead of Gmail
    • Requires domain email setup

  4. Warm up domain:

    • Start with low email volume
    • Gradually increase

# Rate Limiting

Issue: Emails stop sending after a few

Solutions:

  1. Check provider limits:

    • Gmail: 500/day (free)
    • SendGrid: 100/day (free)
    • Upgrade plan if needed

  2. Implement queuing:

    • Use email queue system
    • Send emails in batches

# Disabling Email (Optional)

If you don't want to use email:

  1. Admin Panel → Settings → Email Configuration
  2. Toggle Is Active to OFF
  3. Or leave SMTP settings empty

Note: Some features (email verification, password reset) require email. Consider using a service like Mailtrap for development.

# Production Recommendations

  1. ✅ Use dedicated email service (SendGrid, Mailgun, AWS SES)
  2. ✅ Use custom domain for "From" address
  3. ✅ Configure SPF/DKIM records
  4. ✅ Monitor email delivery rates
  5. ✅ Set up email queue for high volume
  6. ✅ Use separate SMTP for transactional vs marketing emails

Next: See Security & Demo Mode for security best practices.

← Security & Demo Mode →