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.

17TRACK Home Assistant

The 17TRACK Home Assistant integration logs in to a free 17track.net account and mirrors every tracking number on it as a sensor. It covers about 3,200 carriers and polls the 17TRACK cloud every 15 minutes. Summary sensors count packages by status, and per-package entities carry the carrier, origin, destination, and last update. Setup takes a few minutes in Settings, with one password length limit explained below.

Seventeentrack

Seventeentrack is the integration’s internal name, so you see it in service calls and in the docs URL instead of “17TRACK”. The three actions are seventeentrack.get_packages, seventeentrack.add_package, and seventeentrack.archive_package. Each one needs the config_entry_id of your integration, which you find on its options page. The seventeentrack docs page on home-assistant.io is the full reference for all three.

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. 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, which is fast enough for a typical household without hammering the API.

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 shows 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 card that collapses itself when a count drops to zero wraps the whole section and hides it when nothing is in transit.

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. Coverage varies a lot between carriers and shipping classes.

Delivery automations

The dashboard is for checking in. Automations react as packages move through the system, and 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 I can read it from the lock screen without opening the app.

The out-for-delivery alert is the one everyone 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 without writing a file to disk.

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. If you haven’t set up Frigate yet, our guide to running on-premise camera detection with a Coral accelerator 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.

The last piece 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. Getting the regexes right takes some trial and error, and after that no tracking number needs typing.

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

In a multi-person household, a tracking setup that buzzes four phones every 15 minutes is worse than no setup at all.

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.

For quiet hours, 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.

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. One tap replaces 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.

With the automations, dashboard, and ingestion wired together, packages show up in the dashboard when they ship and you get a single alert when one is at your door. The porch camera captures every drop-off, and old deliveries archive themselves after two days.