The IMAP integration is observing your IMAP server and reporting the number of unread emails. Other search criteria can be used, as shown in the example below.


Adding IMAP to your Home Assistant instance can be done via the user interface, by using this My button:

Gmail with App Password

If you’re going to use Gmail, you need to create an App Password.

  1. Go to your Google Account
  2. Select Security
  3. Under “Signing in to Google” select App Passwords
  4. Sign in to your Account, and create a new App Password for Gmail.
  5. Then you can setup the intergation as below:
    • Server:
    • Port: 993
    • Username: Your full email address
    • Password: The new app password

Configuring IMAP Searches

By default, this integration will count unread emails. By configuring the search string, you can count other results, for example:

  • ALL to count all emails in a folder
  • FROM, TO, SUBJECT to find emails in a folder (see IMAP RFC for all standard options)
  • Gmail’s IMAP extensions allow raw Gmail searches, like X-GM-RAW "in: inbox older_than:7d" to show emails older than one week in your inbox. Note that raw Gmail searches will ignore your folder configuration and search all emails in your account!

Selecting a charset supported by the imap server

Below is an example for setting up the integration to connect to your Microsoft 365 account that requires US_ASCII as charset:

  • Server:
  • Port: 993
  • Username: Your full email address
  • Password: Your password
  • Charset: US-ASCII