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必须理解它依赖的两个输入entryIMAP 配置条目 ID和uid消息 UID。这两个值都来自imap_content事件的触发数据。根据 IMAP 集成文档 的说明当搜索范围内有新邮件到达或邮件被移除时集成会发出自定义事件imap_content。事件数据trigger.event.data是一个字典包含以下关键键键说明serverIMAP 服务器名usernameIMAP 用户名search使用的 IMAP 搜索配置folder使用的文件夹配置text邮件正文文本默认只保留前 2048 字节sender发件人subject邮件主题date发送时间的datetime对象headers邮件头字典值可迭代头可能出现多次custom自定义事件数据模板的渲染结果initial是否为范围内最后一条消息的初始事件parts多部分邮件的部件元数据字典uid邮件的最新 UIDimap.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并填写消息UIDuid。选择保存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.markdownaction: imap.seen data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: {{ trigger.event.data[uid] }}这个示例将触发事件对应的那封邮件标记为已读。其中entry持有该邮件的 IMAP 配置条目 ID。在 UI 模式下可从列表中选择在 YAML 模式下需要自己查找条目 ID。uid要标记为已读的消息 UID可从消息的事件数据中取得通常通过模板从触发事件中提取。YAML 参数完整参考参数必填类型说明entry是stringIMAP 配置条目的 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_idimap.seen就可能拿错配置条目下的 UID 去标记邮件导致“目标不存在”或标记错邮件。正确的做法是在触发器的事件数据过滤中指定entry_idtriggers: - 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] infoexample.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过滤只处理指定配置条目下的邮件。条件模板条件校验发件人必须是infoexample.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.moveimap.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.deleteimap.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端口993Microsoft 365 / Live IMAP 因仅支持 OAuth2 而无法与当前 IMAP 集成配合来源imap.markdown。仍无法解决你可以在设置工具操作中手动调用该动作排查参数问题或携带动作调用信息前往社区论坛求助来源stuck.md。关联动作速查imap.seen与以下动作配合使用效果最佳来源imap.seen.markdown 的 related_actions 与 related.mdimap.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），仅供参考 
长河君 · 2026/9/17 4:13:23 · 阅读 1.2k Home Assistant IMAP 集成之 imap.seen：将邮件标记为已读的完整实战指南
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必须理解它依赖的两个输入entryIMAP 配置条目 ID和uid消息 UID。这两个值都来自imap_content事件的触发数据。根据 IMAP 集成文档 的说明当搜索范围内有新邮件到达或邮件被移除时集成会发出自定义事件imap_content。事件数据trigger.event.data是一个字典包含以下关键键键说明serverIMAP 服务器名usernameIMAP 用户名search使用的 IMAP 搜索配置folder使用的文件夹配置text邮件正文文本默认只保留前 2048 字节sender发件人subject邮件主题date发送时间的datetime对象headers邮件头字典值可迭代头可能出现多次custom自定义事件数据模板的渲染结果initial是否为范围内最后一条消息的初始事件parts多部分邮件的部件元数据字典uid邮件的最新 UIDimap.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并填写消息UIDuid。选择保存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.markdownaction: imap.seen data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: {{ trigger.event.data[uid] }}这个示例将触发事件对应的那封邮件标记为已读。其中entry持有该邮件的 IMAP 配置条目 ID。在 UI 模式下可从列表中选择在 YAML 模式下需要自己查找条目 ID。uid要标记为已读的消息 UID可从消息的事件数据中取得通常通过模板从触发事件中提取。YAML 参数完整参考参数必填类型说明entry是stringIMAP 配置条目的 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_idimap.seen就可能拿错配置条目下的 UID 去标记邮件导致“目标不存在”或标记错邮件。正确的做法是在触发器的事件数据过滤中指定entry_idtriggers: - 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] infoexample.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过滤只处理指定配置条目下的邮件。条件模板条件校验发件人必须是infoexample.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.moveimap.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.deleteimap.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端口993Microsoft 365 / Live IMAP 因仅支持 OAuth2 而无法与当前 IMAP 集成配合来源imap.markdown。仍无法解决你可以在设置工具操作中手动调用该动作排查参数问题或携带动作调用信息前往社区论坛求助来源stuck.md。关联动作速查imap.seen与以下动作配合使用效果最佳来源imap.seen.markdown 的 related_actions 与 related.mdimap.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），仅供参考