Metadata-Version: 2.4
Name: django-outlook-sync-inbox
Version: 1.2.2
Summary: A production-ready Django application package to automate background syncing of local desktop Outlook emails with both HTML and REST API interfaces.
Author-email: Yonas <yonas2754@gmail.com>
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pywin32; sys_platform == "win32"
Requires-Dist: schedule>=1.2.0
Requires-Dist: djangorestframework>=3.14.0



```markdown
# 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.2.2

```

---

## ⚙️ 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:

```python
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:

```python
# ==============================================================================
# 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:

```powershell
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`**:

```python
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:

```powershell
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:*

```powershell
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:

```json
[
    {
        "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": "Hello, Your email has been received and processed successfully by our application system. Thank you.",
                "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.

```

```
