4.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 PostNL statusPhase.message is preserved on the parcel's raw_status attribute. The mapping uses ordered substring patterns because PostNL's status string is a free-form Dutch sentence rather than a stable enum.
• Parcel events on the HA event bus — the coordinator fires postnl_parcel_registered when a new barcode appears, postnl_parcel_status_changed when a known barcode's canonical status changes, and postnl_letter_announced for each newly-seen MyMail letter id. Events are suppressed on the very first refresh so you do not get a stampede for parcels and letters that already existed when HA started.
• MyMail letters and per-letter image entities — announced letters appear as the Letters sensor (with the full list on the letters attribute) plus one image entity per letter holding the scan. The image is fetched server-side with your token and served through Home Assistant's authenticated image proxy, so a dashboard card or mobile-notification attachment loads without leaking the token.
• Per-parcel sensors per active incoming shipment — every active incoming parcel surfaces as sensor.postnl_..._parcel_<barcode> with the full normalised parcel dict as attributes. Sensors are created when a barcode appears and removed deterministically by the summary sensor when it drops out — no more permanent unavailable ghost entities lingering after delivery.
• More summary sensors — Next delivery (device class timestamp), En route to PostNL Point, Delivered parcels (with a configurable window via the options flow). All scoped per PostNL account.
• Parcels sorted by delivery date — every bucket is now ordered: active incoming/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 PostNL account becomes a device named PostNL (<your-email>) with entities like PostNL (account@example.com) Incoming parcels. Disambiguates multi-account setups out of the box.
• examples/ folder — ready-to-paste automation YAMLs (new parcel registered, out for delivery, ready at PostNL Point, new letter arrived) and dashboard cards (active-parcels grid, letters gallery, summary glance, next-delivery countdown).

⚠️ Breaking changes & how to fix them

1. Friendly names changed

Was (≤ 3.2.x)	Is now (4.0.0)
PostNL Delivery	PostNL (account@example.com) Incoming parcels
PostNL Distribution	PostNL (account@example.com) Outgoing parcels

What to fix:

• Lovelace cards and Markdown templates that hard-code the friendly name (e.g. "PostNL Delivery") need to be updated to the new pattern, or — better — switch to referencing 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 canonical enum, not PostNL's Dutch description

Per-parcel sensors (sensor.postnl_..._parcel_<barcode>) now expose the canonical ParcelStatus value as their state.

Was (per-parcel attribute on the summary sensor)	Is now (per-parcel sensor state)
Dutch statusPhase.message (e.g. "Pakket wordt vandaag bezorgd")	Canonical ParcelStatus (e.g. out_for_delivery)

What to fix:

• Automations triggering on per-parcel state need the canonical ParcelStatus value. See the parcel-status reference in the README for the full mapping.
• The original Dutch description is still available on the parcel's raw_status attribute and on the new postnl_parcel_* events.

3. Unit-of-measurement is now translated

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

What to fix:

• Templates comparing unit_of_measurement == 'packages' should be updated to accept parcels / pakketten, or compare against entity IDs instead.
• Long-term statistics for the counters may emit a one-time "unit cannot be converted" recorder warning after upgrading. Fix via Developer Tools → Statistics → Update statistic unit, or ignore until the affected rows roll out of the retention window.