Parcel tracking (17TRACK, DHL) smart home integration, free and open source
Track parcels from every carrier worldwide with 17TRACK and the official DHL API.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Track your parcels from every carrier in Gladys, at home and abroad: UPS, FedEx, USPS, DHL, Deutsche Post, GLS, DPD, Royal Mail, the postal services of the whole world, the parcels shipped from China (Cainiao, YunExpress…) and more than 3,000 others, like the parcel tracking apps.
Developed without a 17TRACK or DHL account: feedback welcome on the Gladys forum. The answers of both APIs were simulated from their documentation.
For your La Poste, Colissimo and Chronopost parcels, prefer the
La Poste integration (guim31/gladys-laposte), which reads the official
La Poste API.
This integration is not affiliated with the carriers or 17TRACK.
What it does
- You add a parcel by its tracking number, and a name if you like ("Running shoes"), from the configuration or from a scene. The carrier is recognized from the number.
- Two sources, each turned on by its free key:
- DHL, through its official API, for the DHL and Deutsche Post numbers;
- 17TRACK for everything else: it recognizes the carrier and gathers the events of every carrier along the way (China Post then La Poste, for example) into one timeline.
- Each parcel becomes a device in Gladys: status, last event, place, date, carrier and expected delivery date.
- The status is the same for every carrier: registered, in transit, out for delivery, to pick up, problem, delivered. The carrier's original text (often English or German) stays visible as a detail.
- The "My parcels" widget lists your parcels, the ones waiting for you first.
- Three scene triggers (out for delivery, delivered, a parcel needs you) and three scene actions (track a parcel, stop tracking a parcel, read my parcels).
- A delivered parcel is archived by itself after 7 days (adjustable).
Requirements
- Gladys 5.1.0 or later, with Internet access.
- At least one of the two keys, both free:
- 17TRACK (every carrier): create an account on api.17track.net, then copy the key in Settings → Security → Access key. If you turn on the IP whitelist, add your router's public address to it, otherwise 17TRACK refuses the key.
- DHL (DHL and Deutsche Post parcels): create an account on developer.dhl.com, create an app with the Shipment Tracking - Unified API, and copy its API Key (not the secret).
- Both together give the best result: DHL reads its own parcels, 17TRACK does the rest.
Configuration
Install the integration from Integrations → Install from GitHub with the address
https://github.com/guim31/gladys-colis, then open its configuration.
| Setting | Default | Role |
|---|---|---|
| 17TRACK API key | (empty) | Your 17TRACK key. It never appears in the logs. |
| DHL API key | (empty) | The API Key of your DHL app. It never appears in the logs. |
| Keep delivered parcels | 7 days | A delivered parcel is archived after this time (1 to 30 days). |
| Language | French | Language of the statuses, of the feature names of new devices and of messages. |
The configuration actions:
- Track a parcel: the tracking number (spaces, dots and dashes are fine) and an optional name. The parcel is read at once. The same number with another name renames the parcel. Then create its device in the Discover tab.
- Stop tracking a parcel: by its name or number. Its device stays in Gladys: delete it from the device page.
- Read the parcels now: reads every parcel on the way at once, checks the keys, and shows the 17TRACK quota left and the DHL requests used today.
Quotas and reading pace
The integration reads each parcel at a pace that follows its status, never beyond the free plans:
| Status | Reading |
|---|---|
| Out for delivery | every 15 minutes |
| In transit, problem | every hour |
| To pick up, not found yet | every 2 hours |
| Registered | every 3 hours |
| Delivered | never again |
- DHL: the free plan allows 250 requests a day and one every 5 seconds. The integration stops at 240 a day, spaces its requests by 5 seconds, and slows down when many DHL parcels share the day (20 DHL parcels in transit: a little over 2 hours between two readings). Once the 240 requests are made, the DHL parcels wait for the next day (midnight UTC).
- 17TRACK: only the registration of a new number spends quota, once per parcel; the readings after it are free and batched (40 numbers per request, 3 requests per second at most). The free plan gives a limited number of registrations: according to the 17TRACK help center, 200 numbers granted once to the accounts opened since January 2026 (100 a month on older accounts). Check your 17TRACK dashboard: the "Read the parcels now" action shows what is left. A parcel archived then tracked again spends nothing.
- 17TRACK reads the carriers on its side: right after the registration, the first events can take a few minutes.
The devices
One device per parcel, named after the parcel ("Running shoes (1Z999AA10123456784)"), to create in the Discover tab. Its features, all read only:
| Feature | Content |
|---|---|
| Status | Not read yet, Not found yet, Registered, In transit, Out for delivery, To pick up, Problem, Delivered |
| Last event | The carrier's text, as it sends it |
| Place | The place of the last event |
| Event date | Date and time of the last event |
| Carrier | UPS, DHL Paket, La Poste, Cainiao… |
| Expected delivery | The date the carrier announces, if any |
A dash (—) stands for what the carrier does not say. The feature names take the language chosen when the device is created.
When the parcel is archived, it leaves the Discover tab but its device stays in Gladys with its last values: delete it when you no longer need it (Gladys does not let an integration delete a device).
The widget
Add the My parcels widget to your dashboard. It lists up to 8 parcels: first the ones out for delivery, to pick up or with a problem, then the others. Each line gives the name, the last event and its date, and a colored status badge. A tap opens the details: carrier, number, expected delivery date, history of the events and a link to the tracking page. A line at the bottom reports a refused key, a quota reached or a service that does not answer.
Scene triggers
| Trigger | When |
|---|---|
| A parcel is out for delivery | The courier has the parcel for today's round. |
| A parcel is delivered | The carrier reports the parcel delivered (not for a parcel already delivered when added). |
| A parcel needs you | The parcel waits at a pickup point or a locker, or has a problem (failed delivery, customs, delay, return). |
Each trigger can be limited to one parcel (empty: every parcel). "A parcel needs you" can also be limited to one reason: "To pick up" or "Problem". The information passed to the scene actions: parcel name, number, carrier, status, last event, place and tracking page (and the reason).
A trigger fires once per status change: a restart of Gladys or of the integration does not fire it again.
Scene actions
- Track a parcel: adds a parcel. The number field also takes a whole text, such as the subject of an order confirmation mail: the first tracking number in it is used. Results: number, name, status, carrier, and "New parcel" (1 or 0).
- Stop tracking a parcel: by its name or number. Result "Removed": 1, or 0 when no parcel matches.
- Read my parcels: a sentence such as "You have 2 parcels on the way: Shoes, out for delivery today; Book, waiting to be picked up.", and the numbers of parcels on the way, out for delivery, to pick up and with a problem.
Scene examples
- The courier is coming: trigger "A parcel is out for delivery", action "Send a message": "The parcel {parcel name} arrives today ({carrier})". Add a presence condition to warn only when nobody is home.
- Remember the pickup point: trigger "A parcel needs you", reason "To pick up", then a message "{parcel name} is waiting for you: {last event}".
- Morning summary: time trigger at 8 am, action "Read my parcels", then "Continue only if" parcels on the way
0, and a voice announcement of the sentence.
- Automatic tracking from your mails: with a mail integration, pass the subject of the shipping mail to the "Track a parcel" action.
Troubleshooting
- "17TRACK refuses the API key": check the key (Settings → Security). If the IP whitelist is on at 17TRACK, add your router's public address, or turn it off.
- "DHL refuses the API key": copy the app's API Key (not the "API Secret") and check the app has the "Shipment Tracking - Unified" API.
- A parcel stays "Not found yet": the sender created the label but has not handed the parcel over yet, or 17TRACK does not recognize the carrier. The integration tries again, then archives the number after 30 days.
- "17TRACK quota reached": no free registration is left on your account; the parcels already tracked are still read. Remove the parcels you no longer need.
- "DHL daily allowance used": the 240 requests of the day are made; the DHL parcels resume at midnight UTC.
- The device shows nothing: create it in the Discover tab, then wait for the next reading or use "Read the parcels now".
- For more details, set the log level to
debug(variableLOG_LEVEL=debug): every reading is described there, never with the keys.
Limits
- Developed without a 17TRACK or DHL account: the answers were simulated from the documentation of both APIs. The first real feedback is expected.
- DHL's "Out for delivery" and "To pick up" statuses are inferred from the text of the event (English or German): a new wording can stay classified "In transit".
- The texts of the events stay in the carrier's language.
- The triggers follow the reading pace: "out for delivery" can come up to an hour after the courier took the parcel.
- 40 tracked parcels at most.
- UPS, FedEx and USPS have official APIs too, but they ask for a business account and an OAuth authentication: these carriers go through 17TRACK.
- The carriers that ask for a postal code or a phone number to track a parcel are not supported.
Configuration settings
These are the settings Parcel tracking (17TRACK, DHL) asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your free API keys | section | No | Enter a 17TRACK key (every carrier, detected from the number), a DHL key, or both. Then use "Track a parcel" and create the devices in the Discover tab. For La Poste, prefer the La Poste integration. Not affiliated with the carriers or 17TRACK. |
| 17TRACK API key | secret | No | Settings → Security → Access key of your free account on api.17track.net. Every carrier. |
| DHL API key | secret | No | The API Key of a "Shipment Tracking - Unified" app on developer.dhl.com (free, 250 requests a day). |
| Keep delivered parcels | select | No | A delivered parcel is archived after this time: it leaves the list, the widget and the Discover tab. |
| Language | select | No | Language of the statuses, of the feature names of the new devices and of the messages. The carriers' texts stay as they send them. |
How to install Parcel tracking (17TRACK, DHL) in Gladys
- In Gladys, open Integrations: Parcel tracking (17TRACK, DHL) appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-colis:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-colis.
Parcel tracking (17TRACK, DHL) requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Parcel tracking (17TRACK, DHL) is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation