freight-email-parser

name

freight-email-parser

description

Monitor freight broker's email inbox via IMAP or Outlook, classify incoming emails using HuggingFace zero-shot or regex, parse quote requests from shippers, extract carrier communications, send/draft replies, and alert broker via SMS with actionable summaries. Supports exception handling workflows like driver ETA drift alerts when telematics or GPS data indicates delays and the AI should notify the shipper or customer by email. Use when a broker wants email monitoring, gets a quote request, needs to process carrier emails, or wants inbox summaries. Triggered by phrases like "check emails", "pending quotes", "carrier emails", "email inbox", "new emails", "email summary", or driver ETA / delay alerts.

Freight Email Parser

Full email workflow for freight brokers. Monitors inbox, classifies emails, extracts structured data, formats SMS alerts, and can be used as the outbound notification layer for ETA exception workflows. Supports Gmail (IMAP) and Outlook (Microsoft Graph API).

Install

pip3 install flask imap-tools msal transformers torch requests python-dateutil

Quick Start (Demo — no credentials needed)

cd skills/freight-email-parser/scripts
python3 email_pipeline.py --demo

---

Gmail Setup

# Gmail App Password (not regular password)
# 1. Enable 2FA in Google Account
# 2. Security → App Passwords → Generate for Mail
export EMAIL_HOST=imap.gmail.com
export EMAIL_USER=[e-mail]
export EMAIL_PASS=xxxx-xxxx-xxxx-xxxx

Outlook / Office 365 Setup

export OUTLOOK_CLIENT_ID=your-client-id
export OUTLOOK_CLIENT_SECRET=your-client-secret
export OUTLOOK_TENANT_ID=your-tenant-id
export OUTLOOK_USER_EMAIL=[e-mail]

See references/outlook-setup.md for the full Azure app registration walkthrough.

---

Scripts Reference

email_pipeline.py — Main orchestrator (start here)

python3 email_pipeline.py --poll        # Poll inbox and process new emails
python3 email_pipeline.py --demo        # Test with sample emails (no credentials)
python3 email_pipeline.py --reminders   # Check for unanswered quote requests (2h+)
python3 email_pipeline.py --poll --json # JSON output for programmatic use

Pipeline flow: Outlook (if configured) → Gmail IMAP fallback → HF classify → regex fallback → extract → alert → store

Output format:

{
  "new_emails": 2,
  "quote_requests": 1,
  "carrier_comms": 1,
  "reminders_due": 0,
  "alerts": ["📧 QUOTE REQUEST - ABC Manufacturing\n..."],
  "reminder_alerts": []
}

email_monitor.py — Gmail IMAP polling

python3 email_monitor.py --poll
python3 email_monitor.py --poll --json
python3 email_monitor.py --hours 48    # Check last 48 hours

outlook_connector.py — Outlook/Office 365 polling

python3 outlook_connector.py --poll
python3 outlook_connector.py --poll --json

hf_classifier.py — HuggingFace zero-shot classifier

python3 hf_classifier.py --subject "Need quote for freight" --body "Can you move 24 pallets from Dallas to Chicago?"
python3 hf_classifier.py --subject "..." --body "..." --light   # Use lighter model (deberta-v3-small)
python3 hf_classifier.py --subject "..." --body "..." --json

Falls back to regex classifier if transformers not installed.

email_classifier.py — Fast regex classifier (no deps)

python3 email_classifier.py --subject "Need quote" --body "Can you move pallets from Dallas?"

quote_extractor.py — Extract structured fields from quote requests

python3 quote_extractor.py --subject "Quote needed" --body "Need a reefer from LA to NY, pickup Dec 18"
python3 quote_extractor.py --subject "..." --body "..." --json

email_sender.py — Send, reply, or draft emails

# Send a new email
python3 email_sender.py --to [e-mail] --subject "Re: Quote" --body "Our rate is $3,050"

# Use a template
python3 email_sender.py --template quote_ack --to [e-mail] --original-subject "Freight quote request"
python3 email_sender.py --template quote_send --to [e-mail] --rate 3050

# Save as draft (don't send)
python3 email_sender.py --draft --to [e-mail] --subject "Re: Quote" --body "Our rate is $3,050"

Available templates: quote_ack, carrier_ack, quote_send, pod_received

---

Email Categories

Category	Emoji	Description
QUOTE_REQUEST	💰	Shipper asking for a rate quote
CARRIER_COMM	🚛	Carrier responding or sending availability
POD_BOL	📦	Delivery confirmation or bill of lading
INVOICE	📄	Payment requests or bills
RATE_CON	📋	Rate confirmations
GENERAL	📧	Unclear or routine email
SPAM	🗑️	Marketing, unsubscribe, etc.

---

Example SMS Outputs

Quote request:

📧 QUOTE REQUEST - ABC Manufacturing
Lane: Dallas, TX → Chicago, IL | Dry Van
Pickup: Dec 18-20 | 24 pallets
Commodity: General freight

Reply 'quote [amount]' to send | 'skip' to ignore

Carrier email:

🚛 CARRIER - [e-mail]
Subject: Available truck - LA to NY
MC#123456
Rate: $3,200

Reply 'accept', 'counter [amount]', or 'pass'

Driver ETA exception alert:

⏱️ ETA ALERT - Load #12345
Carrier GPS now shows ETA slipped from 3:00 PM to 4:05 PM
Delay: 65 minutes
Reason signal: stopped 42 minutes outside consignee

Reply 'notify customer' to send update
Reply 'draft update' to review email first

Unanswered quote reminder (2h):

⏰ REMINDER: Quote from [e-mail] unanswered for 2.5h
Subject: Need freight quote Dallas to Chicago

---

Auto-Response (Optional)

Configure in ~/.freight-broker/config.json:

{
  "auto_reply_quotes": false,
  "auto_acknowledge_carriers": true,
  "carrier_ack_message": "Received, reviewing. Will respond within 2 hours."
}

---

Cron Setup (Auto-Check Every 2 Minutes)

*/2 * * * * cd /path/to/freight-email-parser/scripts && python3 email_pipeline.py --poll >> /tmp/email-pipeline.log 2>&1

---

State Storage

All state is stored in ~/.freight-broker/:

• processed_uids.json — deduplication registry
• processed_emails.json — full email records with classification
• email_drafts.json — saved drafts
• attachments/ — downloaded email attachments
• models/ — cached HuggingFace models

---

References

• references/imap-setup.md — Gmail, Outlook personal, generic IMAP config
• references/outlook-setup.md — Azure app registration for Office 365