Home Assistant IMAP 邮件移动指南：用 imap.move 动作实现邮件归档与整理
Home Assistant IMAP 邮件移动指南用 imap.move 动作实现邮件归档与整理【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文讲解 Home Assistant 的IMAP: Move messageimap.move动作它能够把 IMAP 服务器上的某封邮件移动到指定文件夹例如垃圾箱或归档目录并可在移动的同时将该邮件标记为已读。该动作专为自动化场景设计通常配合 IMAP 集成发出的imap_content事件使用——从事件数据中取出entry配置条目 ID和uid消息唯一标识即可精确操作触发事件对应的那封邮件。读完本文你将掌握在 UI 与 YAML 两种模式下配置imap.move的完整方法、四个核心参数的含义、不同邮件服务器的文件夹分隔符差异以及一个可直接运行的自动化归档示例。动作概述imap.move 能做什么imap.move是 Home Assistant IMAP 集成提供的四个邮件操作动作之一与 imap.seen标记已读、imap.delete删除邮件、imap.fetch获取邮件内容 并列用于在自动化中对邮件进行后处理。它的核心能力是移动邮件把服务器上的一封邮件从一个文件夹移动到另一个文件夹可选标记已读通过seen参数决定是否在移动时同步标记为已读true或false默认false事件驱动设计文档明确指出它预期在imap_content事件之后运行直接使用事件数据中的entry和消息uid无需自己维护邮件列表。与imap.delete的不可恢复删除不同移动是一种相对温和的整理手段常用于把处理完毕的邮件移入Trash或归档文件夹。前置条件先配置 IMAP 集成在使用imap.move之前你需要先在 Home Assistant 中配置好 IMAP 集成Settings Devices services Add integration IMAP得到一个config entry。该集成负责连接邮件服务器、按搜索条件检测新邮件并在新邮件到达或移除时发出imap_content自定义事件。imap.move动作中的entry参数指的就是这个配置条目的 ID形如91fadb3617c5a3ea692aeb62d92aa869的哈希字符串。imap_content事件数据中与移动最相关的字段如下完整字段表见 IMAP 集成文档事件数据字段说明uid消息的唯一标识imap.move用它定位要移动的邮件entry_id触发事件的 IMAP 配置条目 ID可用于事件过滤sender邮件发件人subject邮件主题folder邮件所在的文件夹initial是否为该会话的初始事件在用户界面中使用 imap.move如果你习惯用可视化方式构建自动化无需编写 YAMLHome Assistant 会逐步引导你完成配置。官方文档给出的步骤如下进入Settings Automations scenes打开现有的自动化或脚本或选择Create新建一个如果是新建自动化在When何时部分添加触发器脚本script不需要触发器在Then do然后执行部分选择Add action在搜索框中搜索并选择IMAP: Move message选择Config entry配置条目、填写消息UID并设置Target folder目标文件夹点击Save保存。UI 模式下的选项在 UI 中imap.move提供以下可配置项UI 选项说明是否必填Config entry承载该邮件的 IMAP 配置条目是UID要移动消息的 UID可在该消息的事件数据中找到是Target folder目标文件夹名称例如INBOX/Trash或旧系统上的INBOX.Trash是Seen移动时是否将消息标记为已读否关于 Targets 的说明imap.move不支持 targets目标选择。在 UI 中系统不会提示你选择区域area、设备device、实体entity或标签label而是直接要求选择 IMAP 配置条目。这是合理的邮件的操作对象是 IMAP 服务器上的消息而不是 Home Assistant 中的实体。在 YAML 中使用 imap.move如果你直接编写 YAML或想精确了解动作的底层字段可以参考下面的技术参考。YAML 中该动作的服务名称为imap.move。基本 YAML 示例官方文档给出的基础示例如下它把触发事件对应的邮件移动到INBOX.Trash文件夹action: imap.move data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: {{ trigger.event.data[uid] }} target_folder: INBOX.Trash这段配置的含义从imap_content触发事件的事件数据中取出uid配合固定的entry配置条目 ID把该邮件移动到INBOX.Trash。YAML 参数参考参数类型必填默认值说明entrystring是—承载该邮件的 IMAP 配置条目 ID。UI 模式下可从列表选择YAML 模式下需在配置条目中查找该 IDuidstring是—要移动消息的 UID可在消息的事件数据中找到target_folderstring是—目标文件夹名称例如INBOX/Trash或旧系统上的INBOX.Trashseenboolean否false移动时是否将消息标记为已读其中entry、uid、target_folder三个参数均为必填seen为可选且默认值为false。深入理解四个参数entry配置条目 IDentry是 IMAP 配置条目的唯一 ID。当你的 Home Assistant 中只配置了一个 IMAP 条目时它自然是唯一的选择但当存在多个 IMAP 配置条目例如分别监控 Gmail 与工作邮箱时必须用entry精确指定操作哪个账户。官方Good to know部分特别强调当你有多个 IMAP 配置条目时应通过entry过滤触发事件确保处理的是正确的邮件。uid消息唯一标识uid是 IMAP 协议中消息的唯一标识UID它不像顺序号那样会随邮箱内容变化因此适合在事件与动作之间传递。在自动化中你通常不需要手动查找 UID直接从trigger.event.data[uid]模板取值即可例如上文示例中的{{ trigger.event.data[uid] }}。target_folder目标文件夹与分隔符target_folder指定邮件要移动到的目标文件夹。这里最容易踩坑的是文件夹分隔符不同 IMAP 服务器使用不同的层级分隔符。官方文档给出的参考如下邮件服务文件夹分隔符Gmail/Dovecot.但通常为/Courier IMAP.Cyrus IMAP/Microsoft Exchange/Zimbra/Yahoo Mail/例如在 Gmail 上把邮件移入垃圾箱应写INBOX/Trash而在使用 Courier IMAP 的旧系统上则可能写作INBOX.Trash。务必使用与你的邮件服务器匹配的分隔符否则移动会失败或指向不存在的文件夹。seen移动时标记已读seen参数让移动与标记已读在一步内完成。默认值为false即移动时不改变邮件的已读状态设置为true时邮件移动到新文件夹的同时会被标记为已读。这适合归档即已读的邮件整理流程——例如把已处理的账单邮件移入归档文件夹同时清掉未读红点。完整自动化示例收到邮件自动归档将imap.move与imap_content事件触发器结合可以得到一个开箱即用的邮件整理自动化。以下示例可在 IMAP 集成文档 的事件与后处理示例基础上扩展实现当infoexample.com发来新邮件时先获取邮件内容存入响应变量再把它移动并标记为已读alias: Move incoming message to archive description: Fetch and archive incoming messages from a specific sender 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.move data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: {{ trigger.event.data[uid] }} target_folder: INBOX.Trash seen: true - action: persistent_notification.create data: message: Moved message: {{ message_text[subject] }}该示例的关键点事件过滤event_data中通过entry_id过滤确保只有指定 IMAP 配置条目的事件触发条件过滤模板条件校验发件人为infoexample.com防止误移动其他邮件响应变量先用imap.fetch把邮件正文存入message_textfetch 返回的文本不受事件 2048 字节限制移动后仍可读取subject用于通知一步到位imap.move同时完成移动与标记已读。如果你只想简单地移动而不需要读取内容可以去掉imap.fetch步骤直接在触发后执行imap.move。相关动作的协同使用imap.move在文档的related_actions中与以下动作互相关联可按需组合imap.seen标记消息为已读仅标记已读而不移动参数为entry和uid适合只清除未读状态的场景imap.delete删除消息从服务器删除邮件不可恢复参数为entry和uidimap.fetch获取消息内容获取邮件正文与部件元数据通过response_variable返回结果正文大小不受限制。一个常见的收件箱清空流程是imap.fetch读取内容 → 用模板传感器提取信息 →imap.move归档或imap.delete清理全部在imap_content事件触发后按序执行。若要处理多部分multipart邮件的指定部件可进一步使用 imap.fetch_part 动作按parts字典中的索引获取对应内容。注意事项与最佳实践多配置条目时务必过滤当你有多个 IMAP 配置条目时imap_content事件会来自不同账户。官方文档强调用entry过滤触发事件确保处理的是正确的邮件。遗漏这一过滤可能导致动作对错误的账户执行移动操作。移动后的邮件不一定能恢复官方Good to know部分给出明确警告被移动的邮件并不总能恢复。例如移动到某些服务器的Trash文件夹后若邮件最终被清理策略删除将无法找回。因此在使用该动作前务必确保触发器和过滤条件配置正确——建议先在测试账户上验证流程再应用到生产环境。结合事件数据中的 initial 字段imap_content事件的initial字段布尔值标识事件是否为最后一条收到消息的初始事件。当搜索范围内有消息被移除而最后收到的消息未变化时也会生成imap_content事件且initial为False。设计自动化时可通过该字段区分新邮件到达与邮件被移除两种事件避免对移除事件误执行移动操作。动手测试想在不写一行 YAML 的情况下验证imap.move进入Settings Tools Actions搜索IMAP: Move message填写配置条目、UID 与目标文件夹点击Perform action即可在你的真实实体上观察效果。测试时建议先在某个不影响正常收件的文件夹如INBOX内新建的子文件夹中验证分隔符与目标文件夹写法是否正确确认无误后再用于生产自动化。如果遇到问题可在社区寻求帮助提交时请附上你调用的动作、配置条目与预期行为或让 AI 助手根据你的自然语言描述推荐正确的动作与参数组合。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考