Track Package Deliveries in Home Assistant with 17TRACK and Automations

Connect a free 17track.net account to Home Assistant and you can pull tracking data from 3,200+ carriers into one place. From there, automations ping your phone, fire the porch camera, and toggle outdoor lights as boxes move through the system. Below is a working blueprint for the whole flow, from setup to multi-user alert tuning.

Setting Up the 17TRACK Integration

17track.net is a tracking aggregator. It pulls status updates from USPS, UPS, FedEx, DHL, Royal Mail, China Post, YunExpress, and roughly 3,200 other carriers across 220 countries. Once you add tracking numbers to your 17track account (by hand, through the mobile app, or via email forwarding), the Home Assistant integration mirrors them as sensor entities. You can then display them and build automations on top.

Before adding the integration, create a free account at 17track.net and log in once to confirm the credentials. One footgun is worth knowing about: your 17track password must not exceed 16 characters. The website will silently let you set a longer one. However, the API that Home Assistant uses rejects anything beyond 16, and you’ll be stuck in a login loop. If you hit auth errors, this is almost always the cause. Reset the password to 16 characters or fewer and try again.

With the account ready, add the integration in Home Assistant. Go to Settings -> Devices & services -> Add Integration -> 17TRACK, then enter your email and password. The integration is marked Cloud Polling and refreshes every 15 minutes by default. That’s the sweet spot between API politeness and responsiveness for a typical household.

Once connected, the integration creates two groups of entities. The first is a set of summary sensors that count packages by state. They cover the seven possible statuses: Not Found, In Transit, Expired, Ready to be Picked Up, Undelivered, Delivered, and Returned. The second group is per-package entities. Each exposes attributes like carrier, origin, destination, tracking number, last update, and status. The integration also ships three service calls:

All three need the config_entry_id of your integration instance. You can grab it from the integration’s options page. These service calls replace the older per-state sensor pattern, so newer dashboards and automations should be built around them. The full reference lives on the official 17TRACK integration page .

Building a Package Tracking Dashboard

A good package dashboard answers two questions at a glance. How many boxes are in flight, and which one is closest to arriving? I build mine around a trigger-based template sensor. It calls seventeentrack.get_packages on a 15-minute schedule, stores the full list in an attribute, and renders the data through a stack of Lovelace cards.

The template sensor is the backbone:

template:
  - trigger:
      - platform: time_pattern
        minutes: "/15"
      - platform: homeassistant
        event: start
    action:
      - service: seventeentrack.get_packages
        data:
          config_entry_id: <YOUR_CONFIG_ENTRY_ID>
          package_state:
            - in_transit
            - ready_to_be_picked_up
        response_variable: packages
    sensor:
      - name: "Active Packages"
        unique_id: active_packages_count
        state: "{{ packages.packages | length }}"
        attributes:
          items: "{{ packages.packages }}"

With that sensor in place, a Mushroom template card gives you a clean headline tile. Set the primary text to {{ states('sensor.active_packages') }} packages in transit. Use mdi:package-variant-closed as the icon, and set the tap action to open a detail subview. A conditional card wraps the whole section so it hides when the count is zero. That keeps the main dashboard tidy.

For the detail view, a Markdown card iterates over the items attribute. It renders a table with the friendly name, carrier, last known status, and last update time. If you prefer a more visual layout, auto-entities can build one row per package. Use templates to paint the status chip: green for delivered, blue for in transit, yellow for out for delivery, and red for alerts. On mobile, wrap the whole thing in a vertical stack so each section reflows on narrow screens. The same dashboard then works on a wall-mounted tablet and a phone, with no separate layouts.

Some carriers include geolocation data in their tracking events. FedEx and DHL sometimes do; USPS almost never does. When the data is there, you can plot the coords on a Map card. Use a template sensor that pulls latitude and longitude from the package attributes. Expect this to be hit or miss. Coverage varies a lot between carriers and shipping classes.

Delivery Automations

The dashboard is handy for checking in, but automations do the heavy lifting as packages move through the system. Five of them cover the full lifecycle for most households.

When the sensor.active_packages count climbs, something new has entered the system. A numeric state trigger with above: 0 catches it. Pair it with a value template that compares the current attribute list against a stored snapshot. The match fires a low-priority mobile alert with the carrier and tracking number. I title mine “New shipment detected” so it’s clear at a glance, no app needed.

The out-for-delivery alert is the one everyone actually wants. Trigger on a seventeentrack.get_packages response that contains a package with status out_for_delivery. Carriers expose this through the per-package status attribute. Then fire a high-priority alert to every household member. If you use the Home Assistant Companion app for iOS or Android, set push.interruption-level to time-sensitive. That way, the alert breaks through focus modes and silent hours.

Delivered alerts feel much better when they include a photo. When a package flips to delivered, fire the porch camera snapshot service first. Store the result in a variable, then pass the file path to the notify service. The photo gets embedded in the alert. If you run Frigate or a Reolink doorbell, the snapshot URL can be pulled straight from the camera entity, no disk write needed.

A porch light automation covers evening drops. When a package is out for delivery and the sun is below the horizon, turn the porch light on for two hours. Drivers find the door, the package ends up in the camera frame, and the light turns off before bedtime. The condition is a one-liner: package state plus sun.sun being below_horizon.

For camera recording, check if your platform supports on-demand clips. Frigate does, via the frigate.create_event service; Reolink does, via camera.record. Start a five-minute recording the moment a package flips to delivered. You end up with a saved video of every drop-off, with no need to babysit the live feed. If you haven’t set up Frigate yet, the guide to local AI security cameras with Frigate and a Coral TPU walks through the full install.

Households with a smart lock can add a sixth automation. When a package is out for delivery and you’re away from home, make a temporary guest code and text it to a trusted neighbor. Home Assistant’s Z-Wave lock integration lets you add and revoke user codes from code. The whole flow fits in a single script with a trigger, an action, and a notify call.

One last piece worth wiring up is a nightly summary at 8 PM. Call seventeentrack.get_packages with package_state: [delivered, in_transit]. Then build a one-line recap like “2 delivered today, 3 still in transit”. For people who only want the big picture, this swaps the constant stream of per-package updates for a single evening check-in.

Automatic Tracking Number Ingestion

Pasting tracking numbers into the 17track app by hand every time you order something gets old fast. The easiest fix is 17track’s built-in email forwarding. In your account settings, 17track gives you a unique forwarding address. Any shipping email you forward to it gets parsed for tracking numbers and added to your account on its own. Set up a forwarding rule in Gmail, Outlook, or Fastmail for messages matching “shipped”, “tracking number”, or “on its way”, and you’re done. The numbers show up in Home Assistant within 15 minutes.

For a fully local setup, the IMAP integration in Home Assistant can watch a mailbox. It fires an imap_content event whenever a new message matches a search term. Use the IMAP custom event data template to run the body through a regex that pulls tracking numbers. Amazon’s are 12 digits prefixed with TBA, UPS starts with 1Z, and FedEx uses 12- or 15-digit numerics. Then call seventeentrack.add_package with the result. The regex work is fiddly, but the payoff is zero-touch tracking.

If you’d rather not write parsers, two community add-ons cover this ground. Mail and Packages by moralmunky picks up alerts from Amazon, USPS Informed Delivery, UPS, FedEx, and DHL. ha-email-sensor by ljmerza parses tracking numbers from 40+ providers. Both can feed their output into the 17track add_package service through a simple automation.

Finally, schedule an archive automation. It should call seventeentrack.archive_package for any package that’s been in the delivered state for 48 hours. This keeps your sensor list short and stops old deliveries from cluttering dashboard queries.

Notification Tuning and Multi-User Setup

A tracking setup that buzzes four phones every 15 minutes is worse than no setup at all. A few tricks keep the noise down in a multi-person household.

Debouncing is the first thing to add. Use a for clause on your state triggers so a brief flip doesn’t fire an alert. Compare the new state against the previous one in the automation condition. For trigger-based template sensors, store a snapshot of tracking numbers in an input_text helper. Only notify when a new number appears that wasn’t there on the previous refresh. This alone kills most of the duplicate buzzes from the 15-minute polling cycle. For routing logic that outgrows native automations, AppDaemon’s Python-based automation engine makes state machines and cross-package checks much easier to manage.

Routing packages to the person who ordered them takes a bit of bookkeeping. 17track does not expose a “recipient” field on its own. You can fake it by adding a tag to the package’s friendly name (for example, Alex-Headphones or Sam-RAM-kit). An automation template parses the prefix and routes the alert to that person’s phone only. For Amazon orders, check the order history page and set the friendly name at ingestion time, so nobody has to fix it later.

Quiet hours are worth setting up once and forgetting about. Wrap the whole alert block in a condition. If the current time is between 10 PM and 7 AM, write the event to an input_text buffer instead of sending a push. At 7:05 AM, a second automation reads the buffer and sends one morning digest. Your phone stays quiet overnight, but nothing gets lost.

For people who don’t want the full trail, a per-user critical-only mode is a nice touch. Create an input_boolean.alex_critical_only toggle. Gate the in-transit and shipped alerts on it being off. When someone flips the toggle on, they only get out-for-delivery and delivered pings. This is handy for houseguests or family who’d rather not be buzzed every time a box leaves a warehouse in China.

Actionable alerts close the loop on archiving. The Home Assistant Companion app supports action buttons that fire events back to Home Assistant. Add a “Mark received” button to the delivered alert that calls seventeentrack.archive_package for the tracking number. Cleanup happens with one tap, not a manual service call in Developer Tools.

If three packages arrive in the same five-minute window, one grouped alert feels much calmer than three pings in a row. The cleanest pattern is a template sensor that counts recently-changed packages in a sliding window. The alert fires when the window closes and includes all packages as a list.

Once the automations, dashboard, and ingestion are wired together, the whole system gets out of your way. Packages show up in the dashboard when they ship. You get a single alert when something is actually at your door. The porch camera captures every drop-off, and old deliveries archive themselves after two days. For a free service backed by open-source code, the signal-to-noise ratio is hard to beat.