bpost Parcel Tracker
📦 Part of ha-parcel-integrations, a family of package-tracking integrations for Home Assistant that all publish the same parcel format, statuses and events, so they plug into cross-carrier automations and the optional Parcel Aggregator. Browse the other carriers on the website.
💬 Questions or feedback? Join the discussion on the Home Assistant community.
A custom Home Assistant integration that tracks your bpost (Belgium) parcels. Choose either tracking codes with a delivery postal code, or your My bpost account inbox.
Contents
Features
- Track any number of bpost parcels by tracking code — no account needed, one hub per delivery postal code
- My bpost account inbox: sign in once and every parcel in it is imported and kept up to date, incoming and outgoing; only rotating tokens are stored, never your password
- Per-parcel sensor with the canonical status (
out_for_delivery / delivered / unknown / …), the carrier's own status text, the expected delivery window (when bpost reports one) and a tracking deep-link
- Summary sensors: incoming parcels, next delivery, recently delivered parcels,
plus outgoing and delivered-outgoing parcels for account entries
- Mail Ahead letters for account entries: a letters sensor plus an image entity
with the scan of each envelope bpost announces
- Read-only Deliveries calendar with the expected delivery windows
bpost.track_parcel / bpost.untrack_parcel services, so a dashboard button can add a parcel- Events + device triggers for no-code automations, including outgoing status
changes and delivery for account entries
- Opt-in per-parcel status history
- Manual refresh button and a diagnostic last-update sensor
Requirements
- Home Assistant 2025.12 or newer
- For tracking codes: the delivery postal code (asked once, at setup) and a
parcel's tracking code (from the shipping confirmation e-mail or the
missed-delivery card) — bpost's public tracker requires both to look up a
parcel, no account needed
- For the account route: the e-mail address and password of your My bpost
account. Home Assistant asks you to sign in again if bpost stops accepting
the stored tokens.
- For letters: Mail Ahead switched on for your address in the My bpost app.
Without it the letters sensor simply stays at 0.
Installation
HACS (recommended)
- Open HACS and search for bpost.
- Install it.
- Restart Home Assistant if HACS asks you to.
Or click the button below to open it directly in HACS:
Manual
Copy custom_components/bpost into your config/custom_components/ folder and restart Home Assistant.
Configuration
Or set it up by hand: add the integration via Settings → Devices & Services → Add Integration → bpost, then choose Tracking codes or Account (automatic import). Both kinds can be set up side by side.
Tracking codes ask for the delivery postal code, which becomes the hub default for every parcel you add to it. Add parcels via the integration's Configure dialog, the bpost.track_parcel service, or a dashboard button — just the tracking code; the postal code comes from the hub.
Account (automatic import) asks for your My bpost e-mail address and password once, then keeps its parcel list in step with your inbox — nothing to add by hand. Only the rotating tokens bpost hands back are stored; your password is not.
Options
Open Configure on the integration entry:
| Menu item | Description |
|---|
| Parcels | Edit the full list of tracked codes at once (add or remove any number, then save). No live validation — a tracking code is confirmed on the next poll. Tracking-code entries only; an account entry has no list to edit. |
| Settings | Delivered-parcel retention (filter by / amount) and the opt-in status-history attribute. |
Changes apply immediately, no restart.
Polling isn't one of these settings: the integration polls on a dynamic,
status-driven schedule with nothing to configure.
Dynamic polling
Polling isn't a setting here — the integration adjusts its own cadence to
what your tracked parcels are actually doing:
- Quiet hours — no polling between 00:00–06:00 local time, aside from one
catch-up check at each end of that window (around midnight and around 6
AM), so an overnight update is never missed.
- Hot (every 15 minutes) — while any tracked parcel is out for delivery
today, starting an hour before its delivery window opens (or immediately if
no window is known yet — for a tracking-code hub this is the fallback that
fires in practice, since bpost's public tracker has never reported a
delivery window; the account route can report a real one from your My
bpost inbox).
- Normal (every 45 minutes) — for anything else still on its way.
- Fully paused (tracking-code hubs) — once every tracked parcel in that
hub has been delivered, or nothing is tracked in it, that hub's polling
stops until you add a parcel back (adding one always triggers an immediate
check, regardless of the pause).
- Never fully stops (account entries) — with nothing hot or in transit,
an account entry keeps polling at the normal cadence, since that's also how
a new parcel in your inbox gets discovered.
- A small, fixed per-hub offset is added on top, so not every bpost hub out
there polls at exactly the same second.
Removal
Standard HA removal applies: Settings → Devices & Services → bpost → ⋮ → Delete. Nothing is stored on bpost's side.
Sensors
| Entity | Description |
|---|
sensor.bpost_incoming_parcels | Number of active tracked parcels, full list under the parcels attribute |
sensor.bpost_parcel_<barcode> | One per tracked parcel; state is the canonical status, attributes carry the full normalised parcel |
sensor.bpost_next_delivery | Earliest expected delivery moment across all active parcels |
sensor.bpost_en_route_to_pickup_point | Incoming parcels on their way to a pickup point, such as a bbox locker, that have not arrived yet |
sensor.bpost_awaiting_pickup | Incoming parcels that are ready to collect at a pickup point |
sensor.bpost_delivered_parcels | Recently delivered parcels (see the retention option) |
sensor.bpost_outgoing_parcels | Active sender parcels; account entries only |
sensor.bpost_outgoing_delivered_parcels | Recently delivered sender parcels; account entries only |
sensor.bpost_letters | Mail Ahead letters from the last 30 days, listed under the letters attribute (id, date, planned_delivery, sender, and bpost's untouched record as raw); account entries only |
image.bpost_letter_<sender or date> | One per letter: the scan of the envelope, fetched by Home Assistant and served through its own image proxy; account entries only. The entity_id follows your language (brief in Dutch, courrier in French), so match letters on the id attribute — see notify_when_letter_arrives.yaml |
sensor.bpost_last_successful_update | Diagnostic: when bpost was last polled successfully |
A delivered parcel moves from its per-parcel sensor to the delivered sensor automatically.
Parcel status reference
The status field is the carrier-agnostic enum shared by the whole integration family. Both the public tracker and the account inbox report the same bpost status vocabulary, and it is mapped in full — preparation, transit, out-for-delivery, ready-to-collect, delivered, return and customs states. An unseen delivery method is still matched on its family prefix, and any code that stays unmapped is reported as unknown with a one-shot log warning asking you to report it:
| Status | Meaning |
|---|
registered, in_transit, out_for_delivery | Announced, moving through the network, or with the courier today |
at_pickup_point, returning, problem | Ready to collect, returning to sender, or a delivery exception |
delivered | Delivered — including to a Kariboo pickup point, which is a delivery method, not a still-waiting state |
unknown | Not yet found, or a status code we have not mapped yet |
The carrier's own status code is always available as raw_status.
Events
The integration fires these on the event bus (also available as device triggers on the bpost device):
| Event | When |
|---|
bpost_parcel_registered | A new parcel appears in the active list |
bpost_parcel_status_changed | A parcel's canonical status changes (old_status / new_status in the payload), except the final hop to delivered |
bpost_parcel_delivered | A parcel is delivered |
bpost_parcel_delivery_time_changed | The expected delivery window changes |
bpost_outgoing_parcel_status_changed | An account sender parcel's canonical status changes (old_status / new_status) |
bpost_outgoing_parcel_delivered | An account sender parcel is delivered or returned to its sender |
bpost_letter_announced | A new Mail Ahead letter appears on an account entry |
Every parcel payload is the full normalised parcel plus the hub's device_id; a letter payload is the letter as the letters sensor lists it, plus carrier and device_id. Events are suppressed on the first refresh after start-up.
Services
| Service | Fields | Description |
|---|
bpost.track_parcel | tracking_code, postal_code (optional, to pick a hub when more than one is set up) | Start tracking a parcel |
bpost.untrack_parcel | tracking_code | Stop tracking a parcel |
Both act on tracking-code entries; account entries follow your My bpost inbox and are never edited by hand.
Examples
Ready-to-paste automations and dashboard snippets live in examples/, including tracking a new parcel straight from a dashboard.
Community Lovelace cards
Third-party cards that work with this integration's sensors:
Debugging
logger:
logs:
custom_components.bpost: debug
Troubleshooting
- A parcel shows
unknown — either bpost has no record for that tracking code + the hub's postal code yet (it will pick up automatically once scanned), or bpost is reporting a status code that is not in the mapped vocabulary yet — the log says which one.
- A log line says "Unrecognised bpost … status" — please open an issue with the logged line so the mapping can be extended.
- "bpost needs reauthentication" — bpost stopped accepting the stored
tokens for an account entry. Open the repair Home Assistant offers and enter
that account's password again; nothing else is lost.
- A parcel never resolves — double-check the tracking code, and that the hub's postal code matches the delivery address; bpost's public tracker requires an exact match on both. A parcel addressed to a different postcode needs its own hub.
Related integrations
This integration is part of ha-parcel-integrations — a family of
parcel-carrier integrations that all publish the same canonical parcel format,
statuses and events.
Disclaimer
This is an independent, community-built project. It is not affiliated with, endorsed by, sponsored by, or supported by bpost, Home Assistant, or any other third party referenced in this project. Please don't contact bpost for support with this integration.
All third-party trademarks, trade names, product names, logos, and other brand assets are the property of their respective owners. References to them are solely to identify the relevant carrier or service and do not imply affiliation, sponsorship, or endorsement. Nothing in this project grants or implies any licence or right to use third-party brand assets.
This integration may rely on public, unofficial, or undocumented carrier interfaces, accessed with your own account or API key where required. These may change or be withdrawn without notice and may be subject to bpost's terms. Data is sent only to bpost's own services or those of its group; this project operates no servers of its own. You are responsible for ensuring that your use complies with applicable law and those terms. Use is at your own risk; see the licence for warranty limitations.
This integration uses the same public tracking endpoint as the bpost consumer website.
Contributing
Pull requests and issues are welcome. Please open an issue before
submitting a large change.
License
MIT
