HH/templates/emails/README_EMAIL_TEMPLATES.md

# Al Hammadi Hospital Email Templates

Professional, responsive email templates designed with the hospital's brand identity.

## 🎨 Brand Colors

The email templates use Al Hammadi Hospital's official color palette:

| Color | Hex Code | Usage |
|-------|----------|-------|
| **Primary Navy** | `#005696` | Main brand color, headers, primary buttons |
| **Accent Blue** | `#007bbd` | Gradients, secondary elements |
| **Light Background** | `#eef6fb` | Info boxes, highlights |
| **Slate Gray** | `#64748b` | Secondary text |
| **Success Green** | `#10b981` | Positive indicators |
| **Warning Yellow** | `#f59e0b` | Alerts, warnings |

## 📧 Available Templates

### 1. Base Template (`base_email_template.html`)
The foundation template with all common email components:
- Responsive header with logo
- Hero/title section
- Main content area
- Call-to-action button
- Information boxes
- Footer with contact info

**Usage:** Extend this template for all custom emails.

---

### Patient-Facing Templates

### 2. Survey Invitation (`survey_invitation.html`)
Patient survey invitation email with:
- Personalized greeting
- Survey benefits section
- Call-to-action button
- Survey information box

**Context Variables:**
```python
{
    'patient_name': 'John Doe',
    'visit_date': 'March 10, 2026',
    'survey_duration': '3-5 minutes',
    'survey_link': 'https://...',
    'deadline': 'March 17, 2026'
}
```

### 3. Appointment Confirmation (`appointment_confirmation.html`)
Appointment confirmation email with:
- Appointment details card
- Important reminders
- Reschedule/cancel CTA
- Contact information

**Context Variables:**
```python
{
    'patient_name': 'John Doe',
    'appointment_id': 'APT-2026-001',
    'appointment_date': 'March 15, 2026',
    'appointment_time': '10:00 AM',
    'department': 'Cardiology',
    'doctor_name': 'Dr. Ahmed Smith',
    'location': 'Al Hammadi Hospital - Main Branch',
    'reschedule_link': 'https://...'
}
```

### 4. Survey Results Notification (`survey_results_notification.html`)
Department survey results notification with:
- Summary statistics cards
- Key highlights
- Action items
- Full report access

**Context Variables:**
```python
{
    'recipient_name': 'Dr. Sarah Ahmed',
    'department_name': 'Emergency Department',
    'overall_score': '4.5/5',
    'total_responses': '156',
    'response_rate': '78%',
    'survey_period': 'February 2026',
    'results_link': 'https://...',
    'deadline': 'March 31, 2026'
}
```

---

### Staff/Admin Templates

### 5. Explanation Request (`emails/explanation_request.html`)
Complaint explanation request to staff with:
- Complaint details card
- Custom message from PX team
- SLA deadline information
- Submit explanation CTA

**Context Variables:**
```python
{
    'staff_name': 'Dr. Ahmed Mohammed',
    'complaint_id': 'CMP-2026-00123',
    'complaint_title': 'Long wait time in OPD',
    'patient_name': 'Mohammed Ali',
    'hospital_name': 'Al Hammadi Hospital',
    'department_name': 'OPD - Internal Medicine',
    'category': 'Wait Time',
    'status': 'Under Review',
    'created_date': 'March 10, 2026',
    'description': 'Patient waited for 3 hours...',
    'custom_message': 'Please provide detailed explanation',
    'explanation_url': 'https://...'
}
```

### 6. New Complaint Admin Notification (`emails/new_complaint_admin_notification.html`)
Admin notification for new complaints with:
- Priority/severity badges with color coding
- Complaint details grid
- Patient information section
- Hospital/department information
- Description preview
- Action required notice
- View complaint CTA

**Context Variables:**
```python
{
    'admin_name': 'Dr. Sarah Ahmed',
    'priority_badge': '🚨 URGENT',
    'is_high_priority': True,
    'reference_number': 'CMP-2026-00123',
    'complaint_title': 'Long wait time in OPD',
    'priority': 'high',  # low, medium, high, critical
    'severity': 'high',  # low, medium, high, critical
    'status': 'New',
    'patient_name': 'Mohammed Ali',
    'mrn': 'MRN123456',
    'contact_phone': '+966501234567',
    'contact_email': 'patient@email.com',
    'hospital_name': 'Al Hammadi Hospital',
    'department_name': 'OPD - Internal Medicine',
    'description': 'Patient waited for 3 hours...',
    'complaint_url': 'https://...',
    'notification_type': 'Working Hours',
    'current_time': '2026-03-12 10:30:00'
}
```

**Integration:**
- **File:** `apps/complaints/tasks.py`
- **Function:** `notify_admins_new_complaint()`
- **Line:** 2436

### 7. User Invitation (`accounts/onboarding/invitation_email.html`)
New user onboarding invitation with:
- Welcome message
- Onboarding process overview
- Account setup CTA
- Expiry notice

**Context Variables:**
```python
{
    'user': user_instance,
    'activation_url': 'https://...',
    'expires_at': datetime_object
}
```

### 7. Invitation Reminder (`accounts/onboarding/reminder_email.html`)
Onboarding reminder for pending users with:
- Friendly reminder message
- Benefits highlights
- Setup CTA
- Urgency notice

**Context Variables:**
```python
{
    'user': user_instance,
    'activation_url': 'https://...',
    'expires_at': datetime_object
}
```

### 8. Onboarding Completion (`accounts/onboarding/completion_email.html`)
Admin notification for completed onboarding with:
- User information card
- Completion timestamp
- View details CTA

**Context Variables:**
```python
{
    'user': user_instance,
    'user_detail_url': 'https://...'
}
```

### 9. Password Reset (`accounts/email/password_reset_email.html`)
Password reset request with:
- Secure reset link
- Expiry warning
- Support contact info

**Context Variables:**
```python
{
    'user': user_instance,
    'protocol': 'https',
    'domain': 'px360.alhammadihospital.com',
    'uid': uidb64,
    'token': token
}
```

## 📱 Features

### Responsive Design
- Mobile-optimized layout
- Adapts to all screen sizes (320px - 1920px)
- Touch-friendly buttons and links

### Email Client Compatibility
- ✅ Gmail (web, iOS, Android)
- ✅ Outlook (2016+, Office 365)
- ✅ Apple Mail
- ✅ Yahoo Mail
- ✅ AOL Mail

### Accessibility
- Semantic HTML structure
- Alt text for images
- High contrast colors
- Readable font sizes (minimum 14px)

### Dark Mode Support
- Automatic adaptation to dark mode preferences
- Maintains brand integrity in dark mode

## 🛠️ Usage

### Django Template Rendering

```python
from django.core.mail import EmailMultiAlternatives
from django.template.loader import render_to_string

def send_survey_invitation(patient_email, context):
    # Render HTML template
    html_content = render_to_string('emails/survey_invitation.html', context)
    
    # Create plain text alternative
    text_content = f"""
    Dear {context['patient_name']},
    
    We value your feedback! Please take {context['survey_duration']} to complete our survey.
    
    Survey Link: {context['survey_link']}
    
    Thank you,
    Al Hammadi Hospital
    """
    
    # Send email
    msg = EmailMultiAlternatives(
        subject='Patient Survey Invitation - Al Hammadi Hospital',
        body=text_content,
        from_email='noreply@alhammadihospital.com',
        to=[patient_email],
    )
    msg.attach_alternative(html_content, 'text/html')
    msg.send()
```

### Customizing Templates

1. **Extend the base template:**
```django
{% extends 'emails/base_email_template.html' %}

{% block title %}Your Custom Title{% endblock %}
{% block hero_title %}Your Hero Title{% endblock %}
{% block content %}
    <!-- Your custom content -->
{% endblock %}
```

2. **Override specific blocks:**
```django
{% block cta_text %}Custom Button Text{% endblock %}
{% block cta_url %}https://your-link.com{% endblock %}
{% block info_title %}Custom Info Title{% endblock %}
```

3. **Add custom styles:**
```django
{% block extra_styles %}
<style>
    .custom-class { color: #005696; }
</style>
{% endblock %}
```

## 📋 Best Practices

### Content Guidelines
- Keep subject lines under 50 characters
- Use preheader text effectively (35-50 characters)
- Include clear, single call-to-action
- Keep email width under 600px

### Image Guidelines
- Use PNG for logos (transparent background)
- Optimize images for web (under 100KB)
- Always include alt text
- Host images on reliable CDN

### Testing
Before sending:
1. Test on multiple email clients
2. Check mobile responsiveness
3. Verify all links work
4. Test with dark mode enabled
5. Check spam score

### Recommended Tools
- **Testing:** Litmus, Email on Acid
- **Images:** TinyPNG, Squoosh
- **Spam Check:** Mail-Tester, GlockApps

## 📁 File Structure

```
templates/emails/
├── base_email_template.html              # Base template
├── survey_invitation.html                # Survey invitation
├── appointment_confirmation.html         # Appointment confirmation
├── survey_results_notification.html      # Results notification
├── explanation_request.html              # Complaint explanation request
├── new_complaint_admin_notification.html # Admin complaint notification ⭐ NEW
├── email_templates_preview.html          # Visual preview page
└── README_EMAIL_TEMPLATES.md            # This file

templates/accounts/
├── onboarding/
│   ├── invitation_email.html        # User invitation
│   ├── reminder_email.html          # Invitation reminder
│   └── completion_email.html        # Completion notification
└── email/
    └── password_reset_email.html     # Password reset
```

## 🔧 Logo Setup

Update the logo URL in your Django settings or pass it in context:

```python
# settings.py
EMAIL_LOGO_URL = 'https://your-cdn.com/images/HH_P_H_Logo(hospital)_.png'

# Or in view context
context = {
    'logo_url': request.build_absolute_uri(
        static('images/HH_P_H_Logo(hospital)_.png')
    )
}
```

## 📞 Support

For questions or custom template requests, contact:
- **Email:** px-team@alhammadihospital.com
- **Department:** Patient Experience Management

---

**Version:** 1.0  
**Last Updated:** March 12, 2026  
**Maintained by:** PX360 Development Team