Skip to content
nicx17Public

About

An automated logistics intelligence tracker that ingests emails, parses Blue Dart and Delhivery waybills, and tracks their delivery status using Selenium and BeautifulSoup.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

Repository files navigation

HyTrackV3

Status GitHub Release Python Selenium License

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:

Each update shows the current status, the route and expected delivery date, and a journey log of the latest scans, styled to match nickcardoso.com.

In-transit update with journey log Delivered update
Update on a phone

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 (with a plain-text fallback) email updates whenever a shipment status changes, including a journey log of recent scans. A notification that fails to send is retried on the next run.
  • Careful Ingestion: Reads waybills from the subject and body, skips numbers that look like phone numbers, ignores bounces, auto-replies and mail that fails SPF/DKIM/DMARC, and caps waybills per email and per sender.
  • Self-Maintaining: Stops tracking waybills that never resolve or stop changing, rotates its log file, and skips a run if the previous one is still going.

Prerequisites

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

  • Python 3.10+
  • Google Chrome (latest stable version)
  • Git

Installation

  1. Clone the repository:

    git clone https://github.com/nicx17/HyTrackV3.git
    cd HyTrackV3
  2. Set up a virtual environment:

    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  3. 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.

  1. Copy the sample configuration:

    cp sample.env.txt .env
  2. 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.

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

License

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

About

An automated logistics intelligence tracker that ingests emails, parses Blue Dart and Delhivery waybills, and tracks their delivery status using Selenium and BeautifulSoup.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages