# Email Template System

## Overview
RMBXchange now has a professional HTML email template system with a consistent design across all transactional emails.

## Template Structure

### Base Layout
- **File**: `resources/views/emails/layout.blade.php`
- **Features**:
  - Responsive design (mobile-friendly)
  - Brand colors (Blue #1A6EC8, Orange #E8530A)
  - Professional header with logo
  - Consistent footer with links
  - Alert boxes (success, warning, danger)
  - Info boxes for transaction details
  - Call-to-action buttons

### Available Email Templates

#### 1. Password Reset
- **File**: `resources/views/emails/password-reset.blade.php`
- **Usage**: Sent when user requests password reset
- **Variables**:
  - `$userName` - User's name
  - `$resetUrl` - Password reset link

#### 2. Order Completed
- **File**: `resources/views/emails/order-completed.blade.php`
- **Usage**: Sent when admin marks an exchange order as completed
- **Variables**:
  - `$userName` - User's name
  - `$orderNumber` - Order reference number
  - `$ghsAmount` - Amount paid in GHS
  - `$cnyAmount` - Amount received in CNY
  - `$exchangeRate` - Exchange rate used

#### 3. Wallet Top-Up
- **File**: `resources/views/emails/wallet-topup.blade.php`
- **Usage**: Sent when wallet top-up payment is successful
- **Variables**:
  - `$userName` - User's name
  - `$reference` - Transaction reference
  - `$ghsAmount` - Amount paid in GHS
  - `$cnyAmount` - Amount credited in CNY
  - `$exchangeRate` - Exchange rate used
  - `$newBalance` - New wallet balance

#### 4. Withdrawal Submitted
- **File**: `resources/views/emails/withdrawal-submitted.blade.php`
- **Usage**: Sent when user submits a withdrawal request
- **Variables**:
  - `$userName` - User's name
  - `$amount` - Withdrawal amount in CNY
  - `$reference` - Transaction reference
  - `$alipayAccount` - Alipay account number

#### 5. Withdrawal Approved
- **File**: `resources/views/emails/withdrawal-approved.blade.php`
- **Usage**: Sent when admin approves a withdrawal request
- **Variables**:
  - `$userName` - User's name
  - `$amount` - Withdrawal amount in CNY
  - `$reference` - Transaction reference
  - `$alipayAccount` - Alipay account number

#### 6. Withdrawal Rejected
- **File**: `resources/views/emails/withdrawal-rejected.blade.php`
- **Usage**: Sent when admin rejects a withdrawal request
- **Variables**:
  - `$userName` - User's name
  - `$amount` - Withdrawal amount in CNY
  - `$reference` - Transaction reference

#### 7. Welcome Email
- **File**: `resources/views/emails/welcome.blade.php`
- **Usage**: Can be sent to new users (optional)
- **Variables**:
  - `$userName` - User's name

#### 8. Custom Message
- **File**: `resources/views/emails/custom-message.blade.php`
- **Usage**: For admin-sent custom messages
- **Variables**:
  - `$userName` - User's name
  - `$message` - Custom message content

## EmailService Usage

### Updated Method Signature
```php
public function send(
    string $email, 
    string $subject, 
    string $message, 
    ?string $template = null, 
    array $data = []
): array
```

### Sending Plain Text Email
```php
$emailService = new \App\Services\EmailService();
$emailService->send(
    'user@example.com',
    'Subject Line',
    'Plain text message content'
);
```

### Sending HTML Template Email
```php
$emailService = new \App\Services\EmailService();
$emailService->send(
    'user@example.com',
    'Order Completed - RMBXchange',
    '', // Empty message when using template
    'emails.order-completed',
    [
        'userName' => 'John Doe',
        'orderNumber' => 'ORD-12345',
        'ghsAmount' => 100.00,
        'cnyAmount' => 57.00,
        'exchangeRate' => 0.57
    ]
);
```

## Email Provider Support

The system supports three email providers:

### 1. SMTP (Default)
- Uses Laravel's built-in Mail facade
- Configurable via admin settings
- Supports any SMTP server (Gmail, Outlook, etc.)

### 2. Mailjet
- Direct API integration
- Requires API key and secret key
- Professional email delivery service

### 3. PHPMailer
- Uses SMTP configuration
- Alternative to Laravel's Mail facade
- Requires: `composer require phpmailer/phpmailer`

## Configuration

All email settings are managed through the admin dashboard:
- Navigate to: `/admin/settings`
- Configure email provider and credentials
- Set from address and from name
- Test email delivery

## Design Features

### Responsive Design
- Mobile-optimized layout
- Stacks content on small screens
- Touch-friendly buttons

### Brand Consistency
- Uses RMBXchange logo
- Brand colors throughout
- Professional typography

### User Experience
- Clear call-to-action buttons
- Transaction details in organized boxes
- Status indicators (success, warning, danger)
- Easy-to-read formatting

## Adding New Templates

To create a new email template:

1. Create a new Blade file in `resources/views/emails/`
2. Extend the base layout:
```blade
@extends('emails.layout')

@section('content')
    <!-- Your email content here -->
@endsection
```

3. Use the template in your controller:
```php
$emailService->send(
    $email,
    'Subject',
    '',
    'emails.your-template',
    ['variable' => 'value']
);
```

## Best Practices

1. **Always provide user name** for personalization
2. **Include transaction references** for tracking
3. **Use clear call-to-action buttons** for important actions
4. **Keep content concise** and scannable
5. **Test on multiple devices** before deploying
6. **Use appropriate alert boxes** for status messages

## Troubleshooting

### Emails not sending
1. Check email provider configuration in admin settings
2. Verify SMTP credentials are correct
3. Check Laravel logs: `storage/logs/laravel.log`
4. Test with a simple plain text email first

### Templates not rendering
1. Clear view cache: `php artisan view:clear`
2. Check template file exists in `resources/views/emails/`
3. Verify all required variables are passed

### Styling issues
1. Email clients have limited CSS support
2. Use inline styles for critical styling
3. Test in multiple email clients (Gmail, Outlook, etc.)
4. Avoid complex layouts and JavaScript

## Future Enhancements

Potential improvements:
- Email preview in admin dashboard
- A/B testing for email templates
- Email analytics and tracking
- Multi-language support
- Scheduled email campaigns
- Email queue management