# Mailtrap Setup Guide for Email 2FA

## 🚀 Quick Setup

### **1. Get Mailtrap Credentials**

1. Go to [Mailtrap.io](https://mailtrap.io/)
2. Sign up/login to your account
3. Go to **Email Testing** → **Inboxes**
4. Select your inbox (or create a new one)
5. Click **"Show Credentials"** or **"Integrations"**
6. Copy the **SMTP credentials**

### **2. Update .env File**

Replace the placeholder values in your `.env` file:

```env
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your-actual-mailtrap-username
MAIL_PASSWORD=your-actual-mailtrap-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@yourapp.com"
MAIL_FROM_NAME="${APP_NAME}"
```

**Replace:**
- `your-actual-mailtrap-username` → Your Mailtrap username
- `your-actual-mailtrap-password` → Your Mailtrap password

### **3. Clear Configuration Cache**

```bash
php artisan config:cache
php artisan config:clear
```

## 🧪 Test Email Sending

### **Option 1: Use the Test Command**

```bash
# Test with default email
php artisan email:test

# Test with specific email
php artisan email:test your-email@example.com
```

### **Option 2: Run the Test Suite**

```bash
# Run Mailtrap-specific tests
php artisan test tests/Feature/MailtrapTest.php

# Run all 2FA tests
php artisan test tests/Feature/EmailTwoFactorTest.php
```

### **Option 3: Test via API**

```bash
# Send a test 2FA code
curl -X POST http://localhost:8000/api/2fa/send-email-code \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
```

## 📧 Check Mailtrap Inbox

1. Go to your Mailtrap inbox
2. Look for the email with subject: **"Your 2FA Verification Code"**
3. Open the email to see:
   - The 6-digit verification code
   - Professional HTML design
   - Security warnings and instructions

## 🔧 Troubleshooting

### **Common Issues:**

#### **1. Authentication Failed**
```
Error: "Authentication failed"
```
**Solution:** Double-check your Mailtrap username and password in `.env`

#### **2. Connection Refused**
```
Error: "Connection could not be established"
```
**Solution:** Check if `smtp.mailtrap.io` is accessible from your network

#### **3. Email Not Arriving**
**Solution:** 
- Check Mailtrap inbox is active
- Verify email address is correct
- Check Mailtrap email quota

#### **4. Configuration Not Updating**
**Solution:** Run `php artisan config:cache` to refresh configuration

### **Debug Steps:**

1. **Check Configuration:**
```bash
php artisan config:show mail
```

2. **Test Connection:**
```bash
php artisan email:test
```

3. **Check Logs:**
```bash
tail -f storage/logs/laravel.log
```

## 🎯 Mailtrap Benefits

### **Development Advantages:**
- **No real emails sent** - Safe for development
- **Instant delivery** - No delays
- **Beautiful preview** - See exactly what users see
- **HTML/CSS testing** - Verify email rendering
- **Spam testing** - Check spam scores

### **Testing Scenarios:**
- ✅ **2FA code delivery**
- ✅ **Email template design**
- ✅ **Link functionality**
- ✅ **Responsive design**
- ✅ **Spam filter testing**

## 📊 Mailtrap vs Production

| Feature | Mailtrap | Production |
|---------|----------|------------|
| **Real Delivery** | ❌ No | ✅ Yes |
| **Instant Preview** | ✅ Yes | ❌ No |
| **Safe Testing** | ✅ Yes | ❌ No |
| **Spam Testing** | ✅ Yes | ❌ No |
| **Cost** | Free tier | Paid service |

## 🔄 Switching to Production

When ready for production, update your `.env`:

```env
# For Gmail/Google Workspace
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls

# For SendGrid
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
```

## 📱 Mobile Testing

Mailtrap also has mobile apps:
- **iOS App** - Test on iPhone/iPad
- **Android App** - Test on Android devices
- **Email previews** - See mobile rendering

## 🎨 Email Template Features

Your 2FA email includes:
- **Gradient code display** - Easy to read
- **Security warnings** - User education
- **Expiration info** - Clear time limits
- **Professional design** - Trust building
- **Responsive layout** - Mobile friendly

## ✅ Verification Checklist

Before going to production, verify:

- [ ] Mailtrap credentials are correct
- [ ] Test command sends email successfully
- [ ] Email appears in Mailtrap inbox
- [ ] 2FA code is visible and readable
- [ ] Email template looks professional
- [ ] Links and formatting work correctly
- [ ] Mobile rendering looks good

## 🚀 Next Steps

1. **Test thoroughly** with Mailtrap
2. **Verify all email scenarios** work
3. **Check mobile rendering** on different devices
4. **Test spam scores** in Mailtrap
5. **Set up production email service** when ready

Your email 2FA system is now ready for development and testing with Mailtrap! 🎉