django-outlook-sync-inbox 1.1.0

A production-ready Django application package to automate background syncing of local desktop Outlook emails with both HTML and REST API interfaces.

# Django Outlook Sync Inbox

A production-ready Django application package designed to automate background syncing of local desktop Outlook emails into your Django database application space, exposing both an administrative HTML Monitoring Dashboard and clean, lightweight JSON REST API endpoints.

---

## 🚀 Key Features

* **Background Daemon Process:** Keeps a light, standalone background loop active to scrape emails automatically using the Windows background environment.
* **Strict Recipient Filtering:** Restricts email ingestion to specific targeted email addresses.
* **Conditional Response Routing:** Dynamically evaluates subject keywords and current operational hours to choose between multiple automated email reply templates.
* **Smart Loop & Thread Protection:** Scans historical database text footprints and filters out reply markers (`RE:`, `FW:`) to block recursive loop cascades.
* **Data Extraction Pipeline:** Statically extracts inline attachments/images and features a word-extraction text cleaner to strip legacy tags inside the Django Admin dashboard field views.
* **Hierarchical Tree API:** Organizes responses into a nested conversation structure, automatically grouping email replies right inside their parent thread arrays.

---

## 🛠️ Step 1: Installation & Setup

Install your library using Python's package manager inside your active project virtual environment:

```powershell
pip install django-outlook-sync-inbox==1.1.0

---

⚙️ Step 2: Framework Configuration

Open your target Django project's main settings.py file and register your configurations.

1. Register Apps in INSTALLED_APPS

Add the core Django REST Framework along with your newly installed library package namespace:

INSTALLED_APPS = [
    # ... Django base core apps ...
    
    'rest_framework',
    'django_outlook_sync',  # Core application directory mapping
]

2. Append Custom Parameters Block

Scroll to the bottom of settings.py and define your strict processing criteria limits, evaluation rules, and message layout choices:

# ==============================================================================
# DJANGO OUTLOOK SYNC CONFIGURATION SYSTEM
# ==============================================================================

# Case-insensitive string filters matching fields found in TO or CC email headers
OUTLOOK_ALLOWED_RECIPIENTS = [
    "abebe kebede chale",
    "yonas mulugeta teruwha"
]

# 1. Keywords used to trigger the high-priority reply layout dynamically
OUTLOOK_PRIORITY_KEYWORDS = ["urgent", "priority", "critical"]

# 2. Operational hour boundaries (Outside hours defined as >= 18 or < 8)
OUTLOOK_OFF_HOURS_START = 18
OUTLOOK_OFF_HOURS_END = 8

# 3. Categorized conditional HTML reply message template options
OUTLOOK_REPLY_TEMPLATES = {
    "default": """
        <p>Hello,</p>
        <p>Your email has been received and processed successfully by our application system.</p>
        <p>Thank you.</p>
    """,
    "outside_hours": """
        <p>Hello,</p>
        <p>Thank you for reaching out. We have received your message, but please note that our synchronization system is currently running outside of normal operational hours. We will review your request during the next session.</p>
        <p>Best regards,</p>
    """,
    "priority": """
        <p>Hello,</p>
        <p>This is an automated confirmation that your high-priority request has been successfully synced to our escalation database pipeline.</p>
    """
}

---

🗄️ Step 3: Database Migrations & URLs

1. Apply Layout Migrations

Generate and run the schema structural layout blueprints inside your project directory database using management commands:

python manage.py makemigrations django_outlook_sync
python manage.py migrate

2. Include Routing Rules in urls.py

Expose your component interfaces inside your core primary app routing table myproject/urls.py:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    
    # Mounts all user interfaces and API endpoints under the /outlook/ prefix
    path('outlook/', include('django_outlook_sync.urls')),
]

---

🔑 Step 4: First-Time Setup (Crucial)

Before you fire up the background automation script, you must open the communication bridge on your desktop:

1. Open your Microsoft Outlook desktop application.
2. Ensure you are logged into your profile account and your inbox is active.
3. Leave the Outlook application running (you can minimize it) in the background.

---

⏰ Step 5: Running the Background Daemon Engine

Once Outlook is running on your desktop, open a separate dedicated console terminal window, make sure your virtual environment is active, and fire up your global tracking loop macro command line executable:

django-outlook-daemon

Note: If your local path configuration does not support global entry script maps, you can run the internal package entry point module pathway explicitly instead:

python -m django_outlook_sync.auto_sync

---

🖥️ Step 6: How to view the final output

Once your background daemon engine is running and processing inbound traffic sequences, open your web browser to check the final application results via these distinct channels:

Output Interfaces Reference Guide

Interface Description	Targeted Endpoint URL Route	Output Content Payload Structure
Django Admin Board	http://127.0.0.1:8000/admin/django_outlook_sync/emailmessage/	Built-in administrative panel with widgets optimized to extract only pure statement text words.
HTML Mailbox UI Monitor	http://127.0.0.1:8000/outlook/inbox/	A production-ready dashboard grid displaying all ingested database email rows.
Nested Tree REST API	http://127.0.0.1:8000/outlook/api/emails/	(Default) Returns a hierarchical JSON structure with thread replies nested inside parents.
Flat List REST API	http://127.0.0.1:8000/outlook/api/emails/flat/	Returns a standard single-level collection array containing all chronological emails.
Single Ingest Details Lookup	http://127.0.0.1:8000/outlook/api/emails/1/	Detailed profile lookup tracking a specific email instance item row by database ID.

Hierarchical Tree REST API Output Sample Result

The default API response groups related messages automatically. Reply instances are grouped back into their respective conversation tracks inside the "replies" list property:

[
    {
        "id": 16,
        "subject": "test3",
        "sender": "Yonas Mulugeta Teruwha",
        "recipients": "Yonas Mulugeta Teruwha",
        "cc_recipients": "",
        "html_body": "Test3",
        "received_at": "2026-06-22T04:13:59Z",
        "is_thread_reply": false,
        "created_at": "2026-06-22T01:15:44.003763Z",
        "replies": [
            {
                "id": 20,
                "subject": "RE: test3",
                "sender": "Yonas Mulugeta Teruwha",
                "recipients": "Yonas Mulugeta Teruwha",
                "cc_recipients": "",
                "html_body": "Test3",
                "received_at": "2026-06-22T04:15:45Z",
                "is_thread_reply": true,
                "created_at": "2026-06-22T01:17:51.520935Z"
            }
        ]
    }
]

---

🛑 Troubleshooting

• Loop / Double Processing: The engine evaluates text signatures across raw and text objects. If your custom reply template text structure changes, update the validation string definitions within your script files to ensure thread containment checks continue functioning correctly.
• Missing Images: Static assets are served locally using your primary web server engine context. Ensure django.contrib.staticfiles handles paths properly inside your global server properties configurations.