4.6.1

Bug fixes

• The "delivery is taking a bit longer due to busyness" notice is recognised again. PostNL's busy-delay status was reported as unknown and now maps to in transit (#12).

---

📦 See every supported carrier — new ones land regularly.

4.6.0

New features

• A dedicated "parcel delivered" event — postnl_parcel_delivered fires the moment a parcel is delivered, with a matching device trigger. The final hop now fires this instead of a generic status change.

Bug fixes

• "Zending is bezorgd in de brievenbus" is recognised again — observation code I11 was reported as unknown and now maps to delivered (#11).

---

📦 See every supported carrier — new ones land regularly.

4.5.1

Bug fixes

• Fewer false "unknown status" warnings — PostNL's own Unknown status is now recognised, so it no longer triggers a "help us map it" warning (#9).
• Quieter logs for brand-new parcels — a parcel PostNL doesn't track yet no longer logs colli/barcode warnings; those details drop to debug (#8).

4.5.0

New features

• Automations for parcels you send back — two new events, postnl_outgoing_parcel_status_changed and postnl_outgoing_parcel_delivered, now fire for your outgoing/return parcels, and both are available as no-code device triggers. Get notified the moment a return changes status or arrives.

Bug fixes

• More delivery statuses recognised — statuses that previously showed up as unknown are now mapped correctly, including a delayed/failed delivery attempt ("bezorgmoment bijgewerkt / lukt vandaag niet") and the A03, R01 and K50 tracking events.
• All entities load reliably again — the first data fetch now runs during setup, so a transient error no longer leaves you with only part of the entities. Home Assistant cleanly retries the whole setup instead.

Credits

Thanks to @Mitch73-2 for reporting the unrecognised statuses. 🙏

4.4.0

New features

• Outgoing delivered parcels sensor — a new "Outgoing delivered parcels" sensor surfaces the parcels you sent that were recently delivered, so they no longer silently disappear once they reach the recipient. It honours the same delivered-parcels window (last N days / N most recent) as the incoming delivered sensor.

Credits

Thanks to @jonisnet for reporting this gap and contributing the implementation. 🙏

4.3.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 PostNL 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

• All calls to PostNL now use request timeouts, so a hung connection can no longer stall updates.
• One slow or failing parcel no longer breaks the whole refresh — each parcel degrades on its own.
• Delivered-parcel history is cached and API clients are reused for fewer, faster requests.
• Re-authentication is guarded against binding the entry to a different account.
• Refresh-interval options are translated, and shared wording is aligned with the other carriers.

4.2.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 PostNL's own description), capped to the most recent 20 events. Off by default, and kept out of the long-term recorder database. Notification and ETA updates inherit the parcel's current stage, so the timeline never jumps backwards.

4.1.0

What's new

• New event postnl_parcel_delivery_time_changed — fires when a parcel's planned delivery window appears or shifts, so you can trigger notifications. An example automation is included under examples/automations/.
• Configurable refresh interval — pick how often PostNL is polled (15, 30, 60, 120 or 240 minutes) in the integration options.
• Parcel weight and dimensions are now exposed as parcel attributes where PostNL provides them.
• Receiver (recipient) name is now available on each parcel, matching the DHL and DPD integrations.
• Improved authentication flow for a more reliable connection to PostNL.

Heads-up

• The default polling interval is now 30 minutes. Want more frequent updates? Set a shorter interval in the integration options.

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.

4.0.0b3

Bug fixes

• Setup no longer crashes on mixed delivery timestamps — some accounts hit ConfigEntryNotReady on every refresh when one delivered parcel carried a Z-suffixed timestamp and another did not. The integration now normalises both shapes.

What's new

• Letter image entities keep a meaningful "last updated" — the entity's state is the parsed letter date instead of HA's boot time, so restarting Home Assistant no longer makes every announced letter look like it just arrived.
• Letter image entities expose more attributes — each image.postnl_..._letter_<title> entity now carries id, title, date and unread, mirroring the per-letter shape the sensor.postnl_letters letters attribute and the postnl_letter_announced event already use.

No breaking changes — purely additive on top of 4.0.0b2.