brand-master/EMAIL_SETUP.md

Email Configuration Guide

Overview

The Brand Master application supports sending transactional emails for:

• Password reset PINs
• Welcome emails for new users
• Order confirmations (future)
• Contact form notifications (future)

Email Service Options

Option 1: Gmail SMTP (Recommended for Testing)

1. Create App Password (if using Gmail with 2FA):

   • Go to Google Account Settings → Security
   • Enable 2-Factor Authentication
   • Go to "App passwords"
   • Generate app password for "Mail"
   • Copy the 16-character password

2. Configure Environment Variables:

   SMTP_HOST=smtp.gmail.com
   SMTP_PORT=587
   SMTP_USERNAME=your-email@gmail.com
   SMTP_PASSWORD=your-app-password
   SMTP_FROM=noreply@brand-master.com
   

Option 2: SendGrid (Recommended for Production)

1. Create SendGrid Account:

   • Sign up at https://sendgrid.com
   • Verify your sender email
   • Create API key

2. Configure Environment Variables:

   SMTP_HOST=smtp.sendgrid.net
   SMTP_PORT=587
   SMTP_USERNAME=apikey
   SMTP_PASSWORD=your-sendgrid-api-key
   SMTP_FROM=noreply@brand-master.com
   

Option 3: Amazon SES (Production - Most Reliable)

1. Setup SES:

   • Sign up for AWS SES
   • Verify your domain or email
   • Get SMTP credentials

2. Configure Environment Variables:

   SMTP_HOST=email-smtp.us-east-1.amazonaws.com
   SMTP_PORT=587
   SMTP_USERNAME=your-ses-smtp-username
   SMTP_PASSWORD=your-ses-smtp-password
   SMTP_FROM=noreply@brand-master.com
   

Kubernetes Deployment Configuration

Method 1: Update values.yaml (Recommended)

Edit brand-master-chart/values.yaml:

backend:
  env:
    # Existing vars...
    - name: SMTP_HOST
      value: "smtp.gmail.com"
    - name: SMTP_PORT
      value: "587"
    - name: SMTP_USERNAME
      value: "your-email@gmail.com"
    - name: SMTP_PASSWORD
      value: "your-app-password"  # Use secrets in production!
    - name: SMTP_FROM
      value: "noreply@brand-master.com"

Method 2: Use Kubernetes Secret (Production)

1. Create Secret:

   kubectl create secret generic brand-master-email \
     --from-literal=smtp-username=your-email@gmail.com \
     --from-literal=smtp-password=your-app-password \
     -n my-apps
   

2. Update Deployment (brand-master-chart/templates/backend-deployment.yaml):

   env:
     # ... existing env vars ...
     - name: SMTP_HOST
       value: "smtp.gmail.com"
     - name: SMTP_PORT
       value: "587"
     - name: SMTP_USERNAME
       valueFrom:
         secretKeyRef:
           name: brand-master-email
           key: smtp-username
     - name: SMTP_PASSWORD
       valueFrom:
         secretKeyRef:
           name: brand-master-email
           key: smtp-password
     - name: SMTP_FROM
       value: "noreply@brand-master.com"
   

Local Development (.env file)

Create backend/.env:

DATABASE_URL=postgresql://brand_master_user:your_password@localhost/brand_master_db
JWT_SECRET_KEY=your-secret-key
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8000

# Email Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=noreply@brand-master.com

# Admin Credentials
ADMIN_EMAIL=admin@brandmaster.com
ADMIN_PASSWORD=Admin123!

Testing Email Functionality

Test Password Reset

1. Trigger Password Reset:

   curl -X POST https://api-brand-master.dvirlabs.com/api/auth/request-reset-pin \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com"}'
   

2. Check Email:

   • User should receive email with 6-digit PIN
   • PIN expires in 15 minutes

3. Reset Password:

   curl -X POST https://api-brand-master.dvirlabs.com/api/auth/reset-password-with-pin \
     -H "Content-Type: application/json" \
     -d '{
       "email": "user@example.com",
       "pin": "123456",
       "new_password": "NewPassword123!"
     }'
   

Test Welcome Email

1. Register New User:

   curl -X POST https://api-brand-master.dvirlabs.com/api/auth/register \
     -H "Content-Type: application/json" \
     -d '{
       "email": "newuser@example.com",
       "full_name": "Test User",
       "password": "password123"
     }'
   

2. Check Email:

   • User should receive welcome email

Check Backend Logs

If emails aren't being sent:

# View backend logs
kubectl logs -n my-apps deployment/brand-master-backend -f

# Look for:
# ✅ Email sent successfully to user@example.com
# OR
# ⚠️ SMTP not configured. Email would have been sent to: user@example.com
# OR
# ❌ Failed to send email to user@example.com: <error details>

Troubleshooting

Issue: "SMTP not configured" message

Problem: SMTP environment variables not set

Solution:

# Check if variables are set in pod
kubectl exec -n my-apps deployment/brand-master-backend -- env | grep SMTP

# Should show:
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_USERNAME=your-email@gmail.com
# SMTP_PASSWORD=***
# SMTP_FROM=noreply@brand-master.com

Issue: "Authentication failed" error

Problem: Wrong credentials or app password required

Solution:

• For Gmail: Use App Password, not account password
• Verify credentials are correct
• Check if 2FA is enabled (required for App Passwords)

Issue: "Connection refused" error

Problem: Wrong SMTP host or port, or firewall blocking

Solution:

• Verify SMTP_HOST and SMTP_PORT are correct
• Check Kubernetes network policies
• Test SMTP connection from pod:

  kubectl exec -n my-apps deployment/brand-master-backend -- \
    nc -zv smtp.gmail.com 587
  

Issue: Emails go to spam

Problem: Missing SPF/DKIM records or sender reputation

Solution:

• Use verified domain with proper DNS records
• Use SendGrid or SES for production
• Add SPF record: v=spf1 include:_spf.google.com ~all
• Setup DKIM signing

Email Templates

Email templates are in backend/app/services/email.py:

• send_password_reset_pin() - Password reset with PIN
• send_welcome_email() - Welcome new users

To customize:

1. Edit template in email.py
2. Rebuild backend image
3. Redeploy

Production Best Practices

1. ✅ Use Kubernetes Secrets for credentials
2. ✅ Use dedicated email service (SendGrid, SES)
3. ✅ Setup SPF/DKIM for deliverability
4. ✅ Monitor email sending (logs, metrics)
5. ✅ Implement rate limiting to prevent abuse
6. ✅ Use verified sender domain
7. ✅ Add unsubscribe links for marketing emails
8. ✅ Keep templates professional and branded

Quick Setup for Testing (Gmail)

# 1. Update values.yaml
nano brand-master-chart/values.yaml

# Add under backend.env:
    - name: SMTP_HOST
      value: "smtp.gmail.com"
    - name: SMTP_PORT
      value: "587"
    - name: SMTP_USERNAME
      value: "your-email@gmail.com"
    - name: SMTP_PASSWORD
      value: "your-16-char-app-password"
    - name: SMTP_FROM
      value: "Brand Master <noreply@brand-master.com>"

# 2. Redeploy
cd brand-master-chart
helm upgrade brand-master . --namespace my-apps --wait

# 3. Test
curl -X POST https://api-brand-master.dvirlabs.com/api/auth/request-reset-pin \
  -H "Content-Type: application/json" \
  -d '{"email": "your-test-email@gmail.com"}'

# 4. Check email inbox

Support

If emails still don't work:

1. Check backend logs for error messages
2. Verify SMTP credentials
3. Test SMTP connection manually
4. Check spam folder
5. Try different email provider

---

Status: Email service implemented and ready to configure
Last Updated: May 8, 2026