HyTrackV3

HyTrackV3 is an automated logistics intelligence tracker designed to streamline package tracking. It connects to your email server via IMAP, intelligently parses waybills for supported couriers (currently Blue Dart and Delhivery), and uses Selenium with BeautifulSoup to fetch real-time delivery statuses.

Try It Now

You can use our hosted instance to track your packages immediately.

Simply email your Blue Dart or Delhivery tracking numbers (waybills) to:

notify@hyclotron.com

The system will ingest your tracking number, start monitoring the package, and send you beautiful, HTML-formatted status updates directly to your inbox whenever the status changes.

Email Previews

Here is what the automated status updates look like:

Features

Automated Email Ingestion

Seamlessly connects to your email provider to discover new tracking numbers automatically.

Multi-Courier Support

Built-in support for major Indian logistics providers: - Blue Dart (via Requests/BeautifulSoup) - Delhivery (via Selenium Headless Browser)

Smart Tracking

Uses headless Chrome for dynamic content. - Handles session management and retries for robust fetching.

Database Persistence

Maintains a local SQLite database (hytrack3.db) to track shipment history and avoid duplicate processing.

Automated Notifications

Sends HTML-formatted email updates whenever a shipment status changes.

Prerequisites

Before running HyTrackV3 locally, ensure you have the following installed:

Python 3.8+
Google Chrome (latest stable version)
Git

Installation

Clone the repository:

git clone https://github.com/nicx17/HyTrackV3.git
cd HyTrackV3

Set up a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Note: This will install selenium, beautifulsoup4, requests, webdriver-manager, and other required packages.

Configuration

HyTrackV3 requires environment variables to connect to your email accounts.

Copy the sample configuration:
```
cp sample.env.txt .env
```
Edit .env: Open the .env file and fill in your details.
```
IMAP_SERVER=imap.gmail.com
EMAIL_ADDRESS=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
...
```
Note for Gmail Users: You must use an App Password if 2-Step Verification is enabled. See the Configuration Guide for detailed instructions.

Usage

Run the tracker manually:

python Hytrack3.py

Automation (Cron Job)

To run the tracker periodically (e.g., every hour), add a cron job:

crontab -e

Add the following line (adjust paths as necessary):

0 * * * * /path/to/HyTrackV3/.venv/bin/python /path/to/HyTrackV3/Hytrack3.py >> /path/to/HyTrackV3/cron.log 2>&1

Project Structure

HyTrackV3/
├── assets/             # Images and static assets
├── docs/               # Documentation files
├── Hytrack3.py         # Main application script
├── requirements.txt    # Python dependencies
├── sample.env.txt      # Template for environment variables
├── README.md           # Project documentation
└── hytrack3.db         # SQLite database (created on first run)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

Distributed under the GPL-3.0 License. See LICENSE for more information.