2.5.0

New features

• Return shipments now show up as outgoing parcels — when you send a parcel back to a webshop, it appears in the Outgoing parcels sensor while it is on its way and moves to the new Outgoing delivered parcels sensor once it arrives back at the shop. Both honour the same delivered-parcels window (last N days / N most recent) as the incoming delivered sensor, and the naming matches the other carriers so cross-carrier dashboards need no special-casing.

Credits

Thanks to @jonisnet for researching, building, and testing this on a real installation. 🙏

2.4.0

New features

• Device triggers and a refresh button — build no-code automations that fire when a parcel is registered, changes status, or gets a new expected delivery time, and add a button to poll DHL on demand.
• Deliveries calendar — a per-account calendar entity showing your incoming parcels on their expected delivery day, ready to overlay on your own calendar.
• Diagnostic "Last successful update" sensor — alert on a silently stale integration.

Improvements

• A DHL outage no longer pushes you into re-authentication — server errors and genuine auth failures are now told apart.
• Re-authentication is guarded against accidentally binding the entry to a different DHL account.
• Diagnostics now redact person and shop names.
• Refresh-interval options are translated, and shared wording is aligned with the other carriers.

2.3.0

What's new

• Parcel history (optional) — enable Parcel history in the integration options to add a history attribute to every parcel: the full status timeline (timestamp, status, and the original DHL event code), capped to the most recent 20 events. Off by default, and kept out of the long-term recorder database.

2.2.0

What's new

• Delivery-time updates as an event — the coordinator now fires dhl_nl_parcel_delivery_time_changed when DHL revises a known parcel's expected delivery window (planned_from or planned_to) to a value that differs from the previous one. Wire it up with the new examples/automations/notify_when_delivery_time_changes.yaml to get a push notification the moment the ETA shifts.

2.1.0

What's new

• Configurable refresh interval — the options flow now lets you pick how often the integration checks DHL: 15 / 30 / 60 / 120 / 240 minutes (default 30). A slower cadence is gentler on DHL's consumer API. Changes take effect immediately, no Home Assistant restart needed.
• Recipient name on every parcel — every parcel now carries a receiver field with the name the parcel is addressed to. Useful in multi-person households for routing notifications to the right person, e.g. "Alice's parcel is out for delivery". Also exposed as an attribute on the Next delivery sensor.

2.0.0

What's new

• Carrier-agnostic parcel status (ParcelStatus) — every parcel now carries a canonical status value (registered, in_transit, out_for_delivery, at_pickup_point, delivered, returning, problem, unknown). The original DHL string is preserved on the parcel's raw_status attribute.
• Parcel events on the HA event bus — the coordinator fires dhl_nl_parcel_registered when a new barcode appears and dhl_nl_parcel_status_changed when a known barcode's normalised status changes. Both events carry the full normalised parcel payload. Events are suppressed on the very first refresh after start-up.
• Parcels sorted by delivery date — every bucket is now ordered: active incoming and outgoing ascending on planned_from, delivered descending on delivered_at. Parcels without a parseable timestamp always sort to the end.
• Translated UI labels — entity names, unit-of-measurement (parcels → pakketten in Dutch HA) and icons are sourced from strings.json + translations/{en,nl}.json + icons.json. Your HA language drives the labels automatically.
• Cleaner device & friendly names — each DHL account becomes a device named DHL (<your-email>) with entities like DHL (account@example.com) Incoming parcels. Disambiguates multi-account setups out of the box.
• examples/ folder — ready-to-paste automation YAMLs (e.g. new parcel registered, out for delivery, ready at ServicePoint) and dashboard cards (active-parcels grid, summary glance, next-delivery countdown).

⚠️ Breaking changes & how to fix them

1. Friendly names changed

Was (≤ 1.4.x)	Is now (2.0.0)
DHL Incoming Parcels	DHL (account@example.com) Incoming parcels
DHL Parcel <barcode>	DHL (account@example.com) Parcel <barcode>
DHL Next Delivery	DHL (account@example.com) Next delivery
DHL Parcels En Route to ServicePoint	DHL (account@example.com) En route to ServicePoint
DHL Parcels Awaiting Pickup	DHL (account@example.com) Awaiting pickup
DHL Delivered Parcels	DHL (account@example.com) Delivered parcels
DHL Outgoing Parcels	DHL (account@example.com) Outgoing parcels

Entity IDs are preserved for existing installs — Home Assistant remembers them in the entity registry. Templates that reference sensor.dhl_incoming_parcels and similar keep working as-is.

What to fix:

• Lovelace cards and Markdown templates that hard-code the friendly name (e.g. "DHL Incoming Parcels") need to be updated to either the new friendly name pattern or — better — switch to using the entity ID with the friendly_name attribute.
• If you renamed entities or devices in the HA UI, those custom names stick around; you only see the new defaults for fresh installs.

2. Per-parcel sensor state is the normalised enum, not the raw DHL string

Was	Is now
state == "DELIVERED_IN_MAILBOX"	state == "delivered"
state == "OUT_FOR_DELIVERY"	state == "out_for_delivery"
state == "NOTIFICATION_FOR_PARCELSHOP_COLLECTION_HAS_BEEN_SENT"	state == "at_pickup_point"
state == "COLLECTED_AT_PARCELSHOP"	state == "delivered"

What to fix:

• Any automation that triggers on the per-parcel sensor state needs to match the new canonical ParcelStatus value. See the parcel-status reference table in the README for the full mapping.
• The original raw value is still available on the parcel's raw_status attribute; you can keep using that if you prefer.

3. Outgoing summary sensor: shipments attribute → parcels

The outgoing summary sensor's list of shipments now lives on the parcels attribute, matching every other DHL summary sensor.

What to fix:

• If you read state_attr('sensor.dhl_..._outgoing_parcels', 'shipments'), rename shipments to parcels.

4. Custom unit-of-measurement is now translated

The hard-coded parcels unit is replaced by a translated one (parcels in English HA, pakketten in Dutch HA).

What to fix:

• If you have automations matching state_attr(..., 'unit_of_measurement') == 'parcels', account for the Dutch variant too — or compare against the entity ID instead.
• Long-term statistics for the counters may emit a one-time "unit cannot be converted" recorder warning after upgrading on Dutch HA. Open Developer Tools → Statistics, find the sensor and use "Update statistic unit", or ignore the warning until the affected rows roll out of the retention window.

2.0.0b2

What's changed

• Outgoing sensor uses parcels attribute — the outgoing summary sensor's parcel list now lives on the parcels attribute, matching every other DHL summary sensor.

⚠️ Breaking change

• If you read the outgoing sensor's shipments attribute (e.g. state_attr('sensor.dhl_account_outgoing_parcels', 'shipments')), rename it to parcels.

Heads-up

• 2.0.0b1's other breaking changes still apply if you are upgrading from 1.x. See 2.0.0b1 release notes.

2.0.0b1 (beta)

What's new

• Carrier-agnostic parcel status (ParcelStatus) — every parcel now carries a canonical status value (registered, in_transit, out_for_delivery, at_pickup_point, delivered, returning, problem, unknown). The original DHL string is preserved on the parcel's raw_status attribute.
• Parcel events on the HA event bus — the coordinator now fires dhl_nl_parcel_registered when a new barcode appears and dhl_nl_parcel_status_changed when a known barcode's normalised status changes. Both events carry the full normalised parcel payload. Events are suppressed on the very first refresh after start-up.
• examples/ folder — ready-to-paste automation YAMLs (e.g. new parcel registered, out for delivery, ready at ServicePoint) and dashboard cards (active-parcels grid, summary glance, next-delivery countdown).
• Translated UI labels — entity names, unit-of-measurement (parcels → pakketten in Dutch HA) and icons are now sourced from strings.json + translations/{en,nl}.json + icons.json. Your HA language drives the labels automatically.
• Cleaner device & friendly names — each DHL account becomes a device named DHL (<your-email>) with entities like DHL (account@example.com) Incoming parcels. Disambiguates multi-account setups out of the box.

⚠️ Breaking changes & how to fix them

1. Friendly names changed

Was (≤ 1.4.x)	Is now (2.0.0)
DHL Incoming Parcels	DHL (account@example.com) Incoming parcels
DHL Parcel <barcode>	DHL (account@example.com) Parcel <barcode>
DHL Next Delivery	DHL (account@example.com) Next delivery
DHL Parcels En Route to ServicePoint	DHL (account@example.com) En route to ServicePoint
DHL Parcels Awaiting Pickup	DHL (account@example.com) Awaiting pickup
DHL Delivered Parcels	DHL (account@example.com) Delivered parcels
DHL Outgoing Parcels	DHL (account@example.com) Outgoing parcels

Entity IDs are preserved for existing installs — Home Assistant remembers them in the entity registry. Templates that reference sensor.dhl_incoming_parcels and similar keep working as-is.

What to fix:

• Lovelace cards and Markdown templates that hard-code the friendly name (e.g. "DHL Incoming Parcels") need to be updated to either the new friendly name pattern or — better — switch to using the entity ID with the friendly_name attribute.
• If you renamed entities or devices in the HA UI, those custom names stick around; you only see the new defaults for fresh installs.

2. Per-parcel sensor state is the normalised enum, not the raw DHL string

Was	Is now
state == "DELIVERED_IN_MAILBOX"	state == "delivered"
state == "OUT_FOR_DELIVERY"	state == "out_for_delivery"
state == "NOTIFICATION_FOR_PARCELSHOP_COLLECTION_HAS_BEEN_SENT"	state == "at_pickup_point"
state == "COLLECTED_AT_PARCELSHOP"	state == "delivered"

What to fix:

• Any automation that triggers on the per-parcel sensor state needs to match the new canonical ParcelStatus value. See the parcel status reference table in the README for the full mapping.
• The original raw value is still available on the parcel's raw_status attribute; you can keep using that if you prefer.

3. Custom unit-of-measurement is now translated

The hard-coded parcels unit is replaced by a translated one (parcels in English HA, pakketten in Dutch HA).

What to fix:

• If you have automations matching state_attr(..., 'unit_of_measurement') == 'parcels', account for the Dutch variant too — or compare against the entity ID instead.
• Long-term statistics for the counters may emit a one-time "unit cannot be converted" recorder warning after upgrading on Dutch HA. Open Developer Tools → Statistics, find the sensor and use "Update statistic unit", or ignore the warning until the affected rows roll out of the retention window.

4. Minimum Home Assistant version is 2024.7.0

Older HA instances will refuse to load the integration because of the runtime_data and type ConfigEntry[...] features.

How to test the beta

1. Open HACS → Integrations → DHL NL → settings ⋮ → enable
   Show beta versions.
2. Update to 2.0.0b1.
3. Reload Home Assistant.
4. Run your automations; please report regressions via
   GitHub Issues so
   we can fix them before tagging the stable 2.0.0.

1.4.2

What's new

• Diagnostics download — head to Settings → Devices & Services → DHL NL → ⋮ → Download diagnostics to grab a sanitized JSON dump for bug reports. Credentials, e-mail, user-ID, barcode and address fields are redacted automatically.
• Cleaner per-parcel sensors — sensors for delivered parcels are now removed properly when their barcode disappears, instead of leaving orphan entries behind.
• Reauthentication now applies immediately — re-entering your credentials after a session expiry takes effect right away; no need to reload the integration manually.

Heads-up

• Minimum Home Assistant version is now 2024.7.0. Older HA instances won't load this version of the integration.

1.4.1

Fixed

• The re-authentication prompt now appears in the Home Assistant UI when the DHL session can no longer be refreshed automatically. Previously the integration only logged an error and required a manual reload.
• The Days / Number of parcels filter dropdown on the delivered-parcels setup screen now follows your Home Assistant language (English and Dutch supported).
• Dutch translations for the delivered-parcels setup and options screens are now in sync with the English version.