# @bigbinary/neeto-email-delivery-frontend 中文文档 规范地址：https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/ 版本：1\.0\.46 npm 元数据更新时间：2026-09-21T10:49:16.910Z 中文译文更新时间：2026-11-08T02:21:13.050Z 软件包许可：UNLICENSED 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bigbinary/neeto-email-delivery-frontend 原文对照：https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/?lang=original 项目主页：https://github.com/bigbinary/neeto-email-delivery-nano ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，128 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22\.13 - 运行依赖：3 个 - peer 依赖：qs 6\.15\.2，url 0\.11\.4，yup 0\.32\.11，antd 5\.22\.1，util ^0\.12\.5，axios 1\.18\.1，ramda 0\.29\.0，react 18\.3\.1，buffer ^6\.0\.3，formik 2\.4\.6，i18next 22\.5\.1，zustand 4\.4\.2，dompurify 3\.4\.12，js-logger 1\.6\.1，react-dom 18\.3\.1，classnames 2\.5\.1，stream-http 3\.2\.0，tailwindcss ^4\.1\.17，react-helmet ^6\.1\.0，os-browserify 0\.3\.0，react-i18next 12\.3\.1，vm-browserify 1\.1\.2，@babel/runtime 7\.29\.7，react-toastify 8\.0\.2，tty-browserify 0\.0\.1，path-browserify ^1\.0\.1，https-browserify 1\.0\.0，mixpanel-browser ^2\.45\.0，react-router-dom 5\.3\.3，crypto-browserify 3\.12\.1，source-map-loader 4\.0\.1，stream-browserify ^3\.0\.0，@bigbinary/neetoui 8\.8\.3，@honeybadger-io/js 6\.10\.1，@bigbinary/neeto-cist 1\.0\.17，@honeybadger-io/react 6\.1\.25，@tanstack/react-query 5\.59\.20，@bigbinary/neeto-atoms 1\.0\.133，@bigbinary/neeto-icons 1\.20\.89，@bigbinary/neeto-molecules 5\.3\.26，@tanstack/react-query-devtools 5\.59\.20，@bigbinary/neeto-commons-frontend 4\.13\.160，@bigbinary/neeto-filters-frontend 4\.3\.45 - 首次发布：2025-11-11T19:42:37.150Z - 最新版本发布：2026-09-21T10:49:16.752Z - 近 30 天下载量：5278（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：46（近 12 个月 46 个） ## 中文简介 这个repo用于为尼托平台执行自定义的电子邮件发送功能. ## 安装 ```sh npm install @bigbinary/neeto-email-delivery-frontend ``` 也可以使用：`pnpm add @bigbinary/neeto-email-delivery-frontend`、`yarn add @bigbinary/neeto-email-delivery-frontend`、`bun add @bigbinary/neeto-email-delivery-frontend` ## README # 需要电子邮件 - 交付 - 诺 这个 `neeto-email-delivery-nano` 作为新纳米的真相来源 结构、配置、数据等. ## 目录 1. [用主机应用程序开发](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-development-with-host-application) - [发动机](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-engine) - [安装](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-installation) - [使用量](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-usage) - [前端软件包](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-frontend-package) - [安装](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-installation-1) - [发展指示](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-instructions-for-development) - [使用量](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-usage-1) 2. [自动化测试终点](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-automation-testing-endpoints) 3. [出版指令](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/#readme-instructions-for-publishing) ## 用主机应用程序开发 ### 发动机 #### 安装 1. 将此行添加到您的应用程序的 Gemfile 中 : ```ruby source "NEETO_GEM_SERVER_URL" do # ..existing gems gem 'neeto-email-delivery-engine' end ``` 2. 然后执行: ```shell bundle install ``` 3. 将此行添加到您的应用程序 `config/routes.rb` 文件 ```ruby mount NeetoEmailDeliveryEngine::Engine, at: "/neeto_email_delivery" ``` 4. 在表格中添加所需的迁移 `db/migrate` 文件夹。 运行以下 命令复制从引擎到主机应用程序的迁移. ```shell bundle exec rails neeto_email_delivery_engine:install:migrations bundle exec rails db:migrate ``` 5. 在主机中包含 Neeto 电子邮件 交付引擎 :: 交付方法选择器 应用程序( mailer.rb) ````diff class ApplicationMailer < NeetoCommonsBackend::ApplicationMailer + include NeetoEmailDeliveryEngine::DeliveryMethodSelector # ... end 6. Include NeetoEmailDeliveryEngine::HasEmailIntegrations in the host's owner model and override the `email_delivery_redirect_url` and `get_organization_id` method ```diff class Form < ApplicationRecord # ... + include NeetoEmailDeliveryEngine::HasEmailIntegrations # ... def email_delivery_redirect_url # "/admin/..." end def get_organization_id # organization_id end end ```` 7. 添加 `config/initializers/neeto_email_delivery_engine.rb` 并添加所有者 课。 示例 ```ruby NeetoEmailDeliveryEngine.owner_class = "Form" ``` 8. 覆盖 `load_owner` 基础控制器的私人方法. ```ruby # app/overrides/controllers/neeto_email_delivery_engine/base_controller_override.rb NeetoEmailDeliveryEngine::Api::V1::BaseController.class_eval do private def load_owner # @owner = current_user # OR # @owner = @organization.forms.find(params[:owner_id]) end end ``` 9. 覆盖 `send_disconnection_email` 财务报告和审定财务报表 `send_delivery_failure_email` 私人方法 - - app/overrides/service/neto email 交付 引擎/base email service override.rb (英语) `send_disconnection_email` 当账户本身变成 无法使用,例如证书被拒绝时,账户已经 运行时已断开 . `send_delivery_failure_email` 当提供者永久拒绝 单个邮件, 例如当信件超过大小限制时 。 账户 仍然可以连接和工作,所以只需要报告一个电子邮件. 在这种情况下没有退后发送:提供者给予永久拒绝 所以通过尼多的账户重新发行 又拒绝了 执行这个钩子,否则一个被拒绝的电子邮件就会被报告,并且 店主从来不知道它没有交付. 两个钩子都接收每个供应商 所以 `type` 这是其中之一 `gmail`, (中文(简体) ), `outlook` 或者说 `smtp` 每一个. `reason` 每个钩子都不同,每个钩子都有一个 形状,所以没有主机方法可以键入: - `send_disconnection_email` 总是收到一个 **符号** 分类 账户被放弃——其中之一 `:authentication_failure`, (中文(简体) ), `:authorization_revoked`, (中文(简体) ), `:invalid_configuration` 或者说 `:unknown_error`处理 它是一个检索键, 总是保留一个倒置的分支, 因为可能增加更多. - `send_delivery_failure_email` 总是得到提供者自己的 **字符串**, (中文(简体) ), 例如 `"552 5.3.4 Message size exceeds fixed maximum message size"`这是 打算逐字向账户所有者显示;它是他们自己的提供者 描述他们自己的信息,而不是尼托基础设施的细节. ### 失败如何分类 每个供应商都会把故障分到三个桶里 只有中间一个 销毁账户. | 弹夹 | SMTP 软件 | 邮件 | 展望 | | --- | --- | --- | --- | | 瞬间——再审,账号未受影响 | 4x (中文(简体) )`Net::SMTPServerBusy`),超时 | 429和403份配额答复 | 429, 5xx, 瞬间信号刷新故障 | | 账户无法使用 - **断开** | 53个(`Net::SMTPAuthenticationError`,无效的 SSL 配置 | 第401和403段 `PERMISSION_DENIED` 编号 : `failedPrecondition` 未启用邮件服务 | 页:1, `invalid_grant` 刷新时 | | 消息被拒绝——报告,账户存续 | 其他 5xx (中文(简体) )`Net::SMTPFatalError`(中文(简体) ) | 其他 4xx,例如,信息大小过大或收件人畸形 | `NON_DISCONNECTION_ERROR_CODES`,比如说. `ErrorMessageSizeExceeded` | 默认比表格更重要 。 未识别出故障即视为 信件级别问题,而不是账户级别问题,因为删除工作 合并对客户来说比报告一个失败的电子邮件要昂贵得多. 在账户一级列表中有意添加;不要让任何东西落入其中 无意中. ```ruby NeetoEmailDeliveryEngine::BaseEmailService.class_eval do private def send_disconnection_email(integrable, organization_id, type, reason: nil) # Call your mailer logic # type: gmail, outlook, smtp # reason: why the account was disconnected, e.g. :authentication_failure # DisconnectionMailer # .with(organization_id: organization_id) # .send_email(user: integrable, type:, reason:) # .deliver_later end def send_delivery_failure_email(integrable, organization_id, type, reason: nil) # Call your mailer logic # type: gmail, outlook, smtp # reason: the rejection reported by the provider, e.g. # "552 5.3.4 Message size exceeds fixed maximum message size" # DeliveryFailureMailer # .with(organization_id: organization_id) # .send_email(user: integrable, type:, reason:) # .deliver_later end end ``` 10. 在应用程序中添加邮件枪入侵配置. rb ```ruby config.action_mailbox.ingress = :mailgun ``` 11. 添加 `:gmail` 财务报告和审定财务报表 `:outlook` 到自定义( o) 配置/ 初始化器/ extend user omniauth. rb. 12. 以下env变量需要添加到主机应用程序中. ``` GOOGLE_OAUTH_CLIENT_ID GOOGLE_OAUTH_CLIENT_SECRET MICROSOFT_OAUTH_CLIENT_ID MICROSOFT_OAUTH_CLIENT_SECRET SPARKPOST_SENDING_DOMAINS_KEY ## The following are needed, but they should already be present in the host application. So ensure that they are present. APP_LOCAL_TO_INTERNET_PROXY_URL CONNECT_PRIVATE_KEY CONNECT_PUBLIC_KEY MAILGUN_INGRESS_SIGNING_KEY (needed for our custom logic to verify the Outlook account.) ``` 13. 在秘密中 yml 添加 ``` sparkpost: sending_domains_key: <%= ENV['SPARKPOST_SENDING_DOMAINS_KEY'] %> sending_domains_user_name: SMTP_Injection sending_domains_address: smtp.sparkpostmail.com ``` 14. 确保域 `email.com` (生产)和 `email.net` 在Mailgun中正确设置( stage)以接受 收到的邮件 例:对NeetoForm来说,这将是需要formemail.com (制作)和需要formemail.net (stage). 15. 添加以下内容到应用程序Mailbox ```ruby routing /neetoemaildelivery/i => "neeto_email_delivery_engine/inbound" ``` 16. 覆盖 `skip_rate_limits?` 页:1 `NeetoEmailPipelineEngine::MailDeliveryJob` 如果用户配置了SMTP集成,则跳过速率限制. ```ruby # app/overrides/neeto_email_pipeline_engine/jobs/mail_delivery_job_override.rb NeetoEmailPipelineEngine::MailDeliveryJob.class_eval do private def skip_rate_limits? is_smtp_email_job? end def is_smtp_email_job? return false if params[:delivery_account].blank? account_klass, account_id = params[:delivery_account].values_at(:klass, :id) delivery_account = account_klass.constantize.find_by(id: account_id) delivery_account.present? && delivery_account.is_a?(NeetoEmailDeliveryEngine::SmtpAccount) && delivery_account.active? end end ``` ### 前端软件包 #### 安装 1. 添加数据 `neeto-email-delivery-frontend` 软件包到 `package.json` ```shell yarn add @bigbinary/neeto-email-delivery-frontend ``` ### 发展指示 检查 [前端软件包开发指南](https://neeto-engineering.neetokb.com/p/a-d34cb4b0) 用于开发前端软件包的分步指令. #### 使用量 ##### 导出组件 ###### 电子邮件传送Screen | Prop | 类型 | 说明 | | --- | --- | --- | | `canManageIntegrations` | 布尔 | 此特性的授权/许可检查 . | | `ownerId` | uuid/字符串 | 车主的身份证. | | `indexRoute` | 字符串 | 电子邮件发送页面索引路由 . | | `ownDomainSetupRoute` | 字符串 | SparkPoost"Own Domain"设置组件的嵌入路由. | | `ownDomainVerifyRoute` | 字符串 | SparkPoost"验证域"组件的已嵌入路由 . | ###### Sparkpost 域设置 | Prop | 类型 | 说明 | | --- | --- | --- | | `canManageIntegrations` | 布尔 | 此特性的授权/许可检查 . | | `ownerId` | uuid/字符串 | 车主的身份证. | | `alreadyVerifiedRoute` | 字符串 | “ 已核实” 页面的路径; 通常为电子邮件发送索引 . | | `verifyRoute` | 字符串 | 显示 DKIM 记录的校验页面的路径 . | | `onCancelRoute` | 字符串 | 取消时重定向用户的路线;一般是电子邮件发送索引. | ###### Sparkpost 域认证 | Prop | 类型 | 说明 | | --- | --- | --- | | `canManageIntegrations` | 布尔 | 此特性的授权/许可检查 . | | `ownerId` | uuid/字符串 | 车主的身份证. | | `emailDeliveryIndexRoute` | 字符串 | 电子邮件发送页面索引路由 . | ## 火花站验证的业务逻辑 - 如果域未在 Sparkpost 上创建 - 在火花点上创建域 - 向用户提交 DKIM 值, 并要求用户将其添加到 DNS 中 - 出示一个验证按钮. - 关于核查,我们给NeetoTower发出API呼叫,有域和当前 组织. - 如果在 Sparkpost 上创建了域而未验证, 那么 - 向用户提交 DKIM 值, 并要求用户将其添加到 DNS 中 - 出示一个验证按钮. - 关于核查,我们给NeetoTower发出API呼叫,有域和当前 组织. - 如果在 Sparkpost 上创建并验证域名, 那么( 新流量) - 给 NeetoTower 打电话检查域名 + 当前组织 guid 记录是存在的. - 如果来自 NeetoTower 的回复表示域名 + 当前组织 guid 已存在,然后自动批准域. - 如果来自 NeetoTower 的回复表示域名 + 当前组织 guid 不存在,那么 - 显示自定义的 TXT 值并请求用户将其添加到他们的 DNS 中. - 显示检查以上 TXT 值的验证按钮 . - 关于核查,我们给NeetoTower发出API呼叫,有域和当前 组织. ## 火花站域状态 - 待定 -- -- 火花站域创建时的默认状态 . - sp dkim 已校验 - 域名的 DKIM 记录已在 Sparkpost 中被校验 . - sp dkim 未验证 - 域名的 DKIM 记录尚未被校验 火花点. - 失败 - 当任何用于校验的 Sparkpost API 失败时失败状态 . - txt 未验证 - 当一个域被验证为 不同的组织。 我们存储域+组织映射到 涅盘多尔. 如果 NeetoTower 中没有域+组织映射 但是域名在Sparkpost上被验证 然后我们用这个状态来表示 该域需要通过验证 TXT 记录来进一步验证。 如果 域+组织映射已经存在于 NeetoTower, 然后我们直接 标记域为活动. - 活动 - 最终状态。 如果活动, 那么我们将允许通过 此域. ## 展望一体化流程 确保 `MAILGUN_INGRESS_SIGNING_KEY` 环境变量设置在 主机应用程序. 这是核查《展望》账户所需的. 1. **从 UI 连接展望** - 用户点击主机应用程序中的"Connect Outlook"动作. - 引擎将用户重定向到 Microsoft OAuth 使用 `User.Read`, (中文(简体) ), `Mail.Send`,以及 `offline_access` 范围,以便我们能发送电子邮件和 刷新符号,不用换回. 2. **存储 Outlook 账户并发送校验邮件** - 在OAuth成功回电后, `NeetoEmailDeliveryEngine::Integrations::Outlook::ConnectService` 创建 或更新一个 `OutlookAccount` 并确定其地位: `inactive`。 。 。 . - 服务生成一个 `test_email_token`并存于帐中 元数据(以及时间戳和主题),并通过 `NeetoEmailDeliveryEngine::Outlook::SendEmailService` 使用微软 图 `sendMail` API 到生成的验证地址, 如 `outlook.neetoemaildelivery@email.(com|net)`。 。 。 . 3. **入境核查处理** - 输入核查地址的电子邮件由 `NeetoEmailDeliveryEngine::InboundMailbox`。 。 。 . - 该信箱按收件人和 主题,取出 `test_email_token` 从主体,并找到 相应 `OutlookAccount`。 。 。 . - 如果邮件来自合法用户邮箱,则账户不是 已激活,邮箱将账户状态更新到 `active`如果 发送者看起来像一个Outlook 阴影账户(例如:. `outlook_...@outlook.com`,邮箱将账户标记为 `shadow_account` 并标记为 `forbidden` 而不是启动它. ## 断开电子邮件 如果电子邮件发送失败 使用 Gmail/ Outlook 集成, 我们 连接集成并发送电子邮件。 为了定制电子邮件 主机应用程序需要添加一个覆盖,以便控制 寄来者. 覆盖上述安装第9步中提及的base email service.rb. ## 自动化测试终点 该引擎暴露了测试终点 `/neeto_email_delivery/api/v1/testing` 用于自动化测试。 他们让 测试连接 Gmail/ Outlook 并校验没有浏览器 OAuth 的发送邮件 流动,在生产中被禁用。 参见 [测试终点指南](https://npmcn.com/package/%40bigbinary/neeto-email-delivery-frontend/docs/email_delivery_testing_endpoints.md) 联 合 国 请求/回复形状和获取刷新符号的指示. ``` ## Instructions for Publishing Consult the [building and releasing packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages) guide for details on how to publish.. ``` ## 常见问题 ### @bigbinary/neeto-email-delivery-frontend 是什么？ 这个repo用于为尼托平台执行自定义的电子邮件发送功能\. ### 如何安装 @bigbinary/neeto-email-delivery-frontend？ 在项目目录运行 npm install @bigbinary/neeto-email-delivery-frontend，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：qs（6\.15\.2）、url（0\.11\.4）、yup（0\.32\.11）、antd（5\.22\.1）、util（^0\.12\.5）、axios（1\.18\.1）、ramda（0\.29\.0）、react（18\.3\.1）、buffer（^6\.0\.3）、formik（2\.4\.6）、i18next（22\.5\.1）、zustand（4\.4\.2）、dompurify（3\.4\.12）、js-logger（1\.6\.1）、react-dom（18\.3\.1）、classnames（2\.5\.1）、stream-http（3\.2\.0）、tailwindcss（^4\.1\.17）、react-helmet（^6\.1\.0）、os-browserify（0\.3\.0）、react-i18next（12\.3\.1）、vm-browserify（1\.1\.2）、@babel/runtime（7\.29\.7）、react-toastify（8\.0\.2）、tty-browserify（0\.0\.1）、path-browserify（^1\.0\.1）、https-browserify（1\.0\.0）、mixpanel-browser（^2\.45\.0）、react-router-dom（5\.3\.3）、crypto-browserify（3\.12\.1）、source-map-loader（4\.0\.1）、stream-browserify（^3\.0\.0）、@bigbinary/neetoui（8\.8\.3）、@honeybadger-io/js（6\.10\.1）、@bigbinary/neeto-cist（1\.0\.17）、@honeybadger-io/react（6\.1\.25）、@tanstack/react-query（5\.59\.20）、@bigbinary/neeto-atoms（1\.0\.133）、@bigbinary/neeto-icons（1\.20\.89）、@bigbinary/neeto-molecules（5\.3\.26）、@tanstack/react-query-devtools（5\.59\.20）、@bigbinary/neeto-commons-frontend（4\.13\.160）、@bigbinary/neeto-filters-frontend（4\.3\.45）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @bigbinary/neeto-email-delivery-frontend 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bigbinary/neeto-email-delivery-frontend 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @bigbinary/neeto-email-delivery-frontend 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.13。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @bigbinary/neeto-email-delivery-frontend 可以商用吗？ @bigbinary/neeto-email-delivery-frontend 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @bigbinary/neeto-email-delivery-frontend 的下载量有多少？ 根据 npm 官方下载统计，@bigbinary/neeto-email-delivery-frontend 在 2026/10/08 – 2026/11/06 这 30 天内被下载 5,278 次，日均约 176 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bigbinary/neeto-email-delivery-frontend 还在维护吗？ 最新版本 1\.0\.46 发布于 2026/09/21（1 个月前）；至今共发布 46 个版本，其中过去 12 个月发布了 46 个；首次发布于 2025/11/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。