SkyArtShop/docs/EMAIL_SETUP_GUIDE.md

# 📧 Sky Art Shop - Email Configuration Guide

This guide will help you set up email sending for verification codes and newsletters.

---

## Prerequisites

- A Gmail account (recommended for simplicity)
- 2-Factor Authentication enabled on that Gmail account

---

## Step 1: Enable 2-Factor Authentication on Gmail

1. Go to: **<https://myaccount.google.com/security>**
2. Scroll to "Signing in to Google"
3. Click on **"2-Step Verification"**
4. Follow the prompts to enable it (if not already enabled)
5. Complete the setup with your phone number

---

## Step 2: Generate an App Password

1. Go to: **<https://myaccount.google.com/apppasswords>**
2. Sign in if prompted
3. At the bottom, click **"Select app"** → Choose **"Mail"**
4. Click **"Select device"** → Choose **"Other (Custom name)"**
5. Type: `Sky Art Shop`
6. Click **"Generate"**
7. You'll see a **16-character password** like: `abcd efgh ijkl mnop`
8. **COPY THIS PASSWORD** (you won't see it again!)

---

## Step 3: Configure Your Backend

### Option A: Edit .env file directly

Open the file:

```bash
nano /media/pts/Website/SkyArtShop/backend/.env
```

Find these lines at the bottom and update them:

```
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=YOUR_GMAIL@gmail.com
SMTP_PASS=YOUR_APP_PASSWORD
SMTP_FROM="Sky Art Shop" <YOUR_GMAIL@gmail.com>
```

**Replace:**

- `YOUR_GMAIL@gmail.com` → Your actual Gmail address (appears 2 times)
- `YOUR_APP_PASSWORD` → The 16-character app password (remove all spaces)

**Example** (if your email is `myshop@gmail.com` and password is `abcd efgh ijkl mnop`):

```
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=myshop@gmail.com
SMTP_PASS=abcdefghijklmnop
SMTP_FROM="Sky Art Shop" <myshop@gmail.com>
```

Save the file: `Ctrl+O`, then `Enter`, then `Ctrl+X`

---

## Step 4: Test Your Configuration

Run the test script:

```bash
cd /media/pts/Website/SkyArtShop/backend
node test-email.js your-personal-email@example.com
```

Replace `your-personal-email@example.com` with an email where you can check the inbox.

**If successful, you'll see:**

```
✅ EMAIL SENT SUCCESSFULLY!
📬 Check your inbox at: your-personal-email@example.com
```

---

## Step 5: Restart the Server

```bash
pm2 restart skyartshop
```

---

## Troubleshooting

### "Authentication failed" error

- Make sure you're using the **App Password**, not your regular Gmail password
- Check that the app password has no spaces
- Verify 2-Factor Authentication is enabled

### "Connection refused" error

- Check SMTP_HOST is exactly `smtp.gmail.com`
- Check SMTP_PORT is `587`
- Make sure your server has internet access

### Emails going to spam

- Ask recipients to mark your emails as "Not Spam"
- Add a proper SMTP_FROM name
- For production, consider using SendGrid or Mailgun

### "Less secure apps" message

- Don't enable "Less secure apps" - use App Passwords instead
- App Passwords are more secure and work better

---

## Alternative Email Services (For Production)

### SendGrid (Recommended for production)

- 100 emails/day free
- Website: <https://sendgrid.com>

```
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key
SMTP_FROM="Sky Art Shop" <noreply@yourdomain.com>
```

### Mailgun

- 5,000 emails/month free (for 3 months)
- Website: <https://mailgun.com>

### Amazon SES

- Very cheap for high volume
- Website: <https://aws.amazon.com/ses/>

---

## Quick Reference

| Setting | Gmail Value |
|---------|-------------|
| SMTP_HOST | smtp.gmail.com |
| SMTP_PORT | 587 |
| SMTP_SECURE | false |
| SMTP_USER | <your-email@gmail.com> |
| SMTP_PASS | 16-char-app-password |

---

## Files Modified

- `/backend/.env` - Contains your SMTP credentials
- `/backend/test-email.js` - Test script to verify configuration
- `/backend/routes/customer-auth.js` - Uses these settings to send verification emails

---

## What Emails Will Be Sent?

Once configured, the system will automatically send:

1. **Verification Codes** - When customers sign up
2. **Password Reset** - When customers forget their password (future feature)
3. **Newsletters** - For subscribed customers (future feature)
4. **Order Confirmations** - After purchases (future feature)

---

## Security Notes

⚠️ **Never commit your .env file to Git**
⚠️ **Never share your App Password**
⚠️ **Rotate your App Password if compromised**

The `.env` file is already in `.gitignore` so it won't be uploaded to version control.

---

## Need Help?

If you encounter issues:

1. Check the PM2 logs: `pm2 logs skyartshop`
2. Run the test script again with verbose output
3. Verify your Gmail App Password is correct

---

*Last updated: January 2026*