Logto HTTP Email 连接器用自有 Webhook 端点接管邮件发送的全流程解析【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto本篇指南基于 Logto 官方的 HTTP email 连接器文档README及其配套源码展开。该连接器允许你通过一个自定义的 HTTP APIWebhook 风格端点来发送 Logto 所需的各类邮件如注册验证、登录验证码、组织邀请等。读完本文你将掌握该连接器的配置方式endpoint与可选的authorization、请求负载payload的完整结构、2xx 响应约定对认证流程的影响以及从源码层面看请求是如何发出、错误如何归一化抛出的。连接器定位为什么需要 HTTP emailLogto 是一个构建在 OIDC 与 OAuth 2.1 之上的多租户身份认证基础设施。在用户注册、登录、重置密码等流程中系统需要向用户邮箱发送验证邮件。除了内置的 SMTP 及各类商业邮件服务连接器外Logto 还提供了 HTTP email 连接器你只需提供自己能控制的一个邮件服务 HTTP APILogto 在需要发邮件时就会以POST请求调用该 API。典型场景是你的团队已有一套内部邮件网关比如基于企业邮件系统的自建服务不想把 SMTP 凭据交给 Logto也不希望依赖第三方 SaaS 连接器。此时 HTTP email 连接器就是最直接的接入方式——Logto 只负责通知你该发一封什么类型的邮件给谁真正的投递由你的服务完成。该连接器以独立 npm 包发布包名为logto/connector-http-email见 package.json当前版本 0.4.4运行环境要求 Node.js^22.14.0核心依赖为 HTTP 客户端got ^14.0.0和校验库zod 3.24.3。前置条件一个可被 Logto 调用的 HTTP 端点要使用该连接器你需要准备两样东西一个 HTTP 端点endpointLogto 可以访问的 URL用于接收发信请求。你的邮件服务暴露该 API 后Logto 会在需要发送邮件时调用它。一个可选的授权令牌authorization如果你的端点需要鉴权可以配置一个 Authorization 头Logto 会在每次请求中带上它。文档中特别强调的一条约束见 README为避免认证流程中出现错误所配置的endpoint在收到请求后必须返回2xx 响应以告知 Logto 它已经收到了发送邮件的通知。同时需要明确投递语义Logto 收到 2xx 只代表请求已被你的服务接收不代表邮件一定投递成功。因此你应当自行监控邮件服务确保投递成功或者在你的发信 API 中加入监控及时检测投递失败。换句话说HTTP email 连接器是尽力通知模型——可靠投递的责任在你自己的邮件服务一侧。控制台配置项endpoint 与 authorization Header在 Logto 管理控制台中配置该连接器时表单字段由元数据 constant.ts 中的formItems定义共两项字段类型必填占位符示例说明endpointText是https://example.com/your-http-endpointLogto 将向该 URL 发起POST请求authorizationText否Bearer your-token随请求发送的 Authorization 头你可以在服务端校验其值authorization项的 tooltip 原文为The authorization header to be sent with the request, you can verify the value in your server.即该值原样放入请求头由你的服务端自行决定如何验证Bearer Token、API Key 等均可。配置值在运行时由 Zod 守卫做结构校验。见 types.tsexport const httpMailConfigGuard z.object({ endpoint: z.string(), authorization: z.string().optional(), });endpoint为必填字符串authorization为可选字符串。每次发送前index.ts 都会先调用validateConfig(config, httpMailConfigGuard)验证配置校验失败会抛出ConnectorErrorInvalidConfig错误码定义于 connector-kit 的 index.ts。请求负载Payload详解当 Logto 需要发送邮件时连接器会以 JSON 方式向你的端点发送如下结构即文档中的 Payload 示例{ to: foologto.io, type: SignIn, payload: { code: 123456 } }三个核心字段的完整类型定义见 connector-kit 的 passwordless.ts 中的SendMessageDatato收件人邮箱地址字符串必填type邮件模板类型取值为TemplateType枚举passwordless.ts完整取值如下SignIn—— 登录时发送验证码Register—— 注册时发送验证码ForgotPassword—— 重置密码时发送验证码OrganizationInvitation—— 组织Organization邀请Generic—— 通用场景例如控制台发送测试邮件UserPermissionValidation—— 敏感操作前的用户权限验证BindNewIdentifier—— 向已有账户绑定新的身份标识如新增邮箱/手机MfaVerification—— 多因素认证MFA验证码BindMfa—— 绑定 MFA 设备。payload模板动态变量类型为SendMessagePayload常用字段见 passwordless.tscode动态验证码将替换模板中的{{code}}占位符link动态链接将替换模板中的{{link}}占位符locale从用户请求中检测出的语言标签用于本地化优先级为ui_locales HTTPAccept-Language头 默认 enuiLocales认证请求中的原始ui_locales参数可能包含多个按偏好排序的语言标签如en-US en另外该类型允许任意额外字段Recordstring, unknown未来扩展字段不会破坏协议。附加字段ip除文档示例展示的三字段外从源码实现看请求体中还可能携带第四个字段ip。SendMessageData定义了ip?: string——触发本次消息的用户客户端 IP可被连接器用于限流、反欺诈或日志记录passwordless.ts。在 index.ts 中该字段采用条件展开json: { to, type, payload, ...(ip { ip }), }即当且仅当上游提供了 IP 时才出现在 JSON 中。对应的行为由 index.test.ts 中的测试用例固化提供了ip: 192.168.1.100时请求体包含该字段未提供时请求体不含ip属性。如果你的端点要做风控建议按可选字段处理ip不要假定它一定存在。源码解析一次发信请求的完整链路整个连接器入口是 index.ts 中导出的createHttpMailConnector它符合CreateConnectorEmailConnector工厂签名返回对象包含metadata、type: ConnectorType.Email、configGuard和核心函数sendMessage。sendMessage的完整流程如下解析入参与配置从SendMessageData中解构to、type、payload、ip若调用方未直接传入inputConfig则通过getConfig(defaultMetadata.id)连接器 ID 为http-email从存储中读取配置校验配置validateConfig(config, httpMailConfigGuard)用 Zod 校验endpoint/authorization不合法即抛InvalidConfig错误发起请求使用got.post(endpoint, ...)发送请求请求头固定包含Authorization: 你配置的 authorization 值Content-Type: application/json请求体为前述{ to, type, payload, ip? }JSON错误归一化这是该连接器在健壮性上值得注意的一点。got对非 2xx 响应会抛出HTTPError连接器捕获后会取出响应体rawBody若rawBody不是字符串抛出ConnectorError(InvalidResponse, Invalid response raw body type: ...)否则抛出ConnectorError(General, rawBody)把服务端的错误响应体原文透传给上层便于排查非 HTTP 类的异常如网络不可达、超时同样包装为ConnectorError(General, error)抛出。错误码枚举定义在 connector-kit 的 error.ts这意味着无论你的端点返回什么错误Logto 上层拿到的都是类型统一的ConnectorError认证流程可以据此给出一致的错误提示或重试策略。单元测试index.test.ts使用nock对端点打桩验证了三个关键事实初始化不抛错请求体严格匹配{to, type, payload}ip字段按提供与否决定是否出现。测试中模拟的端点配置见 mock.tsendpoint: https://example.com/your-http-endpoint、authorization: SampleToken。如何搭建与自检你的端点结合文档约定与源码实现搭建一个合规的 HTTP email 端点需要满足方法POSTContent-Type为application/json鉴权如配置了authorization校验请求头Authorization是否等于配置值格式不限如Bearer token响应成功接收并受理发信任务后返回2xx例如200或202响应体内容会被透传失败场景下进入ConnectorError(General, rawBody)因此返回可读的错误信息 JSON 字符串或文本会更有诊断价值按type分发依据type字段选择对应邮件模板把payload.code/payload.link填入模板若你的模板服务支持多语言参考payload.locale或payload.uiLocales选择语言版本可靠投递与监控如前文所述2xx 仅表示已受理。建议在端点内做异步队列 投递状态记录并针对投递失败建立告警利用ip可选如收到ip字段可纳入速率限制或异常检测。一个最小化端点伪实现Node.js 风格供理解协议用仓库本身不包含此示例// 伪代码示意协议要点非仓库内文件 app.post(/email-webhook, (req, res) { if (req.headers.authorization ! EXPECTED_TOKEN) { return res.status(401).send(unauthorized); } const { to, type, payload, ip } req.body; // to/type/payload 必有ip 可选 enqueue({ to, template: type, vars: payload, clientIp: ip }); res.status(202).json({ accepted: true }); // 必须 2xx });小结HTTP email 连接器是 Logto 邮件发送链路中自带端点方案的官方实现配置层面只需endpoint必填与authorization可选两个字段协议层面是{to, type, payload, ip?}的 JSON POST语义层面以 2xx 作为受理确认投递可靠性由你的服务负责实现层面基于got发起请求并对所有异常统一封装为ConnectorError。如果你的基础设施里已有可控的邮件网关这套机制可以让你在不引入第三方依赖的前提下把 Logto 的验证码、邀请、MFA 等全部邮件流量接管到自己的体系中。相关实现可进一步追溯connector 入口、元数据与表单定义、配置守卫、数据与模板类型 与 错误码。【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Logto HTTP Email 连接器：用自有 Webhook 端点接管邮件发送的全流程解析
Logto HTTP Email 连接器用自有 Webhook 端点接管邮件发送的全流程解析【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto本篇指南基于 Logto 官方的 HTTP email 连接器文档README及其配套源码展开。该连接器允许你通过一个自定义的 HTTP APIWebhook 风格端点来发送 Logto 所需的各类邮件如注册验证、登录验证码、组织邀请等。读完本文你将掌握该连接器的配置方式endpoint与可选的authorization、请求负载payload的完整结构、2xx 响应约定对认证流程的影响以及从源码层面看请求是如何发出、错误如何归一化抛出的。连接器定位为什么需要 HTTP emailLogto 是一个构建在 OIDC 与 OAuth 2.1 之上的多租户身份认证基础设施。在用户注册、登录、重置密码等流程中系统需要向用户邮箱发送验证邮件。除了内置的 SMTP 及各类商业邮件服务连接器外Logto 还提供了 HTTP email 连接器你只需提供自己能控制的一个邮件服务 HTTP APILogto 在需要发邮件时就会以POST请求调用该 API。典型场景是你的团队已有一套内部邮件网关比如基于企业邮件系统的自建服务不想把 SMTP 凭据交给 Logto也不希望依赖第三方 SaaS 连接器。此时 HTTP email 连接器就是最直接的接入方式——Logto 只负责通知你该发一封什么类型的邮件给谁真正的投递由你的服务完成。该连接器以独立 npm 包发布包名为logto/connector-http-email见 package.json当前版本 0.4.4运行环境要求 Node.js^22.14.0核心依赖为 HTTP 客户端got ^14.0.0和校验库zod 3.24.3。前置条件一个可被 Logto 调用的 HTTP 端点要使用该连接器你需要准备两样东西一个 HTTP 端点endpointLogto 可以访问的 URL用于接收发信请求。你的邮件服务暴露该 API 后Logto 会在需要发送邮件时调用它。一个可选的授权令牌authorization如果你的端点需要鉴权可以配置一个 Authorization 头Logto 会在每次请求中带上它。文档中特别强调的一条约束见 README为避免认证流程中出现错误所配置的endpoint在收到请求后必须返回2xx 响应以告知 Logto 它已经收到了发送邮件的通知。同时需要明确投递语义Logto 收到 2xx 只代表请求已被你的服务接收不代表邮件一定投递成功。因此你应当自行监控邮件服务确保投递成功或者在你的发信 API 中加入监控及时检测投递失败。换句话说HTTP email 连接器是尽力通知模型——可靠投递的责任在你自己的邮件服务一侧。控制台配置项endpoint 与 authorization Header在 Logto 管理控制台中配置该连接器时表单字段由元数据 constant.ts 中的formItems定义共两项字段类型必填占位符示例说明endpointText是https://example.com/your-http-endpointLogto 将向该 URL 发起POST请求authorizationText否Bearer your-token随请求发送的 Authorization 头你可以在服务端校验其值authorization项的 tooltip 原文为The authorization header to be sent with the request, you can verify the value in your server.即该值原样放入请求头由你的服务端自行决定如何验证Bearer Token、API Key 等均可。配置值在运行时由 Zod 守卫做结构校验。见 types.tsexport const httpMailConfigGuard z.object({ endpoint: z.string(), authorization: z.string().optional(), });endpoint为必填字符串authorization为可选字符串。每次发送前index.ts 都会先调用validateConfig(config, httpMailConfigGuard)验证配置校验失败会抛出ConnectorErrorInvalidConfig错误码定义于 connector-kit 的 index.ts。请求负载Payload详解当 Logto 需要发送邮件时连接器会以 JSON 方式向你的端点发送如下结构即文档中的 Payload 示例{ to: foologto.io, type: SignIn, payload: { code: 123456 } }三个核心字段的完整类型定义见 connector-kit 的 passwordless.ts 中的SendMessageDatato收件人邮箱地址字符串必填type邮件模板类型取值为TemplateType枚举passwordless.ts完整取值如下SignIn—— 登录时发送验证码Register—— 注册时发送验证码ForgotPassword—— 重置密码时发送验证码OrganizationInvitation—— 组织Organization邀请Generic—— 通用场景例如控制台发送测试邮件UserPermissionValidation—— 敏感操作前的用户权限验证BindNewIdentifier—— 向已有账户绑定新的身份标识如新增邮箱/手机MfaVerification—— 多因素认证MFA验证码BindMfa—— 绑定 MFA 设备。payload模板动态变量类型为SendMessagePayload常用字段见 passwordless.tscode动态验证码将替换模板中的{{code}}占位符link动态链接将替换模板中的{{link}}占位符locale从用户请求中检测出的语言标签用于本地化优先级为ui_locales HTTPAccept-Language头 默认 enuiLocales认证请求中的原始ui_locales参数可能包含多个按偏好排序的语言标签如en-US en另外该类型允许任意额外字段Recordstring, unknown未来扩展字段不会破坏协议。附加字段ip除文档示例展示的三字段外从源码实现看请求体中还可能携带第四个字段ip。SendMessageData定义了ip?: string——触发本次消息的用户客户端 IP可被连接器用于限流、反欺诈或日志记录passwordless.ts。在 index.ts 中该字段采用条件展开json: { to, type, payload, ...(ip { ip }), }即当且仅当上游提供了 IP 时才出现在 JSON 中。对应的行为由 index.test.ts 中的测试用例固化提供了ip: 192.168.1.100时请求体包含该字段未提供时请求体不含ip属性。如果你的端点要做风控建议按可选字段处理ip不要假定它一定存在。源码解析一次发信请求的完整链路整个连接器入口是 index.ts 中导出的createHttpMailConnector它符合CreateConnectorEmailConnector工厂签名返回对象包含metadata、type: ConnectorType.Email、configGuard和核心函数sendMessage。sendMessage的完整流程如下解析入参与配置从SendMessageData中解构to、type、payload、ip若调用方未直接传入inputConfig则通过getConfig(defaultMetadata.id)连接器 ID 为http-email从存储中读取配置校验配置validateConfig(config, httpMailConfigGuard)用 Zod 校验endpoint/authorization不合法即抛InvalidConfig错误发起请求使用got.post(endpoint, ...)发送请求请求头固定包含Authorization: 你配置的 authorization 值Content-Type: application/json请求体为前述{ to, type, payload, ip? }JSON错误归一化这是该连接器在健壮性上值得注意的一点。got对非 2xx 响应会抛出HTTPError连接器捕获后会取出响应体rawBody若rawBody不是字符串抛出ConnectorError(InvalidResponse, Invalid response raw body type: ...)否则抛出ConnectorError(General, rawBody)把服务端的错误响应体原文透传给上层便于排查非 HTTP 类的异常如网络不可达、超时同样包装为ConnectorError(General, error)抛出。错误码枚举定义在 connector-kit 的 error.ts这意味着无论你的端点返回什么错误Logto 上层拿到的都是类型统一的ConnectorError认证流程可以据此给出一致的错误提示或重试策略。单元测试index.test.ts使用nock对端点打桩验证了三个关键事实初始化不抛错请求体严格匹配{to, type, payload}ip字段按提供与否决定是否出现。测试中模拟的端点配置见 mock.tsendpoint: https://example.com/your-http-endpoint、authorization: SampleToken。如何搭建与自检你的端点结合文档约定与源码实现搭建一个合规的 HTTP email 端点需要满足方法POSTContent-Type为application/json鉴权如配置了authorization校验请求头Authorization是否等于配置值格式不限如Bearer token响应成功接收并受理发信任务后返回2xx例如200或202响应体内容会被透传失败场景下进入ConnectorError(General, rawBody)因此返回可读的错误信息 JSON 字符串或文本会更有诊断价值按type分发依据type字段选择对应邮件模板把payload.code/payload.link填入模板若你的模板服务支持多语言参考payload.locale或payload.uiLocales选择语言版本可靠投递与监控如前文所述2xx 仅表示已受理。建议在端点内做异步队列 投递状态记录并针对投递失败建立告警利用ip可选如收到ip字段可纳入速率限制或异常检测。一个最小化端点伪实现Node.js 风格供理解协议用仓库本身不包含此示例// 伪代码示意协议要点非仓库内文件 app.post(/email-webhook, (req, res) { if (req.headers.authorization ! EXPECTED_TOKEN) { return res.status(401).send(unauthorized); } const { to, type, payload, ip } req.body; // to/type/payload 必有ip 可选 enqueue({ to, template: type, vars: payload, clientIp: ip }); res.status(202).json({ accepted: true }); // 必须 2xx });小结HTTP email 连接器是 Logto 邮件发送链路中自带端点方案的官方实现配置层面只需endpoint必填与authorization可选两个字段协议层面是{to, type, payload, ip?}的 JSON POST语义层面以 2xx 作为受理确认投递可靠性由你的服务负责实现层面基于got发起请求并对所有异常统一封装为ConnectorError。如果你的基础设施里已有可控的邮件网关这套机制可以让你在不引入第三方依赖的前提下把 Logto 的验证码、邀请、MFA 等全部邮件流量接管到自己的体系中。相关实现可进一步追溯connector 入口、元数据与表单定义、配置守卫、数据与模板类型 与 错误码。【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
