Tracking Numbers Integration

Gets emails from IMAP and parses out any tracking numbers. Goes well with the tracking-number-card for lovelace!

Supported Emails

• Adafruit
• Adam & Eve
• Amazon
• Amazon DE
• Ali Express
• B&H Photo
• Bespoke Post
• Best Buy
• Canada Post
• Chewy
• Costway
• Cradlewise
• DHL
• Dollar Shave Club
• DSW
• eBay
• Etsy
• FedEx
• Gamestop
• Georgia Power
• Giri Designs
• Google Express
• Groupon
• Guitar Center
• Home Depot
• House of Noa
• Inovelli
• Litter Robot
• Loog Guitars
• Lowes
• Manta Sleep
• Mixbook
• Moen
• Monoprice
• Navimow
• NewEgg
• Nintendo
• Nuleaf
• Paypal
• Pledge Box
• Philips Hue
• Prusa
• Reolink
• Rockauto
• SmartWings
• SparkFun
• Steiff
• Stride Rite
• Sylvane
• Sony
• Swiss Post
• SwitchBot
• Target
• TCGplayer
• Thriftbooks
• Timeless
• The Smartest House
• Ubiquiti
• UPS
• USPS
• Walmart
• Wayfair
• Western Digital
• Wyze
• Zazzle

If you want support for tracking, forward me the email (ljmerza at gmail) and open an issue.

---

Options

Name	Type	Requirement	default Description
email	string	Required	email address
password	string	Required	email password
imap_server	string	Optional	imap.gmail.com IMAP server address>
imap_port	number	Optional	993 IMAP port
folder	string	Optional	INBOX Which folder to pull emails from
ssl	boolean	Optional	true enable or disable SSL when using IMAP
days_old	number	Optional	30 how many days of emails to retrieve
trackingmore_api_key	string	Optional	Enables live delivery status via TrackingMore. Leave blank to disable.

Live Delivery Status (optional)

By default the integration only extracts tracking numbers from email. You can optionally enrich packages shipped by recognized carriers (USPS, UPS, FedEx, DHL) with live delivery status — status, delivery_status, estimated_delivery, and status_updated attributes. Retailer order numbers (Amazon, Chewy, etc.) are skipped. Configure it under Configure → Live status provider; with the provider set to None (the default) behavior is unchanged.

Two providers are available:

• Carrier-direct (free): query each carrier's own free developer API. Set the provider to Carrier-direct and enter credentials under Configure → Carrier API credentials for whichever carriers you use (leave the rest blank). Each carrier needs a free developer account: USPS (OAuth key + secret), UPS (client ID + secret), FedEx (API key + secret), DHL (one API key). Zero cost; delivered packages aren't re-queried and calls are rate-limited per carrier.
• TrackingMore (paid credits): supply a TrackingMore API key. One credit per tracking number registered; each number is registered once and re-read for free afterward, with new registrations capped per cycle.

Delivery Dates from Email

No setup needed: the integration also reads delivery dates out of the shipping emails themselves ("Arriving Thursday", "Estimated Delivery: Oct 14", "Expected Delivery by Tuesday, September 22", "Delivered today") and adds them to each package:

• estimated_delivery (YYYY-MM-DD) — with estimated_delivery_source set to email. When a live status provider also returns a date, the live date wins and the source becomes carrier.
• delivered_date (YYYY-MM-DD) — set when a "Delivered" email is seen.

Relative wording ("today", "Thursday", "in 1-3 days") is resolved against the email's send date in your Home Assistant timezone; for a date range the later end is used. When several emails mention the same package, the newest email's date wins. Vague windows like "within 7-10 business days" are ignored.

To check what the parsers extract from saved emails without running Home Assistant, put .eml files or JSON fixtures in .data/ and run python3 scripts/run_parsers.py (see the script's docstring).

Manual Tracking Numbers

If you have a package that is not captured via email, call the tracking_numbers.add_manual_tracking_number service (or use the lovelace card's add button) to save it alongside your parsed deliveries. Provide the target sensor's entity_id, the tracking_number, and optionally a link, carrier, origin, or status string. Use tracking_numbers.remove_tracking_number to delete a manual entry or hide a tracking number that was parsed from email.