Activepieces 集成 ValidatedMails实现邮件地址实时校验与可投递性信号路由【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces本文是一份面向 Activepieces 用户的实战指南讲解如何在自动化流程中集成 ValidatedMails 邮件校验能力。文章以activepieces/piece-validatedmails这个开源 piece 的实现为准覆盖连接配置、Validate Email 动作参数、完整的响应字段契约、底层调用链与错误处理机制读完你可以直接在流程中按status分支处理新线索并根据分数、可投递性信号做路由与决策。ValidatedMails piece 是什么ValidatedMails 是一个邮件校验 API 集成 piece用于实时校验单个邮箱地址并返回一份结构一致、扁平化的响应契约适合在流程中直接用于路由、打分和下游决策。piece 的元数据定义在 入口文件展示名称为ValidatedMails归属PieceCategory.COMMUNICATION通信类声明minimumSupportedRelease: 0.36.1即至少需要 Activepieces 0.36.1 版本才能使用该 piece。从源码结构看该 piece 的组成非常精简packages/pieces/community/validatedmails/ ├── src/ │ ├── index.ts # piece 注册入口 │ └── lib/ │ ├── actions/validate-email.ts # Validate Email 动作定义 │ └── common/ │ ├── auth.ts # API Key 连接与校验 │ ├── types.ts # 响应/入参类型契约 │ └── validate-email-helpers.ts # HTTP 请求、重试与错误映射 └── README.md除内置的Validate Email动作外piece 还通过createCustomApiCallAction暴露了一个通用「Custom API Call」动作同样可在 入口文件 看到其 baseUrl 固定为https://api.validatedmails.com鉴权位置为 headers自动注入Authorization: Bearer API Key。这意味着你可以在不写代码的情况下直接调用该 API 的其他端点。典型工作流README 给出的典型场景如下以「新线索提交」作为流程触发器运行ValidatedMails → Validate Email动作根据statusvalid/invalid/unknown进行分支继续处理、拒绝或人工复核该线索。status字段是最高层的决策信号配合score置信度分数、is_valid最终有效性结论以及disposable、role、free等标志位可以构建「直接放行 / 拦截 / 转人工」的三段式路由。例如注册场景中invalid或disposable为真的地址可直接拒绝unknown的可进入二次确认流程。连接配置与认证在 Activepieces 中为 ValidatedMails 配置连接非常简单登录 ValidatedMails 控制台创建 API Key在 Activepieces 中新建连接认证方式选择API Key填入密钥保存连接。Activepieces 会立即调用GET /api-keys/me验证密钥有效性。该校验逻辑实现在 auth.ts它通过httpClient.sendRequest向https://api.validatedmails.com/api-keys/me发送GET请求携带Authorization: Bearer API Key头超时 5 秒。请求成功则返回{ valid: true }任何异常都会返回{ valid: false, error: Unauthorized: Invalid API key }从而在保存连接时即完成密钥的即时核验避免把无效密钥带入流程运行阶段。Validate Email 动作参数Validate Email动作定义在 validate-email.ts共三个输入参数参数类型必填默认值说明emailShortText是无待校验的邮箱地址dnsTimeoutMsNumber否1500DNS 超时毫秒会被钳制在 2005000 之间modeStaticDropdown是POST发起校验请求使用的 HTTP 方法POST或GET关于参数的三点实用提示DNS 超时的钳制逻辑底层实现在 validate-email-helpers.ts 的normalizeDnsTimeoutMs中未传或传入NaN时回退到默认值1500其余情况先取整再限制在MIN_DNS_TIMEOUT_MS 200与MAX_DNS_TIMEOUT_MS 5000之间。你可以通过调大该值来容忍慢 DNS 解析但不会超过 5 秒。mode 只切换 HTTP 方法POST时参数放入 JSON bodyemail与dns_timeout_msGET时参数放入 query stringemail与dns_timeout_ms。两种方式返回的数据契约完全一致选择哪种取决于你的网络环境与 API 网关约束。输入预检请求发出前会先对邮箱做trim()清洗并通过assertEmailInput检查是否包含不满足会直接抛错「Email address must contain 」避免无效输入白跑一次 API 调用。动作的aiMetadata还注明了语义该操作是只读、幂等的对同一地址重复执行返回相同结果、无副作用因此可以放心在流程中多次调用或用于重试场景。响应字段全解无论POST还是GET动作都会把 API 原始响应归一化为一个扁平、类型安全的ValidatedMailsValidationResponse对象类型定义见 types.ts归一化实现见 validate-email-helpers.ts 的toValidationOutput。完整字段如下字段类型说明is_validboolean最终有效性结论statusstring高层状态valid/invalid/unknownscorenumberAPI 返回的置信度分数reasonstring主要原因标签statestring服务商状态标签emailstring提交的邮箱normalizedstring规范化后的邮箱字符串domainstring解析出的域名部分freeboolean是否为免费邮箱服务商域名roleboolean是否为角色型邮箱如 info、salesdisposableboolean是否为一次性/临时邮箱域名accept_allboolean域名是否为 catch-all全收tagboolean是否检测到 plus-tagging如 usertagsmtp_okboolean可用时的 SMTP 信号结果syntax_okboolean语法校验结果mx_okbooleanMX 记录解析结果a_okbooleanA 记录兜底结果response_msnumber端到端 API 延迟毫秒mx_recordstring | undefined主 MX 主机可用时mx_hostsstring[]API 返回的 MX 主机列表reasonsstring[]详细原因列表trace_idstring用于支持排查的请求标识几个值得注意的实现细节status被asStatus严格归一化为三值枚举任何意外值都会回落为unknown保证流程分支逻辑永远只面对三种确定状态mx_record仅在 API 返回字符串时才填充否则为undefined可选字段在流程中引用时建议做空值处理score、response_ms等数值字段在缺失时默认补0字符串字段默认补空串mx_hosts、reasons数组默认空数组确保下游步骤拿到的是完整对象而不会因字段缺失报错trace_id建议在出现争议结果时随工单提供给 ValidatedMails 支持团队便于定位单次请求。底层请求链路与容错设计executeValidateEmailRequestvalidate-email-helpers.ts完整实现了请求发送与容错逻辑理解它有助于你预判流程在异常情况下的行为目标地址主地址https://api.validatedmails.com/validate备用地址https://api.validatedmails.com/validate/带尾部斜杠请求头统一携带Authorization: Bearer API Key与Content-Type: application/json请求超时 10 秒地址回退首次请求遇到307、308重定向、404或405端点迁移类错误时自动改用备用地址重试传输/服务端错误重试无响应网络传输失败或服务端 500错误时整个请求会再走一遍带地址回退的重试错误归一化最终失败时按 HTTP 状态映射为可读错误401→Unauthorized: Invalid API key402→Insufficient credits余额不足429→Rate limited触发限流 500→Service unavailable其他 →Request failed这套「先重试、后归一化」的设计意味着瞬时网络抖动与 API 端点变更不会直接导致流程失败而 401/402/429 这类业务性错误会以清晰文案暴露在流程运行日志中便于你定位是密钥失效、额度耗尽还是请求过于频繁。在流程中的路由实践结合 README 的示例工作流与上述字段契约一个完整的校验路由片段可以这样设计放行status为valid且score高于你的阈值、disposable为false拦截status为invalid或disposable为true临时邮箱、role为true角色邮箱B2C 场景常需拦截复核status为unknown或score处于中间区间转入人工审核队列并把trace_id、reasons一并带入工单。由于响应是扁平对象你可以直接在 Activepieces 的后续步骤中通过表达式如{{ step_1.status }}、{{ step_1.score }}引用任意字段配合分支逻辑实现上述路由无需任何自定义解析。多语言与分发该 piece 内置了完整的多语言文案de、es、fr、ja、nl、pt、zh及默认translation.json位于 i18n 目录字段展示名、动作描述与参数说明会随 Activepieces 界面语言自动切换。分发方面包名为activepieces/piece-validatedmails版本0.0.6依赖activepieces/pieces-common、activepieces/pieces-framework等工作区包见 package.json可通过 Activepieces 的 pieces 管理机制安装使用。支持如遇 API 侧问题或对校验结果有疑问可通过infovalidatedmails.com联系 ValidatedMails 官方支持沟通时建议附上响应中的trace_id与原始邮箱便于对方快速定位。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考