企业官网建设流程全解析

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 message（imap.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 集成文档）：

在用户界面中使用 imap.move

如果你习惯用可视化方式构建自动化，无需编写 YAML，Home Assistant 会逐步引导你完成配置。官方文档给出的步骤如下：

1. 进入Settings > Automations & scenes；
2. 打开现有的自动化或脚本，或选择Create新建一个；
3. 如果是新建自动化，在When（何时）部分添加触发器；脚本（script）不需要触发器；
4. 在Then do（然后执行）部分选择Add action；
5. 在搜索框中搜索并选择IMAP: Move message；
6. 选择Config entry（配置条目）、填写消息UID，并设置Target folder（目标文件夹）；
7. 点击Save保存。

UI 模式下的选项

在 UI 中，imap.move提供以下可配置项：

关于 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 参数参考

其中entry、uid、target_folder三个参数均为必填，seen为可选且默认值为false。

深入理解四个参数

entry：配置条目 ID

entry是 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 上把邮件移入垃圾箱应写INBOX/Trash，而在使用 Courier IMAP 的旧系统上则可能写作INBOX.Trash。务必使用与你的邮件服务器匹配的分隔符，否则移动会失败或指向不存在的文件夹。

seen：移动时标记已读

seen参数让移动与标记已读在一步内完成。默认值为false，即移动时不改变邮件的已读状态；设置为true时，邮件移动到新文件夹的同时会被标记为已读。这适合"归档即已读"的邮件整理流程——例如把已处理的账单邮件移入归档文件夹，同时清掉未读红点。

完整自动化示例：收到邮件自动归档

将imap.move与imap_content事件触发器结合，可以得到一个开箱即用的邮件整理自动化。以下示例（可在 IMAP 集成文档 的事件与后处理示例基础上扩展）实现：当info@example.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'] == 'info@example.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'] }}"

该示例的关键点：

1. 事件过滤：event_data中通过entry_id过滤，确保只有指定 IMAP 配置条目的事件触发；
2. 条件过滤：模板条件校验发件人为info@example.com，防止误移动其他邮件；
3. 响应变量：先用imap.fetch把邮件正文存入message_text（fetch 返回的文本不受事件 2048 字节限制），移动后仍可读取subject用于通知；
4. 一步到位：imap.move同时完成移动与标记已读。

如果你只想简单地移动而不需要读取内容，可以去掉imap.fetch步骤，直接在触发后执行imap.move。

相关动作的协同使用

imap.move在文档的related_actions中与以下动作互相关联，可按需组合：

• imap.seen：标记消息为已读：仅标记已读而不移动，参数为entry和uid，适合只清除未读状态的场景；
• imap.delete：删除消息：从服务器删除邮件（不可恢复），参数为entry和uid；
• imap.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