HH/docs/SIMULATOR_QUICKSTART.md

Simulator API - Quick Start Guide

What is the Simulator API?

The Simulator API provides mock endpoints for testing email and SMS notifications without using real third-party services. It:

• Sends real emails via Django SMTP
• Prints SMS messages to terminal with formatted output
• Integrates seamlessly with the existing NotificationService

Quick Start (5 Minutes)

1. Start the Development Server

cd /home/ismail/projects/HH
python manage.py runserver

2. Enable the Simulator

Edit your .env file and add these lines:

# Enable external API notifications
EMAIL_API_ENABLED=true
SMS_API_ENABLED=true

# Point to simulator endpoints
EMAIL_API_URL=http://localhost:8000/api/simulator/send-email
SMS_API_URL=http://localhost:8000/api/simulator/send-sms

# Simulator authentication (any value works)
EMAIL_API_KEY=simulator-test-key
SMS_API_KEY=simulator-test-key

# Authentication method
EMAIL_API_AUTH_METHOD=bearer
SMS_API_AUTH_METHOD=bearer

# Email SMTP settings (for real emails)
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=10.10.1.110
EMAIL_PORT=2225
EMAIL_USE_TLS=true
DEFAULT_FROM_EMAIL=noreply@px360.sa

3. Test the Simulator

Run the test script:

python test_simulator.py

This will:

• ✅ Send test emails (via SMTP)
• ✅ Send test SMS (printed to terminal)
• ✅ Check simulator health
• ✅ Test error handling
• ✅ Display statistics

4. Use in Your Code

from apps.notifications.services import NotificationService

# Send email
log = NotificationService.send_email_via_api(
    message='Your account has been created!',
    email='user@example.com',
    subject='Welcome to PX360'
)

# Send SMS
log = NotificationService.send_sms_via_api(
    message='Your verification code is 123456',
    phone='+966501234567'
)

Expected Output

Email (in terminal)

======================================================================
📧 EMAIL SIMULATOR - Request #1
======================================================================
To:      user@example.com
Subject: Welcome to PX360
Message: Your account has been created!
HTML:    No
======================================================================

SMS (in terminal)

══════════════════════════════════════════════════════════════════════
               📱 SMS SIMULATOR                                  
══════════════════════════════════════════════════════════════════════
Request #: 1                                                    
══════════════════════════════════════════════════════════════════════
To:      +966501234567                                           
Time:    2026-01-12 18:08:00                                   
══════════════════════════════════════════════════════════════════════
Message:                                                        
         Your verification code is 123456                        
══════════════════════════════════════════════════════════════════════

Available Endpoints

Endpoint	Method	Description
/api/simulator/send-email	POST	Send email via SMTP
/api/simulator/send-sms	POST	Print SMS to terminal
/api/simulator/health	GET	Check simulator status
/api/simulator/reset	GET	Reset counters

Check Simulator Status

curl http://localhost:8000/api/simulator/health

Response:

{
  "status": "healthy",
  "statistics": {
    "total_requests": 5,
    "email_requests": 3,
    "sms_requests": 2
  }
}

Switching to Real APIs

When ready to use real notification services, just update .env:

EMAIL_API_ENABLED=true
EMAIL_API_URL=https://api.yourservice.com/send-email
SMS_API_ENABLED=true
SMS_API_URL=https://api.yourservice.com/send-sms

No code changes required!

Troubleshooting

Simulator not working?

1. Check server is running: python manage.py runserver
2. Check .env has correct URLs
3. Check health: curl http://localhost:8000/api/simulator/health

Emails not received?

1. Verify SMTP settings in .env
2. Check logs/px360.log for errors
3. Check spam folder

SMS not showing in terminal?

1. Ensure server running in visible terminal
2. Check logs/px360.log for SMS logs

Documentation

• Full Documentation: SIMULATOR_API.md
• External API Service: EXTERNAL_API_NOTIFICATION.md
• Test Script: test_simulator.py

Support

For issues or questions:

1. Check logs: logs/px360.log
2. Run test script: python test_simulator.py
3. See full documentation: docs/SIMULATOR_API.md

Summary

✅ Email Simulator: Sends real emails via SMTP
✅ SMS Simulator: Prints formatted SMS to terminal
✅ Easy Setup: Just update .env file
✅ No Code Changes: Works with existing NotificationService
✅ Production Ready: Easy switch to real APIs

Happy testing! 🚀