The usps platform allows one to track deliveries and inbound mail from the US Postal Service (USPS). In addition to having a USPS account, you will need to complete the “Opt-In” process for packages by clicking “Get Started Now” on this page. You must also “Opt-In” to Informed Delivery to see inbound mail.


This component requires that a headless-capable web browser is installed on your system - either PhantomJS or Google Chrome. Preferably use Chrome if your operating system supports it, since PhantomJS is deprecated.

If you are using a Raspberry Pi, you must use PhantomJS.


Install the latest version of PhantomJS. Ensure the executable is on your PATH. phantomjs --version should work and report the correct version. This is the default option and requires no further configuration.

Don’t use apt-get to install PhantomJS. This version is not compatible.

If you use the PhantomJS option, specify driver: phantomjs in your usps configuration.


Install Chrome 59 or greater (preferably the most recent). Install the latest Chromedriver. Ensure both executables are on your PATH. google-chrome --version and chromedriver --version should work and report the correct version.

OS-specific instructions:

If you use the Chrome option, specify driver: chrome in your usps configuration.


To enable this component, add the following lines to your configuration.yaml:

# Example configuration.yaml entry
    username: YOUR_USERNAME
    password: YOUR_PASSWORD

You will see two new sensors, one for packages and one for mail and a camera to rotate through images of incoming mail for the current day.

Configuration options for the USPS component:

  • username (Required): The username to access the MyUSPS service.
  • password (Required): The password for the given username.
  • driver (Required): Specify if you’re using phantomjs or chrome.
  • name (Optional): Prefix for sensor names (defaults to “USPS”)

The USPS sensor logs into the MyUSPS website to scrape package data. It does not use an API.