IMAP for Home Assistant (built-in integration)

About

IMAP is a built-in Home Assistant integration that connects to an email account and reports on its messages. It adds a sensor for messages in a chosen folder, and a search command, which defaults to unseen and undeleted mail, decides which messages are counted. New messages fire an event that can carry message data, and a template can add custom data to that event, while the event size is limited. Push updates are supported when the server offers them, with polling as the alternative that responds more slowly. Actions can fetch a message or an attachment, move a message to another folder, mark it as seen, or delete it. Setup happens in the UI, with settings for server, port, credentials, character set and SSL certificate checking.

Automatic summary of Home Assistant's source code. Something wrong? Get in touch

Supports

Uses the vendor's cloud Needs an internet connection and an account with the vendor.
Set up in the UI Add it in Settings, Devices and services. Nothing to download.
Updated with Home Assistant Ships and updates with every Home Assistant release.

Provides

Sensors

Setting it up

It is added under Settings, Devices and services, with Add integration.

Connect

Character setThe character set used. Common values are utf-8 or US-ASCII.
Message data to be included in the imap_content event data:Note that the event size is limited, and not all message text might be sent with the event if the message is too large.
FolderIn generally the folder is set to INBOX, but e.g. in case of a sub folder, named Test, this should be INBOX.Test.
PasswordThe IMAP password
PortThe IMAP port supporting SSL, usually this is 993.
IMAP searchThe IMAP search command which is UnSeen UnDeleted by default.
ServerThe IMAP server.
SSL cipher listIf the IMAP service only supports legacy encryption, try to change this.
UsernameThe IMAP username.
Verify SSL certificateRecommended, to ensure the server certificate is valid. Turn off, if the server certificate is not trusted (e.g. self signed).

Sign in again

PasswordCorrect the IMAP password.

After setup

Template to create custom event dataThis template is evaluated when a new message was received, and the result is added to the custom attribute of the event data.
Enable Push-IMAP if the server supports it. Turn off if Push-IMAP updates are unreliable.Using Push-IMAP is recommended. Polling will increase the time to respond.
Message data to be included in the imap_content event data.Note that the event size is limited, and not all message text might be sent with the event if the message is too large.
FolderIn generally the folder is set to INBOX, but e.g. in case of a sub folder, named Test, this should be INBOX.Test.
Max message size (2048 < size < 30000)Limit the maximum size of the event. Instead of passing the (whole) text message, using a template is a better option.
IMAP searchThe IMAP search command which is UnSeen UnDeleted by default.

Texts from Home Assistant's source code, Apache License 2.0.

Entities

SensorsMessages

Actions

Delete messageDeletes an email.Fields: Entry, UID
Fetch messageFetches an email message from the server.Fields: Entry, UID
Fetch message partFetches a message part or attachment from an email message.Fields: Entry, Part, UID
Move messageMoves an email to a target folder.Fields: Entry, Seen, Target folder, UID
Mark message as seenMarks an email as seen.Fields: Entry, UID