Home Assistant IMAP 集成之 imap.seen：将邮件标记为已读的完整实战指南
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
导读
imap.seen是 Home Assistant IMAP 集成提供的一个动作（action），用于将 IMAP 服务器上的某封邮件标记为“已读（seen）”。它通常与imap_content事件配合，在自动化中自动完成邮件状态更新，是邮件自动化工作流中“拉取 → 处理 → 归档/标记”链条里的关键一环。读完本文，你将掌握在 UI 与 YAML 两种模式下调用imap.seen的完整方法、其参数语义与取值来源，以及如何结合事件过滤、imap.fetch、imap.move等动作搭建真实可用的邮件后处理自动化。
动作概述：imap.seen 解决什么问题
imap.seen的动作定义为：在 IMAP 服务器上把一封邮件标记为已读。它的设计定位非常明确——在自动化中于imap_content事件之后运行，并使用事件数据中携带的配置条目（entry）与邮件uid来定位要标记的邮件。
# 来源：source/_actions/imap.seen.markdown 的 front matter action: imap.seen domain: imap description: "Marks an IMAP email message as seen." related_actions: - imap.move - imap.delete - imap.fetch从 front matter 可以看出，该动作的关联动作（related actions）包括imap.move（移动邮件）、imap.delete（删除邮件）与imap.fetch（拉取邮件内容）。这四者共同构成了 IMAP 邮件后处理的基础能力矩阵：先fetch读取内容，再根据需要seen、move或delete。
一个典型的使用场景是：邮件到达后触发自动化，先由imap.fetch取出正文并存入响应变量，再由imap.seen将该邮件标记为已读，最后发送通知或持久化记录。imap.seen本身不返回响应数据、不读取邮件内容，它只做“标记状态”这一件事，因此非常轻量。
使用前置：理解 imap_content 事件与 uid 的来源
要正确使用imap.seen，必须理解它依赖的两个输入：entry（IMAP 配置条目 ID）和uid（消息 UID）。这两个值都来自imap_content事件的触发数据。
根据 IMAP 集成文档 的说明，当搜索范围内有新邮件到达或邮件被移除时，集成会发出自定义事件imap_content。事件数据trigger.event.data是一个字典，包含以下关键键：
| 键 | 说明 |
|---|---|
server | IMAP 服务器名 |
username | IMAP 用户名 |
search | 使用的 IMAP 搜索配置 |
folder | 使用的文件夹配置 |
text | 邮件正文文本，默认只保留前 2048 字节 |
sender | 发件人 |
subject | 邮件主题 |
date | 发送时间的datetime对象 |
headers | 邮件头字典，值可迭代（头可能出现多次） |
custom | 自定义事件数据模板的渲染结果 |
initial | 是否为范围内最后一条消息的初始事件 |
parts | 多部分邮件的部件元数据字典 |
uid | 邮件的最新 UID |
imap.seen需要的uid正是trigger.event.data['uid']。因此，典型做法是在自动化触发条件中监听imap_content事件，然后通过模板{{ trigger.event.data['uid'] }}把 UID 传入动作。而entry则是你在 Home Assistant 中为某个 IMAP 账号创建的配置条目 ID（类似91fadb3617c5a3ea692aeb62d92aa869的哈希字符串）。
从 UI 使用 imap.seen（可视化配置方式）
在用户界面中调用该动作的步骤（来源：imap.seen.markdown 与 ui_header.md）：
- 进入设置>自动化与场景（Automations & scenes）。
- 打开一个现有的自动化或脚本，或选择创建新建一个。
- 如果是新自动化，在When（何时执行）部分添加触发器；脚本不需要触发器。
- 在Then do（然后执行）部分，选择添加动作（Add action）。
- 在搜索框中搜索并选择IMAP: Mark message as seen。
- 选择配置条目（Config entry），并填写消息UID（uid）。
- 选择保存（Save）。
值得注意的一点是：该动作不支持目标（targets）。与灯光、开关等实体类动作不同，界面中不会提示你选择区域（area）、设备（device）、实体（entity）或标签（label），而是直接让你选择 IMAP 配置条目。这是因为imap.seen作用的对象是邮件服务器上的消息，而非 Home Assistant 实体。
UI 模式下需要填写的选项：
| 选项 | 说明 |
|---|---|
| Config entry | 保存该邮件的 IMAP 配置条目 |
| UID | 要标记为已读的消息 UID，可从消息的事件数据中找到 |
在 YAML 中使用 imap.seen（配置参考）
在 YAML 中，该动作的调用名为imap.seen。原文档给出的基础示例（imap.seen.markdown）：
action: imap.seen data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: "{{ trigger.event.data['uid'] }}"这个示例将触发事件对应的那封邮件标记为已读。其中：
entry：持有该邮件的 IMAP 配置条目 ID。在 UI 模式下可从列表中选择；在 YAML 模式下需要自己查找条目 ID。uid：要标记为已读的消息 UID，可从消息的事件数据中取得，通常通过模板从触发事件中提取。
YAML 参数完整参考
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
entry | 是 | string | IMAP 配置条目的 ID，该条目持有目标邮件 |
uid | 是 | string | 要标记为已读的消息 UID，可从事件数据中找到 |
两个参数均为必填，且类型都是字符串。uid在 YAML 中写作字符串，但实际内容通常是通过 Jinja 模板渲染出来的数字字符串（如"{{ trigger.event.data['uid'] }}"），这符合 Home Assistant 事件数据的取值方式。
手动测试：Try it yourself
无需编写任何 YAML，你也可以在设置>工具>操作（Actions）中搜索该动作、填写字段并点击执行操作（Perform action）来实际测试（来源：try_it.md）。这是验证配置条目 ID 与 UID 是否正确的最快方式。
多配置条目下的正确姿势：按 entry 过滤事件
原文档的 “Good to know” 部分特别提醒（imap.seen.markdown）：
当你有多个 IMAP 配置条目时，请按
entry过滤触发事件，确保处理的是正确的邮件。
这一点非常关键。如果你配置了多个 IMAP 账号（例如一个 Gmail、一个工作邮箱），所有账号的imap_content事件都会触发同一个自动化。如果不在事件触发条件中过滤entry_id，imap.seen就可能拿错配置条目下的 UID 去标记邮件，导致“目标不存在”或标记错邮件。
正确的做法是在触发器的事件数据过滤中指定entry_id：
triggers: - trigger: event event_type: imap_content event_data: entry_id: 91fadb3617c5a3ea692aeb62d92aa869这样只有来自该配置条目的imap_content事件才会触发自动化。注意事件数据中的键是entry_id，而动作参数中的键是entry，两者语义相同、命名不同，混用时务必对照。
完整实战：imap_content 事件 + fetch + seen 后处理自动化
将imap.seen放入完整上下文的最佳方式，是参考 IMAP 集成文档 中的 “Example - post-processing” 示例。该示例演示了完整的“过滤 → 拉取 → 标记已读 → 通知”链路：
alias: "imap fetch and seen example" description: "Fetch and mark an incoming message as seen" 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_content事件，并用event_data.entry_id过滤，只处理指定配置条目下的邮件。 - 条件：模板条件校验发件人必须是
info@example.com，实现发件人白名单。 - 动作一：调用
imap.fetch拉取邮件正文，存入响应变量message_text。fetch返回的响应中包含text、subject、sender、uid、parts等字段（见 imap.fetch.markdown），且不像事件中的text那样有 2048 字节的大小限制。 - 动作二：调用
imap.seen，用同样的entry与uid将邮件标记为已读。集成文档还特别注明：seen动作的entry可以是模板或字面量字符串，UI 模式下也可以从列表中选择条目。 - 动作三：用
persistent_notification.create创建持久化通知，消息内容为邮件的subject。
这个模式充分体现了imap.seen的“收尾”角色：fetch 负责读取，seen 负责把已处理的邮件标记为已读，避免再次被当作未读邮件重复触发逻辑。
进阶：与 move、delete 组合构建完整的邮件流水线
imap.seen通常不是终点。结合关联动作，你可以构建完整的邮件处理流水线：
标记已读并移动（imap.move）
imap.move.markdown 允许将邮件移动到其他文件夹，并可选地同时标记为已读：
action: imap.move data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: "{{ trigger.event.data['uid'] }}" target_folder: "INBOX.Trash" seen: false # 可选，默认为 false；设为 true 时移动同时标记为已读使用imap.move时要注意 IMAP 服务器的文件夹分隔符差异：Gmail、Cyrus、Exchange、Zimbra、Yahoo 使用/（如INBOX/Trash），而 Dovecot 与 Courier 通常使用.（如INBOX.Trash）。此外，移动后的邮件不一定能恢复，务必在触发器与过滤配置正确后再执行。
标记已读后删除（imap.delete）
imap.delete.markdown 直接从服务器删除邮件，且删除不可恢复，因此原文档特别警告：请确保触发器与过滤配置正确，并在有多个配置条目时按entry过滤，只删除预期内的邮件。
处理多部分邮件的部件（imap.fetch_part）
对于 multipart 邮件，imap_content事件数据中的parts字典会列出各部件及其content_type、content_transfer_encoding、filename等元数据。集成文档中的第二个后处理示例展示了如何先校验部件类型，再用imap.fetch_part拉取指定part的内容，最后调用imap.seen标记已读：
actions: - action: imap.fetch_part data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: "{{ trigger.event.data['uid'] }}" part: "1" response_variable: message_text - action: imap.seen data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: "{{ trigger.event.data['uid'] }}" - action: persistent_notification.create data: message: "{{ message_text['part_data'] | base64_decode }}"常见问题与注意事项
- 为什么自动化没触发或标记失败？首先确认自动化确实收到了
imap_content事件（可在开发者工具的事件总线中监听）。其次核对entry是否与触发事件数据中的entry_id一致，以及uid模板是否正确渲染。 - 多个邮箱条目时务必按 entry 过滤：这是原文档明确强调的最佳实践，避免跨条目误标记。
- imap.seen 只改状态不读内容：如果需要同时获取邮件正文，请与
imap.fetch配合使用；事件中的text默认只有前 2048 字节，而fetch返回的文本不受大小限制（来源：imap.markdown 与 imap.fetch.markdown）。 - Gmail 等服务的 App Password 要求：使用 Gmail IMAP 需开启两步验证并创建 16 位应用专用密码（服务器
imap.gmail.com，端口993）；Microsoft 365 / Live IMAP 因仅支持 OAuth2 而无法与当前 IMAP 集成配合（来源：imap.markdown）。 - 仍无法解决？你可以在设置>工具>操作中手动调用该动作排查参数问题，或携带动作调用信息前往社区论坛求助（来源：stuck.md）。
关联动作速查
imap.seen与以下动作配合使用效果最佳（来源：imap.seen.markdown 的 related_actions 与 related.md）：
- imap.move：将 IMAP 邮件移动到其他文件夹，可同时标记为已读。
- imap.delete：从 IMAP 服务器删除邮件。
- imap.fetch：获取邮件正文及部件元数据，结果存入响应变量供后续步骤使用。
总结
imap.seen虽然只是一个“把邮件标记为已读”的小动作，但它在邮件自动化工作流中承担着重要的状态管理职责：它让“已处理的邮件不再被视为未读”，从而配合imap_content事件、imap.fetch、imap.move、imap.delete构成完整、可重复、可控的邮件后处理流水线。使用时牢记两条核心原则：UID 从触发事件中取，多配置条目时按 entry 过滤，即可稳定地将它集成到你的自动化体系中。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
