Sindbad~EG File Manager

# Email Management System

## Overview
The Email Management System provides comprehensive email functionality for the Church Membership Management System, including automated welcome emails, customizable templates, and queue management.

## Features

### 1. Email Settings & Configuration
- **SMTP Configuration**: Configure SMTP server settings (host, port, encryption, credentials)
- **From Address**: Set default sender email and name
- **Enable/Disable**: Global toggle for email functionality
- **Welcome Email Controls**: Enable/disable welcome emails for users and members

### 2. Email Templates
- **User Welcome Email**: Sent when new user accounts are created
- **Member Welcome Email**: Sent when new members are added
- **Template Variables**: Dynamic content replacement (name, email, member ID, etc.)
- **HTML Support**: Rich HTML email templates

### 3. Email Queue System
- **Queue Management**: All emails are queued for reliable delivery
- **Status Tracking**: Track pending, sent, and failed emails
- **Retry Logic**: Automatic retry for failed emails
- **Statistics**: Monitor email delivery performance

### 4. Automated Email Triggers
- **User Registration**: Automatic welcome email when users are created
- **Member Registration**: Automatic welcome email when members are added
- **Conditional Sending**: Only sends if email address is provided and feature is enabled

## File Structure

```
/modules/email/
├── index.php              # Main email management interface

/classes/
├── EmailService.php       # Core email service class

/api/
├── email.php             # Email API endpoints

/cron/
├── process_emails.php    # Email queue processor

/sql/
├── email_settings.sql    # Database schema
└── add_email_module.sql  # Module registration

/docs/
└── EMAIL_SYSTEM.md       # This documentation
```

## Database Tables

### email_settings
Stores email configuration and template settings:
- SMTP server configuration
- Email templates and subjects
- Feature enable/disable flags

### email_queue
Manages the email delivery queue:
- Recipient information
- Email content and type
- Delivery status and attempts
- Error tracking

## Setup Instructions

### 1. Database Setup
```sql
-- Run the email settings schema
SOURCE sql/email_settings.sql;

-- Add email module to navigation
SOURCE sql/add_email_module.sql;
```

### 2. Email Configuration
1. Navigate to **Email Management** in the admin panel
2. Configure SMTP settings in the **SMTP Settings** tab
3. Enable the email system
4. Customize email templates in the **Email Templates** tab
5. Test configuration using the **Test Email** tab

### 3. Queue Processing
Set up automated email processing using one of these methods:

#### Option A: Cron Job (Recommended)
```bash
# Add to crontab to process emails every 5 minutes
*/5 * * * * php /path/to/copmadinaarea/cron/process_emails.php
```

#### Option B: Manual Processing
Visit: `http://yoursite.com/copmadinaarea/cron/process_emails.php?manual=1`

## Template Variables

### User Welcome Email
- `{name}` - User's full name
- `{email}` - User's email address
- `{username}` - User's username
- `{login_url}` - Link to login page

### Member Welcome Email
- `{name}` - Member's full name
- `{email}` - Member's email address
- `{member_id}` - Member's ID/card number
- `{phone}` - Member's phone number

## API Endpoints

### GET /api/email.php?action=stats
Returns email queue statistics

### GET /api/email.php?action=queue&limit=20
Returns recent emails from queue

### GET /api/email.php?action=process
Manually triggers email processing

### GET /api/email.php?action=test_connection
Tests email system status

## Security Features

- **Access Control**: Only superusers and area-level users can access email management
- **Input Validation**: All form inputs are validated and sanitized
- **SQL Injection Protection**: Prepared statements used throughout
- **Error Handling**: Comprehensive error logging and user feedback

## Troubleshooting

### Emails Not Sending
1. Check if email system is enabled in settings
2. Verify SMTP configuration is correct
3. Check email queue for failed messages
4. Review error logs in `/logs/email_processor.log`

### Template Issues
1. Ensure all required variables are present in templates
2. Check HTML syntax in email templates
3. Test with simple plain text first

### Queue Processing
1. Verify cron job is running correctly
2. Check file permissions on processor script
3. Monitor queue statistics for processing rate

## Best Practices

1. **Test Configuration**: Always test email settings before enabling
2. **Monitor Queue**: Regularly check email queue status
3. **Template Testing**: Test email templates with real data
4. **Error Monitoring**: Monitor logs for delivery issues
5. **Performance**: Process emails in batches to avoid server overload

## Future Enhancements

- **Email Analytics**: Track open rates and click-through rates
- **Advanced Templates**: Visual template editor
- **Bulk Email**: Mass email functionality for announcements
- **Email Scheduling**: Schedule emails for future delivery
- **Integration**: Connect with external email services (SendGrid, Mailgun)