Skip to main content

Mail and Packages smart home integration, free and open source

Mail and Packages integration for Gladys Assistant

Packages and mail detected in your mailbox (UPS, FedEx, USPS, Amazon…).

Mail and Packages reads the shipping notifications that arrive in your mailbox and tells Gladys which parcels are on their way, arriving today, waiting to be picked up, delivered, or stuck. It understands 36 carriers and marketplaces (UPS, FedEx, USPS, Amazon, DHL, DPD, GLS, Colissimo, Chronopost, Mondial Relay, Hermes, Royal Mail, Correos, SEUR, InPost…) in English, French, German, Spanish, Italian, Dutch and Polish. With USPS Informed Delivery, it also counts the letters announced for the day.

It is inspired by the Home Assistant Mail and Packages integration.

Privacy​

  • The mailbox is read over IMAP, read-only: nothing is moved, flagged, marked as read or deleted.
  • Only the emails of the carriers you enable are downloaded; every other email is only seen by its sender and subject, and never stored.
  • Nothing leaves your Gladys: no third-party service, no tracking API.
  • The integration stores one small file (/data/state.json): the identifiers of the notifications already announced to your scenes, so a restart never fires them twice. No email content, no password.

Configuration​

  1. Open the Configuration tab of the integration.
  2. Fill in the IMAP server, the port and the security of your provider (see the table below), then your user name (usually your email address) and your password.
  3. Pick the folders to scan: INBOX by default. Separate several folders with commas, e.g. INBOX, Shopping. Gmail labels are folders too.
  4. Uncheck the carriers you never use, if you wish. Shops or local carriers missing from the list can be added in Other senders, as addresses ([email protected]) or domains (shop.example).
  5. Save, then click Test the connection: the message under the button says how many emails of the period are readable.
  6. Open the Discovery tab and add the devices you want.

Server settings by provider​

ProviderIMAP serverPortSecurityPassword
Gmailimap.gmail.com993TLSapp password
iCloudimap.mail.me.com993TLSapp password
Yahooimap.mail.yahoo.com993TLSapp password (Account security)
Outlook / Hotmail———Microsoft no longer accepts passwords over IMAP: forward to another mailbox
GMXimap.gmx.net993TLSenable IMAP in the GMX settings
Orangeimap.orange.fr993TLSyour password
Freeimap.free.fr993TLSyour password
Your own serverits name or IP993TLSturn on Accept a self-signed certificate for a home-made certificate only

Tip — a dedicated mailbox. You do not have to give Gladys access to your main mailbox: create a free mailbox for Gladys only, and add a forwarding rule from your main mailbox for the emails of your carriers. The original sender is kept by most forwarding rules ("redirect" in some webmails); if it is not, add your own address to Other senders.

Advanced settings​

  • Scan interval: the mailbox is read every 5 minutes by default.
  • Days of emails to read: a parcel is followed as long as its emails are younger than this (10 days by default). Archiving or deleting the emails of a parcel removes it from the counters at the next scan.
  • Language of the device names: the names Gladys gives the devices when they are created. You can rename them afterwards.
  • Time zone: decides when "today" starts. Empty: the time zone of the Gladys server.

Devices​

  • Mail and Packages — the summary of every carrier:
    • In transit: every parcel still on its way;
    • Arriving today: parcels announced "out for delivery" today;
    • Delivered today;
    • To pick up: parcels waiting in a locker, a pickup point or a post office;
    • Delivery problems: delays, missed attempts, returns;
    • Mail expected today: the letters announced by USPS Informed Delivery;
    • Last update: the latest parcel event, as text.
  • Packages – carrier — the same five counters for one carrier.

The counters are rebuilt from the mailbox at every scan: a second scan never counts the same parcel twice.

Scenes​

Triggers​

In the scene editor, category Integrations:

TriggerWhen
Package shippeda shipping confirmation arrives
Package out for deliverya carrier announces a delivery for today
Package ready for pickupa parcel waits in a locker or a pickup point
Package delivereda carrier confirms a delivery
Delivery problemdelay, missed attempt, return to sender
Letter mail expected todaythe USPS Informed Delivery digest arrives

Each parcel trigger can be filtered on one or several carriers, and exposes to the following actions: {{triggerEvent.data.carrier_name}}, {{triggerEvent.data.tracking}}, {{triggerEvent.data.tracking_url}}, {{triggerEvent.data.pickup_code}} and {{triggerEvent.data.subject}}. Each parcel step fires once, restarts included; the emails already in the mailbox when the integration is installed do not fire.

Example: Package ready for pickup → send the message "Your {{triggerEvent.data.carrier_name}} parcel waits for you, code {{triggerEvent.data.pickup_code}}".

Actions​

  • Scan the mailbox for packages — reads the mailbox now, then returns the counters.
  • Get the package counters — instant: the counters of the last scan.

Both can target one carrier and return arriving_today, in_transit, pickup, delivered, exception, mail, expected_today (true when a parcel arrives today or waits to be picked up) and summary, a sentence ready to send ("Packages: 2 arriving today, 1 to pick up."). Example: every morning at 8, Get the package counters, then "Continue only if" expected_today is true, then send the summary to the family.

Dashboard widgets​

  • Packages today — the counters as tiles, the mailbox status, the time of the last scan and a Scan now button.
  • Package tracking — the parcels on their way and today's deliveries, with the tracking number, the pickup code and a link to the tracking page of the carrier.

Both can show every carrier or a single one (widget settings).

Troubleshooting​

  • "The mail server refused the user name or the password": Gmail, iCloud and Yahoo require an app password, and two-step verification must be on to create one.
  • "Folder … does not exist": folder names are case-sensitive; Gmail's "All Mail" folder is [Gmail]/All Mail (or its translation).
  • A parcel is not detected: check that its carrier is checked, and that the email is in a scanned folder and younger than the period read. Carriers change their wording from time to time: open an issue on GitHub with the sender address and the subject of the email (remove your personal data).
  • Logs: in Gladys, open the integration's Supervision page. Set the LOG_LEVEL variable to debug for details; the password is never logged.

Configuration settings​

These are the settings Mail and Packages asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your mailboxsectionNoThe integration reads the shipping notifications of your mailbox over IMAP, read-only: nothing is moved, flagged or deleted. Gmail, iCloud, Yahoo and Outlook require an app password, not your usual password. A dedicated mailbox, to which you forward your shipping emails, works too.
IMAP serverstringYes
PortnumberYes993 with TLS, 143 with STARTTLS.
SecurityselectYes
User namestringYes
Password (or app password)secretYes
FoldersstringYesFolders to scan, separated by commas (e.g. INBOX, Shopping). Gmail labels are folders.
Accept a self-signed certificatebooleanNoOnly for a mail server on your own network. Leave off for an online provider.
CarrierssectionNoOne device per checked carrier shows up in the Discovery tab, next to the "Mail and Packages" summary device.
Carriers to detectmulti_selectNo
Other sendersstringNoShops or carriers missing from the list: addresses or domains, separated by commas. Counted under "Other senders".
AdvancedsectionNo
Scan interval (minutes)numberNo
Days of emails to readnumberNoA parcel stays "in transit" as long as its emails are younger than this.
Language of the device namesselectNo
Time zonestringNoDecides when "today" starts. Empty: the time zone of the Gladys server.

How to install Mail and Packages in Gladys​

  1. In Gladys, open Integrations: Mail and Packages appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/gboulvin/gladys-mail-and-packages:1.0.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/gboulvin/Gladys-Mail-and-Packages.

Mail and Packages 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​

Mail and Packages 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 gboulvin, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂