Home Assistant IMAP 集成imap.fetch 动作详解——完整拉取邮件正文与部件元数据【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读imap.fetch是 Home Assistant IMAP 集成提供的核心动作action用于从 IMAP 服务器上按uid拉取邮件的纯文本正文并返回该邮件的部件part元数据。它专门设计为在imap_content事件触发后运行弥补了事件数据中正文text字段默认只有 2048 字节大小限制的不足。读完本文你将掌握如何通过 UI 与 YAML 两种方式调用imap.fetch、理解其响应数据结构并能写出「抓取邮件 → 标记已读 → 通知/解析」的完整自动化。一、imap.fetch 的定位为什么需要它在 IMAP 集成文档 中当新邮件到达或删除时集成会发送一个自定义事件imap_content事件数据trigger.event.data中携带sender、subject、date、uid、parts等属性其中text字段保存邮件正文。关键限制在于事件里的text默认只包含正文的前 2048 字节。虽然可以通过选项流提高上限但文档明确警告这会拖慢性能——事件数据会被recorder记录一旦总事件大小超过 32168 字节事件甚至会被跳过详见 imap.markdown。imap.fetch正是为解决这个问题而生Unlike theimap_contentevent, the returned text is not limited in size.该动作返回的结果存放在**响应变量response variable**中供同一自动化或脚本的后续步骤使用且正文长度不受 2048 字节限制。这是它与事件数据的本质区别也是其在「全文解析」「关键词提取」类自动化中的核心价值。与其他相关动作的关系imap.fetch并非孤立存在它与 IMAP 动作家族配合使用imap.fetch_part按部件索引抓取单个部件或附件内容imap.seen将消息标记为已读imap.move将消息移动到其他文件夹可同时标记已读。典型工作流是imap_content事件触发 →imap.fetch拉全文 →imap.seen标记已读 → 后续动作处理内容。二、通过 UI 使用 imap.fetchimap.fetch不支持 targetsUI 中不会提示选择区域、设备、实体或标签而是直接选择IMAP 配置条目Config entry。操作步骤如下进入设置Settings 自动化与场景Automations scenes打开现有自动化或脚本或点击创建新建若新建自动化在When触发条件部分添加触发器脚本则无需触发器在Then do执行动作部分点击添加动作搜索并选择IMAP: Fetch message选择配置条目并提供消息UID在响应变量Response variable字段中输入存储名称例如message点击保存。UI 中的选项选项说明Config entry保存该消息的 IMAP 配置条目UID要抓取的消息的 UID可在消息的事件数据中找到三、YAML 用法与参数详解在 YAML 中该动作名为imap.fetch。核心要点是必须把结果存入响应变量才能在后续步骤中使用。最基本的示例action: imap.fetch data: entry: 91fadb3617c5a3ea692aeb62d92aa869 uid: {{ trigger.event.data[uid] }} response_variable: message此例从触发事件中获取消息并存入message响应变量。YAML 参数表参数类型必填说明entrystring是保存该消息的 IMAP 配置条目 ID。UI 模式下可从列表选择YAML 模式下需自行查找条目 IDuidstring是要抓取的消息 UID可在消息的事件数据中找到两个参数都通过data传入response_variable是动作级字段而非data内的参数。uid通常直接用模板{{ trigger.event.data[uid] }}从触发事件中读取从而让自动化对每封新邮件都能精准定位目标消息。多配置条目时的过滤如果 Home Assistant 中配置了多个 IMAP 条目务必在触发器层面对entry_id或动作中对entry进行过滤否则动作可能处理错误邮箱的消息。IMAP 集成文档给出的触发过滤方式是在事件触发器中使用event_datatriggers: - trigger: event event_type: imap_content event_data: entry_id: 91fadb3617c5a3ea692aeb62d92aa869四、响应数据Response data结构imap.fetch的响应包含以下字段text抓取邮件的纯文本版本subject抓取邮件的主题sender发件人邮箱地址uid消息的 UIDparts多部分multipart消息中可用部件的元数据字典。每个键是一个部件索引可传给 imap.fetch_part 动作使用每个部件包含content_type、content_transfer_encoding以及若设置了filename。多部分消息的parts数据示例如下{ 0,0: { content_type: text/plain, content_transfer_encoding: 7bit }, 0,1: { content_type: text/html, content_transfer_encoding: 7bit }, 1: { content_type: text/plain, filename: Text attachment content.txt, content_transfer_encoding: base64 } }从示例可以看出部件索引的规律嵌套的 MIME 结构使用逗号分隔的多级索引如0,0、0,1顶层独立部件则用单个数字如1。这些索引可直接传递给imap.fetch_part的part参数用于抓取对应部件的原始内容。与 imap_content 事件数据的呼应IMAP 集成的事件数据中也包含parts字典详见 imap.markdown 的事件属性表两者的parts结构一致。也就是说即使在事件阶段没有调用imap.fetch你也可以通过trigger.event.data[parts]预览部件元数据再决定是否调用imap.fetch_part抓取某个附件。五、实战抓取全文并标记已读的完整自动化将imap.fetch与imap.seen、persistent_notification.create组合可以构建一个完整的「邮件处理流水线」自动化。以下示例来自 IMAP 集成文档它按entry_id过滤事件触发器抓取消息存入message_text标记已读最后以通知方式展示邮件主题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] }}要点解析触发器过滤event_data.entry_id确保只处理目标配置条目下的邮件防止多邮箱串扰条件过滤模板条件校验sender只处理特定发件人如infoexample.com的邮件响应变量message_text存储整个响应字典后续通过message_text[subject]取主题状态管理imap.seen在抓取后立即将消息标记为已读避免下次轮询再次触发事件。配合 imap.fetch_part 处理附件如果需要进一步解析附件可在imap.fetch之后根据parts元数据调用 imap.fetch_part。下面示例同样来自集成文档在确认部件1存在且为text/plain后抓取其内容并解码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 }} - condition: template value_template: {{ trigger.event.data[parts].get(1) }} - condition: template value_template: {{ trigger.event.data[parts][1].get(content_type) text/plain }} 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.fetch_part返回的part_data是经过编码如base64的原始数据因此通知消息中通过base64_decode过滤器解码后展示。六、进阶思路基于抓取全文的邮件解析imap.fetch的价值在于正文不再受 2048 字节限制因此特别适合正则解析型场景。IMAP 集成文档中的「关键词识别」示例展示了如何用事件数据中的text扫描主题template: - trigger: - trigger: event event_type: imap_content id: custom_event event_data: sender: no-replysmartconnect.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 %}同样的思路完全可以升级为先imap.fetch拿到不限长度的全文存入响应变量再用regex_findall_index等过滤器从长文本中提取金额、电量等结构化数据。集成文档中的「从邮件提取格式化文本」示例即采用regex_findall_index配合正文提取数值例如从能源账单邮件中提取Yesterdays Energy Use对应的 kWh 数值——这类长文本解析正是imap.fetch的典型适用场景。七、使用注意事项与事件触发器强绑定imap.fetch的典型使用模式是先由imap_content事件提供uid因此它更适合作为事件驱动的自动化/脚本步骤而不是独立定时任务响应变量作用域结果只存在响应变量中仅能在同一自动化或脚本的后续步骤使用无法跨自动化共享多条目过滤有多个 IMAP 配置条目时务必按entry/entry_id过滤防止处理错误邮箱的消息正文格式返回的text是邮件的纯文本版本HTML 邮件需依赖imap.fetch_part抓取text/html部件或由事件数据中的headers进一步处理大附件处理获取附件内容应使用imap.fetch_partimap.fetch本身只返回正文与部件元数据不返回附件二进制内容测试便捷可直接在设置 工具 动作Settings Tools Actions中搜索该动作填写字段后点击执行Perform action无需编写 YAML 即可观察实际返回结果。总结imap.fetch补全了 IMAP 集成在「事件数据正文受限」场景下的能力缺口它以消息uid为键、以响应变量为通道向自动化提供不受大小限制的邮件正文与部件元数据。掌握它之后配合imap.fetch_part抓附件、imap.seen标记已读与imap.move归档你就能把邮箱变成一个完整的自动化输入源——从「收到邮件」到「解析正文、提取数据、通知用户、归档邮件」全流程闭环。如需深入了解 IMAP 集成的配置Gmail 应用密码、搜索条件、SSL 选项、IMAP-Push 等与事件属性全表可继续阅读 IMAP 集成文档相关动作的字段定义与响应格式见 imap.fetch_part、imap.seen 与 imap.move。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考