首页 ▸ Integrations ▸

IMAP

IMAP集成正在观察您的IMAP服务器。它可以报告未读邮件的数量，并可以发送一个自定义事件，用于触发自动化。可以使用其他搜索条件，如下面的示例所示。

配置

要将 IMAP integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

浏览到您的 Home Assistant 实例。
转到 设置 > 设备与服务。
在右下角，选择 Add Integration 按钮。
从列表中选择 IMAP。
按照屏幕上的说明完成设置。

带应用密码的IMAP服务

Microsoft 365和Live IMAP服务

Microsoft已删除在没有现代验证的情况下直接使用（应用）密码访问IMAP的支持。您可以创建一个应用密码，但访问仅允许通过获得Microsoft授权的OAUTH2启用的邮件客户端或通过Microsoft Entra ID（学校或企业）中的应用注册。

IMAP集成不支持OAUTH2身份验证流程。这意味着遗憾的是，无法将Home Assistant IMAP与Microsoft 365 IMAP服务（学校和企业版）以及（免费）个人Microsoft Live IMAP服务一起使用。

Google Gmail IMAP服务

如果您打算使用Gmail，则必须在您的Gmail帐户上启用两步验证。一旦启用，您需要创建一个应用密码。

访问您的Google帐户
选择安全性
在“如何登录Google”下选择两步验证。
登录到您的帐户。
在两步验证页面底部，单击应用密码。
给您的应用起个能理解的名字（例如，Home Assistant IMAP）。
单击创建，然后记下您的16位字符应用密码以备保存（保存时去掉空格）。
单击完成。
使用上面的我的按钮将IMAP集成添加到您的Home Assistant实例中。根据需要输入以下信息：
- 用户名：您的Gmail邮件登录
- 密码：您的16位字符应用密码（不带空格）
- 服务器：imap.gmail.com
- 端口：993
单击提交。
如果需要，将您的集成分配给“区域”，然后单击完成。

恭喜您，现在您有一个传感器来计算您Gmail帐户中未读电子邮件的数量。从这里您可以创建其他传感器，基于事件总线中检测到的新消息所传递的数据。

配置IMAP搜索

默认情况下，此集成将计算未读邮件。通过配置搜索字符串，您可以计算其他结果，例如：

ALL以计算文件夹中的所有邮件
FROM、TO、SUBJECT以查找文件夹中的邮件（请参见IMAP RFC的所有标准选项）
Gmail的IMAP扩展允许原始Gmail搜索，例如X-GM-RAW "in: inbox older_than:7d"以显示您收件箱中超过一周的邮件。请注意，原始Gmail搜索将忽略您的文件夹配置，并搜索您帐户中的所有邮件！

选择IMAP服务器支持的字符集

某些IMAP服务，如Yahoo，需要配置US-ASCII字符集。

选择要包含在IMAP事件中的消息数据（高级模式）

默认情况下，IMAP事件不会包括text或headers消息数据。如果您想让它们被包括在内（text或headers，或者两者），您必须在选项流中手动选择它们。处理text数据的另一种方法是使用imap.fetch操作。在这种情况下，text不会受到大小的限制。

选择备用SSL密码列表或禁用SSL验证（高级模式）

如果默认的IMAP服务器设置无法正常工作，您可以尝试设置备用SSL密码列表。 SSL密码列表选项允许您从此端点选择被接受的SSL密码列表：default（系统默认）、modern或intermediate（灵感来自Mozilla Security/Server Side TLS）。

如果您使用自签名证书，可以关闭SSL验证。

Important

SSL密码列表和验证SSL是高级设置。只有在启用高级模式时，选项才可用（请参见用户设置）。

启用IMAP-Push

如果您的IMAP服务器支持IMAP-Push，则默认情况下将启用IMAP-Push。如果您使用的是不可靠的IMAP服务，定期掉线并导致问题，您可能考虑关闭IMAP-Push。这将回退到轮询IMAP服务器。

Important

强制轮询选项是高级设置。只有在启用高级模式时，选项才可用（请参见用户设置）。

故障排除

电子邮件提供商可能限制报告的电子邮件数量。即便您设置IMAP搜索以减少结果数，该数量可能仍少于限制（至少对于Yahoo为10,000）。如果您没有收到预期的事件，且清理收件箱或配置的文件夹不是所需的，请为特定发件人设置电子邮件过滤，让其进入新文件夹。然后创建一个新的配置条目或修改现有条目，使用所需的文件夹。

使用事件

当新消息到达或在定义的搜索命令范围内移除消息时，imap集成将发送一个自定义event，可用于触发自动化。还可以基于event data创建模板binary_sensor或sensor。

下表显示了trigger.event.data中包含的属性。数据是一个字典，具有以下所示的键。

表中显示的属性也可作为自定义事件数据模板的变量使用。示例展示了如何将其用作事件过滤器。

Important

自定义事件数据模板是高级功能。只有在启用高级模式时，选项才可用（请参见用户设置）。在模板中用作变量时，text属性没有大小限制。

server

IMAP服务器名称

username

IMAP用户名

IMAP搜索配置

folder

IMAP文件夹配置

text

消息的电子邮件正文text。默认情况下，只有前2048字节的正文文本可用，其余部分将被截断。您可以增加正文的最大文本大小，但这不建议并且永远无法保证整个消息文本可用。更好的做法是使用自定义事件数据模板（高级设置），可以解析整个消息，不受大小限制。渲染的结果将作为属性custom附加到事件数据，以便用于自动化。如果在选项流中明确选择，将包括text。

sender

消息的sender

subject

消息的subject

date

发送的date的datetime对象

headers

消息的headers以字典形式出现。值是可迭代的，因为头部可以多次出现。如果在选项流中明确选择，将包括headers。

custom

保存自定义事件数据结果template。所有属性均作为模板中的变量可用。

initial

如果这是最后一条接收邮件的初始事件，则返回True。当在搜索范围内的一条消息被删除，且最后接收的消息未更改时，将生成一个imap_content事件，并将initial属性设置为False。请注意，如果触发电子邮件上未设置Message-ID头，initial属性将始终设置为True。

uid

消息的最新uid。

自定义事件的event_type应设置为imap_content。以下配置显示了您如何在模板传感器中使用事件数据。

如果要用于事件的默认最大消息大小（2048字节）对您的需求来说太小，则可以增加此最大大小设置。您需要将您的配置设置为_高级_模式才能执行此操作。

Warning

增加默认最大消息大小（2048字节）可能会对性能产生负面影响，因为事件数据也由recorder记录。如果总事件数据大小超过最大事件大小（32168字节），该事件将被跳过。

template:
  - trigger:
      - trigger: event
        event_type: "imap_content"
        id: "custom_event"
    sensor:
      - name: imap_content
        state: "{{ trigger.event.data['subject'] }}"
        attributes:
          Entry: "{{ trigger.event.data['entry_id'] }}"
          UID: "{{ trigger.event.data['uid'] }}"
          Message: "{{ trigger.event.data['text'] }}"
          Server: "{{ trigger.event.data['server'] }}"
          Username: "{{ trigger.event.data['username'] }}"
          Search: "{{ trigger.event.data['search'] }}"
          Folder: "{{ trigger.event.data['folder'] }}"
          Sender: "{{ trigger.event.data['sender'] }}"
          Date: "{{ trigger.event.data['date'] }}"
          Subject: "{{ trigger.event.data['subject'] }}"
          Initial: "{{ trigger.event.data['initial'] }}"
          To: "{{ trigger.event.data['headers'].get('Delivered-To', ['n/a'])[0] }}"
          Return-Path: "{{ trigger.event.data['headers'].get('Return-Path',['n/a'])[0] }}"
          Received-first: "{{ trigger.event.data['headers'].get('Received',['n/a'])[0] }}"
          Received-last: "{{ trigger.event.data['headers'].get('Received',['n/a'])[-1] }}"

邮件后处理的操作

IMAP集成有一些用于后处理电子邮件消息的操作。这些操作是用于自动化中的操作，作为“imap_content”事件之后的操作。操作使用IMAP entry_id和消息的事件数据中的uid。您可以为entry_id和uid使用模板。当操作被设置为触发操作时，您可以轻松地从UI中选择正确的条目。您将在YAML模式中找到entry_id。强烈建议您通过entry_id过滤事件。

可用的操作包括：

seen：将消息标记为已读。
move：将消息移动到target_folder并可选地标记为已读。
delete：删除消息。
fetch：获取消息的内容。返回包含"text"、"subject"、"sender"和"uid"的字典。这允许获取和处理完整的消息文本，不受大小的限制。

Caution

当这些操作在自动化中使用时，请确保正确设置触发器和过滤。如果删除消息，它们将无法恢复。当设置多个IMAP条目时，请确保根据entry_id过滤消息，以确保处理正确的消息。除非您知道自己在做什么，否则请勿使用这些操作。

示例 - 后处理

下面的示例通过entry_id过滤事件触发器，获取消息并将其存储在message_text中。然后将事件中的消息标记为已读，最后添加一个包含消息主题的通知。seen操作的entry_id可以是一个模板或字面字符串。在UI模式下，您还可以从列表中选择所需的条目。

alias: "imap fetch and seen example"
description: "获取并标记传入消息为已读"
triggers:
  - trigger: event
    event_type: imap_content
    event_data:
      entry_id: 91fadb3617c5a3ea692aeb62d92aa869
conditions:
  - condition: template
    value_template: "{{ trigger.event.data['sender'] == 'info@example.com' }}"
actions:
  - action: imap.fetch
    data:
      entry: 91fadb3617c5a3ea692aeb62d92aa869
      uid: "{{ trigger.event.data['uid'] }}"
    response_variable: message_text
  - action: imap.seen
    data:
      entry: 91fadb3617c5a3ea692aeb62d92aa869
      uid: "{{ trigger.event.data['uid'] }}"
  - action: persistent_notification.create
    data:
      message: "{{ message_text['subject'] }}"

示例 - 关键词检测

以下示例展示了IMAP电子邮件内容传感器的用法，以扫描电子邮件的主题文本。在此示例中，来自APC SmartConnect服务的电子邮件告诉UPS是否正在使用电池运行。

template:
  - trigger:
      - trigger: event
        event_type: "imap_content"
        id: "custom_event"
        event_data:
          sender: "no-reply@smartconnect.apc.com"
          initial: true
    sensor:
      - name: house_electricity
        state: >-
          {% if 'UPS On Battery' in trigger.event.data["subject"] %}
            power_out
          {% elif 'Power Restored' in trigger.event.data["subject"] %}
            power_on
          {% endif %}

示例 - 使用模板传感器从电子邮件中提取格式化文本

本示例显示如何从电子邮件中提取数字或其他格式化数据，以更改模板传感器的值，该值来自电子邮件。我们将从一封电子邮件（来自Georgia Power）中提取能耗、费用和账单金额，并将其放入传感器值中，使用我们已设置的IMAP电子邮件传感器。以下是所用电子邮件正文的示例：

昨天的能源使用量：                             76 kWh
昨天的估计能源费用：                          $8
截至23天的每月能源使用量：                    1860 kWh
截至23天的每月估计能源费用：                  $198

要查看有关您能源使用的详细信息，请单击此处。

下面是提取信息的模板传感器，将IMAP电子邮件传感器（命名为sensor.energy_email）中的电子邮件正文提取到能耗、每日费用和账单周期总共3个传感器中。

template:
  - trigger:
      - trigger: event
        event_type: "imap_content"
        id: "custom_event"
        event_data:
          sender: "no-reply@smartconnect.apc.com"
    sensor:
      - name: "前一天的能源使用"
        unit_of_measurement: "kWh"
        state: >
        {{ trigger.event.data["text"]
          | regex_findall_index("\*昨天的能源使用量：\* ([0-9]+) kWh") }}
      - name: "前一天的费用"
        unit_of_measurement: "$"
        state: >
          {{ trigger.event.data["text"]
            | regex_findall_index("\*昨天的估计能源费用：\* \$([0-9.]+)") }}
      - name: "账单周期总量"
        unit_of_measurement: "$"
        state: >
          {{ trigger.event.data["text"]
            | regex_findall_index("\ days:\* \$([0-9.]+)") }}

通过对上述正则表达式进行小的更改，可以对其他类型的数据进行类似结构的解析，提取其他电子邮件正文文本的信息。

示例 - 自定义事件数据模板

我们可以定义一个自定义事件数据模板来帮助过滤事件。如果我们有多个发件人想要允许，这将非常方便。我们定义以下模板，如果sender的一部分是@example.com，则返回true：

{{ "@example.com" in sender }}

如果发件人被允许，则渲染为True。结果作为trigger.event.data["custom"]添加到事件数据中。

以下示例仅在发件人地址匹配时，将模板传感器的状态设置为电子邮件的主题。

template:
  - trigger:
      - trigger: event
        event_type: "imap_content"
        id: "custom_event"
        event_data:
          custom: True
    sensor:
      - name: 被模板过滤的事件
        state: '{{ trigger.event.data["subject"] }}'

移除IMAP服务

此集成遵循标准配置条目移除流程。

从Home Assistant中移除集成实例

前往设置 > 设备与服务 并选择集成卡片。
从设备列表中，选择要删除的集成实例。
在条目旁边，选择三个点菜单。然后，选择删除。

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈