Skip to content

Configuration and Email Settings

Jump to bottom
firstof9@gmail.com edited this page Jun 14, 2026 · 44 revisions

Installation and Updates

HACS (Recommended)

  1. Have HACS installed — this allows easy updates.
  2. Go to HACS → Integrations, click + in the lower right corner, and search for Mail and Packages.
  3. Click Download under "Mail and Packages" and restart Home Assistant.

Manual Installation

  1. Download this repository as a ZIP (green button, top right) and unzip the archive.
  2. Copy the mail_and_packages folder to your Home Assistant /<config path>/custom_components/ directory.
    • You may need to create the custom_components folder if it does not exist.
    • On Home Assistant OS and Home Assistant Container the final location should be /config/custom_components/mail_and_packages.
    • On Home Assistant Supervised and Home Assistant Core the final location should be /home/homeassistant/.homeassistant/custom_components/mail_and_packages.
  3. Restart Home Assistant.

Note: If the integration does not appear, refresh the Integrations page.

Enabling Betas

HACS (Recommended)

  1. Go to Settings → Devices & services and select the HACS integration.
  2. Find Mail and Packages in the list and click it.
  3. In the Diagnostics card, click +1 disabled entry.
  4. Click Pre-releases, then click the Cog icon at the top and select Enable.
  5. HACS will reload — the Pre-releases toggle is now active. Turn it on.
  6. HACS will show that an update is available — install it and restart Home Assistant.

Configuration

Go to Settings → Devices & services → Integrations, click + Add integration, and search for Mail and Packages. Setup is a two-step process.

Re-configuration

To modify settings without removing the integration, go to Settings → Devices & services → Integrations, find Mail and Packages, and click Configure.

Step 1 — Connection

Notes about specific email providers are below.

Setting Description
Host The IMAP server address provided by your email host.
Port The IMAP port provided by your email host (typically 993 for SSL).
Email The email address where you receive shipping notifications.
Password The password (or app password) for your email account.

Checking multiple mailboxes

To check multiple email accounts, add the integration again with the credentials for the additional account. A separate set of sensors will be created for each account.

Step 2 — Options

Setting Description
Mail Folder The folder in your email account where notification emails are stored. Default is INBOX.
Sensor List The sensors to activate, corresponding to the shipping providers you want to track.
Amazon forwarded email addresses Email addresses you forward Amazon notifications from. Separate multiple addresses with a comma.
Forwarding Header If you use an email forwarding service that preserves the original sender in a custom header (e.g. X-Forwarded-To), enter that header name here. Leave blank or set to (none) if not applicable. See Email Forwarding for details.
Days to look back Number of past days to include when searching for in-transit packages. Increasing this keeps packages visible longer across the midnight boundary. Default is 3.
Scanning Interval (minutes) How often the integration checks for new emails.
Time before connection timeout (seconds) Increase this if your mail provider has a slow connection.
Image Duration (seconds) How long each USPS Informed Delivery image is shown in the rotating GIF.
Create MP4 from GIF Generate an MP4 version of the USPS Informed Delivery image.
Allow external image use Copy the image to /config/www/mail_and_packages/ so it is accessible for use in iOS and Android notifications.
Privacy / Security Note

Files stored in the www Home Assistant folder are publicly accessible unless you have taken additional security measures. For increased security, the USPS Informed Delivery image is given a random filename by default. Two sensors expose this path:

  • sensor.mail_image_system_path — local filesystem path, for use with local file cameras and automations.
  • sensor.mail_image_url — a web-accessible URL, built from your Home Assistant External URL, Internal URL, or Nabu Casa remote UI URL (whichever is available). Requires Allow external image use to be enabled.

Email Provider Notes

GMail

App Password (deprecated)

If you are using GMail you will need to set up an App Password in order for this to work. Please refer to this guide for details.

Additional information on GMail settings is available here under "Set up Gmail with older versions of Outlook and other clients".

OAuth Setup

This section explains how to generate a client ID and client secret using the Google Auth Platform.

OAuth2 Setup

Mail and Packages connects to your mailbox over IMAP. For Gmail accounts, Google requires OAuth2 rather than a password or app password. This guide walks through creating the Google OAuth credentials and wiring them into Home Assistant.

Heads up — Google changed this UI. In 2024 Google replaced the old single "APIs & Services → OAuth consent screen" wizard (with its "Test users" tab and inline scope picker) with the Google Auth Platform (https://console.cloud.google.com/auth). Setup is now split across separate Branding, Audience, Data Access, and Clients pages. The steps below reflect the current UI. (See Get started with the Google Auth Platform.)

Before you start

  • A Google account that can sign in to the Google Cloud Console.
  • A Home Assistant instance reachable over HTTPS on a public domain (required so Google will accept the OAuth redirect). The default redirect used below (https://my.home-assistant.io/redirect/oauth) works for most installs via My Home Assistant.

The whole thing is free and takes about 10 minutes. You do not need to pay for Google Cloud or submit your app for Google's review for personal use.

Step 1 — Create or select a Google Cloud project

  1. Go to the Google Cloud Console.
  2. Use the project picker at the top to create a new project (e.g. home-assistant-mail) or select an existing one you'll reuse.

Step 2 — Enable the Gmail API

The Gmail scope you need later won't be selectable unless the Gmail API is enabled on the project first, so do this now.

  1. Navigate to APIs & Services → Library (https://console.cloud.google.com/apis/library).
  2. Search for Gmail API, open it, and click Enable.

Step 3 — Configure the Google Auth Platform ("consent screen")

Open the Google Auth Platform at Google Cloud Console Auth.

  • First-time projects show a "Get started" flow. Fill it in:
    • App name — anything recognizable (e.g. Home Assistant Mail and Packages).
    • User support email — your address.
    • Audience — choose External.
    • Contact information — your email.
    • Agree and click Create.
  • Reusing a project that already has the Auth Platform configured (for example, from another Home Assistant integration)? Then there is no "Get started" button — you'll land directly on the configured Auth Platform view with the Branding / Audience / Data Access / Clients pages in the left nav. This is expected; just proceed to the next step.

(Reference: Get started with the Google Auth Platform, Manage OAuth App Branding.)

Step 4 — Add the Gmail scope (Data Access page)

  1. In the Google Auth Platform left nav, open Data Access.

  2. Click Add or remove scopes.

  3. Add the scope:

    https://mail.google.com/

    You can paste it into the "Manually add scopes" box at the bottom of the panel and click Add to table, then Update.

  4. Click Save.

⚠️ You must use the full https://mail.google.com/ scope — nothing narrower. This is the single most common mistake. The granular read-only scopes (gmail.readonly, gmail.metadata, gmail.modify, …) only work with the Gmail REST API. Mail and Packages talks to Gmail over IMAP, and IMAP/SMTP/POP authentication via XOAUTH2 only accepts https://mail.google.com/. If you pick a read-only scope, the integration will fail to authenticate. (See Google's XOAUTH2 protocol doc and Restricted Scopes.)

Because https://mail.google.com/ is classified by Google as a restricted scope, adding it pops a "Verification required" notice. For personal use this is informational — click through it. You do not need to submit your app for Google's restricted-scope verification just to read your own mailbox; you self-authorize as the app owner in Step 7.

Step 5 — Audience: user type and test users

  1. Open the Audience page.
  2. Confirm User type = External.
  3. While the app is in Testing, add your own Google account under Test users (the account whose mailbox you want Mail and Packages to read). Only test users can complete consent while the app is in Testing. (See Manage App Audience.)

Step 6 — Publish the app (avoid the 7-day token expiry)

This step is strongly recommended.

While the app's Publishing status is Testing (with External user type), Google expires OAuth refresh tokens after 7 days. The practical symptom: Mail and Packages stops updating and asks you to re-authenticate roughly once a week, seemingly at random. (Confirmed by Google: "Authorizations by a test user will expire seven days from the time of consent." — Manage App Audience.)

Fix: On the Audience page, click Publish app to move the publishing status to In production. Tokens then persist indefinitely.

  • The app will still show as "unverified" — that's fine. Verification is only needed if you intend to distribute the app publicly. For your own mailbox you simply click through the unverified-app warning once during consent (Step 7).
  • This is the exact same guidance Home Assistant gives for its built-in Google Calendar / Google Tasks integrations.

Step 7 — Create the OAuth client (Clients page)

  1. Open the Clients page in the Google Auth Platform.

  2. Click Create client.

  3. Application type: Web application.

  4. Give it a name (e.g. Home Assistant).

  5. Under Authorized redirect URIs, add:

    https://my.home-assistant.io/redirect/oauth

    If you don't use My Home Assistant, use https://<your_home_assistant_url>/auth/external/callback instead — it must exactly match the URL you use during authentication.

  6. Click Create.

  7. Copy the Client ID and Client Secret. You'll paste these into Home Assistant next.

    (New credentials are usually active within a few minutes, though Google says it can take a few hours. See the Home Assistant Google Nest docs, which use the same redirect URI and client setup.)

Step 8 — Add the credentials in Home Assistant and authenticate

  1. In Home Assistant, you'll be prompted for Application Credentials when you add / configure the Mail and Packages integration with the Google OAuth option. You can also pre-create them: Settings → Devices & Services → ⋮ (top right) → Application Credentials → Add Application Credential, choosing Mail and Packages (or the Gmail OAuth provider it uses).
  2. Paste the Client ID and Client Secret from Step 7.
  3. Continue the Mail and Packages config flow. Home Assistant hands you off to Google:
    • Pick the Google account whose mailbox you're monitoring (must be a Test user if the app is still in Testing).
    • You'll see "Google hasn't verified this app." Click Advanced, then Continue (or "Go to app name (unsafe)").
    • Grant the requested access.
  4. Google redirects back to Home Assistant and the integration finishes setup.

Common gotchas

  • "My read-only scope won't authenticate." IMAP requires the full https://mail.google.com/ scope. The gmail.readonly / gmail.metadata / gmail.modify scopes are Gmail-REST-API-only and will not work over IMAP. Use https://mail.google.com/ and nothing else.
  • "It keeps asking me to re-authenticate every week." Your app is in Testing, where Google expires refresh tokens after 7 days. Go to Audience → Publish app to move it to In production.
  • "Google says the app isn't verified." Expected for personal use. During consent, click Advanced → Continue. You only need formal verification to publish the app to other users.
  • "There's no 'Get started' button." You're reusing a Google Cloud project whose Auth Platform is already configured (common if you also use another Google-OAuth Home Assistant integration). Skip straight to the Data Access / Audience / Clients pages — there's nothing to "get started."
  • "The Gmail scope isn't in the list." You skipped Step 2 — enable the Gmail API first, then the scope becomes available on the Data Access page.
  • "Redirect URI mismatch." The redirect URI in your OAuth client must exactly match the one Home Assistant uses (https://my.home-assistant.io/redirect/oauth for My Home Assistant). Your HA instance must be reachable over HTTPS on a public domain.

A note on least privilege (optional)

https://mail.google.com/ grants full read/write/delete access to the mailbox — that's broad. If you'd rather not expose your primary inbox, a common pattern is to use a dedicated Gmail account that only receives forwarded shipment notifications (set up forwarding/filters in your main account), and point Mail and Packages at that mailbox instead. The integration only reads message subjects (and, for USPS Informed Delivery, the mail-piece images), but the OAuth scope itself is all-or-nothing for IMAP, so an isolated mailbox is the cleanest way to limit blast radius.

Sources

Yahoo Mail

Nothing special is required for Yahoo Mail — just enter your username (Yahoo email address) and password. If you have 2FA enabled you will need to generate an app password.

References: Server Settings | App Passwords

Hotmail/Outlook/Live/Office

OAuth2 Setup

Mail and Packages connects to your mailbox over IMAP. For Hotmail, Outlook, Live, and Office 365 accounts, Microsoft requires OAuth2 rather than a password or app password. This guide walks through creating the Microsoft OAuth credentials and wiring them into Home Assistant.

Step 1 — App Registration

  1. Go to the Microsoft Azure Portal / Entra admin center (App Registrations).
  2. Click + New registration.
  3. Name: Enter a recognizable name (e.g., Home Assistant Mail).
  4. Supported account types: Select "Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)".
    • Note: This is required to support @live.com, @hotmail.com, and @outlook.com addresses.
  5. Redirect URI: Select Web from the dropdown and enter: 
    https://my.home-assistant.io/redirect/oauth
    • Note: If you don't use My Home Assistant, enter https://<your_home_assistant_url>/auth/external/callback instead.
  6. Click Register.

Step 2 — Configure API Permissions (Scopes)

  1. On the left sidebar of your app registration, go to API permissions.
  2. Click + Add a permission, then select Microsoft Graph.
  3. Click Delegated permissions.
  4. Search for and check:
    • IMAP.AccessAsUser.All
    • offline_access (required for token refresh)
  5. Click Add permissions.
  6. Optional for work/school accounts: If you are registering an organizational mailbox, click Grant admin consent for [Your Organization Name] next to the Add a permission button. Personal accounts do not need admin consent.

Step 3 — Create Client Secret

  1. On the left sidebar, go to Certificates & secrets.
  2. Click + New client secret, enter a description, set a preferred expiry (e.g., 24 months), and click Add.
  3. Important: Copy the string in the Value column (not the Secret ID) immediately. This value is only shown once.

Step 4 — Copy the Application (Client) ID

  1. Go to the Overview tab in the left sidebar.
  2. Copy the Application (client) ID value.
  3. Note: You do not need the Directory (tenant) ID. The integration automatically routes authentication requests through Microsoft's /common endpoint, so you will only need to input the Client ID and Client Secret in Home Assistant.

Step 5 — Add the credentials in Home Assistant and authenticate

  1. In Home Assistant, you'll be prompted for Application Credentials when configuring the Mail and Packages integration with the Microsoft OAuth option. You can also pre-create them: Settings → Devices & Services → ⋮ (top right) → Application Credentials → Add Application Credential, choosing Mail and Packages (or the Microsoft OAuth provider it uses).
  2. Paste the Client ID (from Step 4) and Client Secret (from Step 3).
  3. Continue the Mail and Packages config flow. Home Assistant redirects you to Microsoft to authorize the connection to your mailbox.
  4. Once completed, you will be redirected back to Home Assistant to finish setup.

Proton Mail

  1. Set up Proton Mail Bridge (Docker container). After initial setup, run the info command to get connection details.
  2. Add the integration using the credentials provided by the bridge. Use SSL and No verification of SSL certificate. Username and password are provided by the bridge.

Clone this wiki locally