Corsair 集成 Mailtrap从安装、API Key 认证到 49 个类型化端点的完整实战指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairMailtrap 是面向开发者的邮件测试与投递平台提供安全的沙箱收件箱Sandbox Inboxes和事务邮件发送能力。corsair-dev/mailtrap是 Corsair 官方提供的 Mailtrap 插件它把 Mailtrap 的账号、联系人、模板、发送域名、沙箱收件箱、统计等能力封装成 49 个类型安全的 API 操作并自动把慢变的业务结构同步到本地数据库方便你以多租户方式为终端用户接入其 Mailtrap 账号。读完本文你将掌握该插件的安装方式、API Key 认证与账号解析机制、全部端点清单及其风险分级、错误处理与重试策略以及本地数据同步的实体模型。插件定位为你的用户连接 MailtrapCorsair项目路径 packages/corsair的核心理念是Connect your users to their apps——让应用以多租户形式接入第三方服务。corsair-dev/mailtrap位于 packages/mailtrap正是这一理念在邮件场景下的落地你的每一个租户tenant都可以绑定自己的 Mailtrap Personal Access Token然后通过统一的tenant.mailtrap.api.*调用链操作 Mailtrap 的完整业务面而不必自己维护 OAuth、HTTP 客户端或数据缓存。从 plugin-docs.yaml 可以看到插件的官方定位displayName: Mailtrap description: Email testing and delivery platform for safe staging inboxes and transactional sending.该插件覆盖 Mailtrap 三大能力域邮件测试Testing沙箱收件箱的创建、查询、清空、标记已读、重置 SMTP 凭据以及消息列表与 HTML 正文读取事务发送与营销Sending/Marketing联系人、联系人列表、自定义字段、邮件模板、发送域名DNS 验证、抑制列表账户与统计Account/Stats账号列表、权限资源、计费用量以及按日期/域名/分类/ESP 维度聚合的发送统计。安装与接入安装包按 packages/mailtrap/README.md 的说明使用 pnpm 安装pnpm add corsair-dev/mailtrap根据 package.json该包以corsair 0.1.0和zod ^4.1.13为 peerDependencies即你的项目需要同时安装 Corsair 本体与 zodzod 用于端点输入/输出的 schema 校验。它提供 ESM 产物dist/index.js与完整 TypeScript 类型声明dist/index.d.ts安装后即可获得全程类型推导的调用体验。官方文档docs/plugins/mailtrap/overview.mdx也给出了 npm / yarn / bun 等包管理器的等价写法。注册插件在 Corsair 实例中挂载插件代码来源docs/plugins/mailtrap/overview.mdximport Database from better-sqlite3; import { createCorsair } from corsair; import { mailtrap } from corsair-dev/mailtrap; export const corsair createCorsair({ plugins: [ mailtrap(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });多租户是默认行为——通过corsair.withTenant(id)指定租户作用域后调用。Corsair 会为每个租户独立保存其 Mailtrap 凭据与本地同步数据实现账号级隔离。KEK数据加密密钥与 Hub 相关密钥的获取方式可参考 docs/quick-start.mdx 与 docs/concepts/multi-tenancy.mdx。连接租户通过 Corsair 的 connect link 机制让终端用户授权其 Mailtrap 账号代码来源docs/plugins/mailtrap/overview.mdxconst { connectUrl } await corsair.manage.connect.createLink({ plugin: mailtrap, tenantId: acme, }); // redirect the users browser to connectUrl认证机制API Key 与账号解析API Key 认证按 packages/mailtrap/README.md 的说明该插件使用API keyMailtrap Personal Access Token认证且不支持 OAuth 流程。Corsair 会在租户首次使用时提示录入凭据。在 index.ts 中认证配置声明为export const mailtrapAuthConfig { api_key: { account: [account_id] as const, }, } as const satisfies PluginAuthConfig;这表示除 token 本身外插件还维护一个名为account_id的租户级密钥。插件构造函数mailtrap()index.ts的keyBuilder会按优先级取 key显式传入的options.key优先否则从租户密钥存储读取api_key。为什么需要 account_idMailtrap 的一个 Personal Access Token 可以访问多个账号accounts因此账号 ID 是独立于 token 的第二凭据。与其他插件把第二凭据放进请求头不同Mailtrap 的账号 ID 是路径作用域的——所有业务端点都形如/api/accounts/{accountId}/...。这在 client.ts 中有明确注释佐证不带合法账号 ID 的请求会直接 404。账号解析的优先级在 endpoints/shared.ts 的resolveAccountId中实现共三级配置优先插件选项accountIdmailtrap({ accountId: 123 })存储次之读取租户已保存的account_id密钥兜底发现调用GET /api/accounts自动发现——仅当 token 只能触达唯一一个账号时才有效多账号场景必须显式配置。发现成功后该 ID 会通过set_account_id尽力持久化写入失败不阻断当前调用因为 ID 已经可用。底层请求实现所有请求都经由 client.ts 的makeMailtrapRequest发出Base URLhttps://mailtrap.io插件目录覆盖的 49 个操作全部位于该主机send.api.mailtrap.io、bulk.api.mailtrap.io、sandbox.api.mailtrap.io等专用发送主机对应的操作不在本插件目录内认证头Authorization: Bearer {token}Content-Type: application/json限流重试Mailtrap 未公开额度数字超限时仅返回裸 429 且无Retry-After头client.ts因此请求层配置了基于 429 响应的退避重试最多 3 次、初始延迟 1000ms、退避乘数 2并监听Retry-After头。全部端点清单与风险分级packages/mailtrap/README.md 列出了完整的 49 个端点Operation ID 命名规范为mailtrap.api.resource.action。每个端点都在 index.ts 中登记了风险级别Risk Level分为三类read只读查询安全write写入操作但可重放destructive不可逆操作Corsair 会对其施加额外关注如审计日志中标记[DESTRUCTIVE]。account账号操作Operation ID风险说明account.getBillingUsagemailtrap.api.account.getBillingUsageread查询账号在测试/发送/营销套餐限额下的计费用量account.getPermissionResourcesmailtrap.api.account.getPermissionResourcesread获取 token 拥有管理员权限的全部资源收件箱、项目、域名、计费、账号按层级嵌套account.listAccountsmailtrap.api.account.listAccountsread列出 token 可访问的 Mailtrap 账号contacts联系人操作Operation ID风险说明contacts.createmailtrap.api.contacts.createwrite创建联系人contacts.getmailtrap.api.contacts.getread按 id 或 email 获取联系人contacts.updatemailtrap.api.contacts.updatewrite按 id 或 email 更新联系人contacts.deletemailtrap.api.contacts.deletedestructive永久删除联系人 [DESTRUCTIVE]contacts.createEventmailtrap.api.contacts.createEventwrite记录联系人自定义事件contacts.createExportmailtrap.api.contacts.createExportwrite启动按筛选条件导出联系人的异步任务contacts.getExportmailtrap.api.contacts.getExportread查询导出任务状态与下载 URLcontacts.importmailtrap.api.contacts.importwrite批量导入联系人按 email 做 upsertcontacts.getImportmailtrap.api.contacts.getImportread查询导入任务状态contactLists联系人列表操作Operation ID风险说明contactLists.listmailtrap.api.contactLists.listread列出联系人列表contactLists.createmailtrap.api.contactLists.createwrite创建联系人列表contactLists.getmailtrap.api.contactLists.getread按 id 获取联系人列表contactLists.updatemailtrap.api.contactLists.updatewrite重命名联系人列表contactLists.deletemailtrap.api.contactLists.deletedestructive永久删除联系人列表 [DESTRUCTIVE]contactFields自定义字段操作Operation ID风险说明contactFields.listmailtrap.api.contactFields.listread列出自定义联系人字段contactFields.createmailtrap.api.contactFields.createwrite创建自定义联系人字段contactFields.getmailtrap.api.contactFields.getread按 id 获取自定义字段contactFields.updatemailtrap.api.contactFields.updatewrite更新自定义字段contactFields.deletemailtrap.api.contactFields.deletedestructive永久删除自定义字段并丢弃其在所有联系人上的存储值 [DESTRUCTIVE]suppressions抑制列表操作Operation ID风险说明suppressions.listmailtrap.api.suppressions.listread列出并可选搜索被抑制的邮箱地址emailTemplates邮件模板操作Operation ID风险说明emailTemplates.listmailtrap.api.emailTemplates.listread列出邮件模板emailTemplates.createmailtrap.api.emailTemplates.createwrite创建邮件模板emailTemplates.getmailtrap.api.emailTemplates.getread按 id 获取邮件模板emailTemplates.updatemailtrap.api.emailTemplates.updatewrite更新邮件模板emailTemplates.deletemailtrap.api.emailTemplates.deletedestructive永久删除邮件模板 [DESTRUCTIVE]sendingDomains发送域名操作Operation ID风险说明sendingDomains.listmailtrap.api.sendingDomains.listread列出发送域名sendingDomains.createmailtrap.api.sendingDomains.createwrite注册发送域名以进行 DNS 验证sendingDomains.getmailtrap.api.sendingDomains.getread按 id 获取发送域名含其 DNS 记录sendingDomains.deletemailtrap.api.sendingDomains.deletedestructive永久移除发送域名 [DESTRUCTIVE]stats发送统计操作Operation ID风险说明stats.getmailtrap.api.stats.getread获取指定日期范围的聚合发送统计stats.byDatemailtrap.api.stats.byDateread按天拆分的发送统计stats.byDomainsmailtrap.api.stats.byDomainsread按发送域名拆分的发送统计stats.byCategoriesmailtrap.api.stats.byCategoriesread按分类拆分的发送统计stats.byEspmailtrap.api.stats.byEspread按收件人邮箱服务商拆分的发送统计projects项目操作Operation ID风险说明projects.listmailtrap.api.projects.listread列出项目及其沙箱收件箱projects.getmailtrap.api.projects.getread按 id 获取项目及其收件箱projects.updatemailtrap.api.projects.updatewrite重命名项目projects.deletemailtrap.api.projects.deletedestructive永久删除项目及其全部收件箱 [DESTRUCTIVE]inboxes沙箱收件箱操作Operation ID风险说明inboxes.listmailtrap.api.inboxes.listread列出沙箱收件箱inboxes.getmailtrap.api.inboxes.getread获取收件箱属性含 SMTP 凭据inboxes.updatemailtrap.api.inboxes.updatewrite更新收件箱名称与/或邮件用户名inboxes.cleanmailtrap.api.inboxes.cleandestructive删除沙箱收件箱中的全部消息 [DESTRUCTIVE]inboxes.markAsReadmailtrap.api.inboxes.markAsReadwrite将沙箱收件箱中全部消息标记为已读inboxes.resetCredentialsmailtrap.api.inboxes.resetCredentialsdestructive重置收件箱 SMTP 凭据旧凭据立即失效 [DESTRUCTIVE]messages消息操作Operation ID风险说明messages.listmailtrap.api.messages.listread列出沙箱收件箱中的消息messages.getHtmlmailtrap.api.messages.getHtmlread获取消息的格式化 HTML 正文端点的代码组织从源码结构看端点按资源分组实现于 packages/mailtrap/endpoints 目录下account.ts、contacts.ts、contact-lists.ts、contact-fields.ts、email-templates.ts、sending-domains.ts、stats.ts、projects.ts、inboxes.ts、messages.ts、suppressions.ts并在 endpoints/index.ts 聚合导出为Account、Contacts、ContactLists等命名空间最终由 index.ts 的mailtrapEndpointsNested组装成account.listAccounts这种两级嵌套结构与 README 中的 Operation ID 一一对应。以收件箱为例endpoints/inboxes.ts每个端点都有统一的执行模式解析账号路径accountPath如/api/accounts/{id}/inboxes/{inbox_id}/clean→ 发起 HTTP 调用mailtrapCall→ 把结果写入本地缓存cacheInbox→ 通过logEventFromContext记录审计事件。inboxes.clean的实现还体现了证据边界原则由于真实清空沙箱会删除测试消息其响应形状并未实测而是依据同资源其他变更操作的形态建模为返回更新后的收件箱。错误处理与重试策略插件内置了一套完整的错误分类与重试决策逻辑定义在 packages/mailtrap/error-handlers.ts错误类别匹配条件行为CONFIGURATION_ERRORMailtrapAccountIdMissingError配置性故障重试无意义maxRetries: 0RATE_LIMIT_ERRORHTTP 429 或消息含 rate limit请求层已做 429 退避重试操作层不再重复避免两层相乘AUTH_ERRORHTTP 401 或消息含 unauthorized提示检查 tokenmaxRetries: 0PERMISSION_ERRORHTTP 403 或消息含 forbidden可能因免费套餐限制如account.getPermissionResources实测返回 403 Unavailable on your plan升级套餐才能解决不重试NOT_FOUND_ERRORHTTP 404 或消息含 not foundmaxRetries: 0VALIDATION_ERRORHTTP 422Mailtrap 的校验错误体会回显提交的邮箱或非法字段值仅记录状态码不记录错误体NETWORK_ERROR网络/ECONNREFUSED/ENOTFOUND/ETIMEDOUT/fetch failed依据操作是否幂等决定重试次数DEFAULT兜底记录未分类状态码不重试其中值得特别说明的是幂等性判断isNonIdempotenterror-handlers.ts将contacts.create、contacts.createExport、contacts.import、contactLists.create、contactFields.create、emailTemplates.create、sendingDomains.create列为不可重放操作。原因是 Corsair 重试时会整段重放端点调用而 Mailtrap 的这些 POST 路由不接受幂等键网络失败发生在服务端已提交之后会导致重复创建记录。唯一的例外是contacts.createEvent——Mailtrap 将联系人事件建模为仅追加的流且不返回可去重的标识重放最多产生一条重复日志条目而不会重复创建资源因此被排除在不可重放清单之外。endpoints.test.ts 会对照完整路由表断言该清单防止其与真实操作漂移。调用方式与本地数据同步类型化调用示例按 docs/plugins/mailtrap/overview.mdx 的示例接入租户后即可类型安全地调用const tenant corsair.withTenant(acme); // 查询计费用量 await tenant.mailtrap.api.account.getBillingUsage({}); // 创建自定义联系人字段 await tenant.mailtrap.api.contactFields.create({});每个端点的输入/输出都有 zod schema 定义index.ts 的mailtrapEndpointSchemas并在 endpoints/types.ts 中导出MailtrapEndpointInputs/MailtrapEndpointOutputs等完整类型IDE 中可直接获得参数提示。7 个同步实体插件会把慢变的结构性数据镜像到本地数据库schema/database.ts实体清单在 schema/index.ts 中登记为 schema 版本1.0.0contactsid、email、创建/更新时间、list_ids、订阅状态subscribed/unsubscribed、自定义字段键值contactListsid、namecontactFieldsid、name、merge_tag、data_typetext/number/boolean/dateemailTemplatesid、uuid、name、subject、category、HTML/文本正文、时间戳sendingDomainsid、domain_name、demo、入站/打开/点击追踪开关projectsid、nameinboxesid、name、status、email_username、project_id、domain、消息计数等。同步后的实体可通过tenant.mailtrap.db.entity.search()/.list()快速查询。设计上有两个刻意取舍源码注释明确说明消息、统计、导入/导出任务与联系人事件不做本地存储——它们属于高吞吐或持续追加型数据始终以实时视图为准收件箱实体刻意排除 SMTP 的password/username——这两项仅在 API 输出类型中提供给调用者直接使用不镜像进本地缓存与 Botpress 插件对signingSecret的处理同理。字段名沿用 Mailtrap 官方 JSON 的 snake_case 命名与线上响应一致无需 camelCase 转换层字段来源为 2026-08-17 对真实账号的实测响应。Webhooks暂无按 packages/mailtrap/README.md 的说明本插件不提供 webhook。源码也印证了这一点Mailtrap SDK 虽然导出了完整的WebhooksApi但本插件目录OSS catalog中没有任何触发器/Webhook 操作因此 index.ts 中mailtrapWebhooksNested为空对象pluginWebhookMatcher恒返回falsewebhooks 目录下仅保留租户匹配与 OAuth 租户链接解析等辅助逻辑。许可证corsair-dev/mailtrap采用Apache-2.0许可证见 packages/mailtrap/README.md 与 package.json 的license字段可自由用于商业项目。延伸阅读docs/plugins/mailtrap/api.mdx全部mailtrap.api.*操作的输入/输出类型参考docs/plugins/mailtrap/database.mdx同步实体的搜索过滤与操作符docs/plugins/mailtrap/overview.mdx安装、连接租户与示例调用docs/management/connect.mdxcreateLink 与 Hub 交付、租户连接流程docs/concepts/api-key.mdx 与 docs/concepts/multi-tenancy.mdxAPI Key 与多租户隔离机制docs/mcp-adapters/mcp-adapters.mdx把插件操作暴露为 MCP 工具供 Agent 直接调用。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Corsair 集成 Mailtrap：从安装、API Key 认证到 49 个类型化端点的完整实战指南
Corsair 集成 Mailtrap从安装、API Key 认证到 49 个类型化端点的完整实战指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairMailtrap 是面向开发者的邮件测试与投递平台提供安全的沙箱收件箱Sandbox Inboxes和事务邮件发送能力。corsair-dev/mailtrap是 Corsair 官方提供的 Mailtrap 插件它把 Mailtrap 的账号、联系人、模板、发送域名、沙箱收件箱、统计等能力封装成 49 个类型安全的 API 操作并自动把慢变的业务结构同步到本地数据库方便你以多租户方式为终端用户接入其 Mailtrap 账号。读完本文你将掌握该插件的安装方式、API Key 认证与账号解析机制、全部端点清单及其风险分级、错误处理与重试策略以及本地数据同步的实体模型。插件定位为你的用户连接 MailtrapCorsair项目路径 packages/corsair的核心理念是Connect your users to their apps——让应用以多租户形式接入第三方服务。corsair-dev/mailtrap位于 packages/mailtrap正是这一理念在邮件场景下的落地你的每一个租户tenant都可以绑定自己的 Mailtrap Personal Access Token然后通过统一的tenant.mailtrap.api.*调用链操作 Mailtrap 的完整业务面而不必自己维护 OAuth、HTTP 客户端或数据缓存。从 plugin-docs.yaml 可以看到插件的官方定位displayName: Mailtrap description: Email testing and delivery platform for safe staging inboxes and transactional sending.该插件覆盖 Mailtrap 三大能力域邮件测试Testing沙箱收件箱的创建、查询、清空、标记已读、重置 SMTP 凭据以及消息列表与 HTML 正文读取事务发送与营销Sending/Marketing联系人、联系人列表、自定义字段、邮件模板、发送域名DNS 验证、抑制列表账户与统计Account/Stats账号列表、权限资源、计费用量以及按日期/域名/分类/ESP 维度聚合的发送统计。安装与接入安装包按 packages/mailtrap/README.md 的说明使用 pnpm 安装pnpm add corsair-dev/mailtrap根据 package.json该包以corsair 0.1.0和zod ^4.1.13为 peerDependencies即你的项目需要同时安装 Corsair 本体与 zodzod 用于端点输入/输出的 schema 校验。它提供 ESM 产物dist/index.js与完整 TypeScript 类型声明dist/index.d.ts安装后即可获得全程类型推导的调用体验。官方文档docs/plugins/mailtrap/overview.mdx也给出了 npm / yarn / bun 等包管理器的等价写法。注册插件在 Corsair 实例中挂载插件代码来源docs/plugins/mailtrap/overview.mdximport Database from better-sqlite3; import { createCorsair } from corsair; import { mailtrap } from corsair-dev/mailtrap; export const corsair createCorsair({ plugins: [ mailtrap(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });多租户是默认行为——通过corsair.withTenant(id)指定租户作用域后调用。Corsair 会为每个租户独立保存其 Mailtrap 凭据与本地同步数据实现账号级隔离。KEK数据加密密钥与 Hub 相关密钥的获取方式可参考 docs/quick-start.mdx 与 docs/concepts/multi-tenancy.mdx。连接租户通过 Corsair 的 connect link 机制让终端用户授权其 Mailtrap 账号代码来源docs/plugins/mailtrap/overview.mdxconst { connectUrl } await corsair.manage.connect.createLink({ plugin: mailtrap, tenantId: acme, }); // redirect the users browser to connectUrl认证机制API Key 与账号解析API Key 认证按 packages/mailtrap/README.md 的说明该插件使用API keyMailtrap Personal Access Token认证且不支持 OAuth 流程。Corsair 会在租户首次使用时提示录入凭据。在 index.ts 中认证配置声明为export const mailtrapAuthConfig { api_key: { account: [account_id] as const, }, } as const satisfies PluginAuthConfig;这表示除 token 本身外插件还维护一个名为account_id的租户级密钥。插件构造函数mailtrap()index.ts的keyBuilder会按优先级取 key显式传入的options.key优先否则从租户密钥存储读取api_key。为什么需要 account_idMailtrap 的一个 Personal Access Token 可以访问多个账号accounts因此账号 ID 是独立于 token 的第二凭据。与其他插件把第二凭据放进请求头不同Mailtrap 的账号 ID 是路径作用域的——所有业务端点都形如/api/accounts/{accountId}/...。这在 client.ts 中有明确注释佐证不带合法账号 ID 的请求会直接 404。账号解析的优先级在 endpoints/shared.ts 的resolveAccountId中实现共三级配置优先插件选项accountIdmailtrap({ accountId: 123 })存储次之读取租户已保存的account_id密钥兜底发现调用GET /api/accounts自动发现——仅当 token 只能触达唯一一个账号时才有效多账号场景必须显式配置。发现成功后该 ID 会通过set_account_id尽力持久化写入失败不阻断当前调用因为 ID 已经可用。底层请求实现所有请求都经由 client.ts 的makeMailtrapRequest发出Base URLhttps://mailtrap.io插件目录覆盖的 49 个操作全部位于该主机send.api.mailtrap.io、bulk.api.mailtrap.io、sandbox.api.mailtrap.io等专用发送主机对应的操作不在本插件目录内认证头Authorization: Bearer {token}Content-Type: application/json限流重试Mailtrap 未公开额度数字超限时仅返回裸 429 且无Retry-After头client.ts因此请求层配置了基于 429 响应的退避重试最多 3 次、初始延迟 1000ms、退避乘数 2并监听Retry-After头。全部端点清单与风险分级packages/mailtrap/README.md 列出了完整的 49 个端点Operation ID 命名规范为mailtrap.api.resource.action。每个端点都在 index.ts 中登记了风险级别Risk Level分为三类read只读查询安全write写入操作但可重放destructive不可逆操作Corsair 会对其施加额外关注如审计日志中标记[DESTRUCTIVE]。account账号操作Operation ID风险说明account.getBillingUsagemailtrap.api.account.getBillingUsageread查询账号在测试/发送/营销套餐限额下的计费用量account.getPermissionResourcesmailtrap.api.account.getPermissionResourcesread获取 token 拥有管理员权限的全部资源收件箱、项目、域名、计费、账号按层级嵌套account.listAccountsmailtrap.api.account.listAccountsread列出 token 可访问的 Mailtrap 账号contacts联系人操作Operation ID风险说明contacts.createmailtrap.api.contacts.createwrite创建联系人contacts.getmailtrap.api.contacts.getread按 id 或 email 获取联系人contacts.updatemailtrap.api.contacts.updatewrite按 id 或 email 更新联系人contacts.deletemailtrap.api.contacts.deletedestructive永久删除联系人 [DESTRUCTIVE]contacts.createEventmailtrap.api.contacts.createEventwrite记录联系人自定义事件contacts.createExportmailtrap.api.contacts.createExportwrite启动按筛选条件导出联系人的异步任务contacts.getExportmailtrap.api.contacts.getExportread查询导出任务状态与下载 URLcontacts.importmailtrap.api.contacts.importwrite批量导入联系人按 email 做 upsertcontacts.getImportmailtrap.api.contacts.getImportread查询导入任务状态contactLists联系人列表操作Operation ID风险说明contactLists.listmailtrap.api.contactLists.listread列出联系人列表contactLists.createmailtrap.api.contactLists.createwrite创建联系人列表contactLists.getmailtrap.api.contactLists.getread按 id 获取联系人列表contactLists.updatemailtrap.api.contactLists.updatewrite重命名联系人列表contactLists.deletemailtrap.api.contactLists.deletedestructive永久删除联系人列表 [DESTRUCTIVE]contactFields自定义字段操作Operation ID风险说明contactFields.listmailtrap.api.contactFields.listread列出自定义联系人字段contactFields.createmailtrap.api.contactFields.createwrite创建自定义联系人字段contactFields.getmailtrap.api.contactFields.getread按 id 获取自定义字段contactFields.updatemailtrap.api.contactFields.updatewrite更新自定义字段contactFields.deletemailtrap.api.contactFields.deletedestructive永久删除自定义字段并丢弃其在所有联系人上的存储值 [DESTRUCTIVE]suppressions抑制列表操作Operation ID风险说明suppressions.listmailtrap.api.suppressions.listread列出并可选搜索被抑制的邮箱地址emailTemplates邮件模板操作Operation ID风险说明emailTemplates.listmailtrap.api.emailTemplates.listread列出邮件模板emailTemplates.createmailtrap.api.emailTemplates.createwrite创建邮件模板emailTemplates.getmailtrap.api.emailTemplates.getread按 id 获取邮件模板emailTemplates.updatemailtrap.api.emailTemplates.updatewrite更新邮件模板emailTemplates.deletemailtrap.api.emailTemplates.deletedestructive永久删除邮件模板 [DESTRUCTIVE]sendingDomains发送域名操作Operation ID风险说明sendingDomains.listmailtrap.api.sendingDomains.listread列出发送域名sendingDomains.createmailtrap.api.sendingDomains.createwrite注册发送域名以进行 DNS 验证sendingDomains.getmailtrap.api.sendingDomains.getread按 id 获取发送域名含其 DNS 记录sendingDomains.deletemailtrap.api.sendingDomains.deletedestructive永久移除发送域名 [DESTRUCTIVE]stats发送统计操作Operation ID风险说明stats.getmailtrap.api.stats.getread获取指定日期范围的聚合发送统计stats.byDatemailtrap.api.stats.byDateread按天拆分的发送统计stats.byDomainsmailtrap.api.stats.byDomainsread按发送域名拆分的发送统计stats.byCategoriesmailtrap.api.stats.byCategoriesread按分类拆分的发送统计stats.byEspmailtrap.api.stats.byEspread按收件人邮箱服务商拆分的发送统计projects项目操作Operation ID风险说明projects.listmailtrap.api.projects.listread列出项目及其沙箱收件箱projects.getmailtrap.api.projects.getread按 id 获取项目及其收件箱projects.updatemailtrap.api.projects.updatewrite重命名项目projects.deletemailtrap.api.projects.deletedestructive永久删除项目及其全部收件箱 [DESTRUCTIVE]inboxes沙箱收件箱操作Operation ID风险说明inboxes.listmailtrap.api.inboxes.listread列出沙箱收件箱inboxes.getmailtrap.api.inboxes.getread获取收件箱属性含 SMTP 凭据inboxes.updatemailtrap.api.inboxes.updatewrite更新收件箱名称与/或邮件用户名inboxes.cleanmailtrap.api.inboxes.cleandestructive删除沙箱收件箱中的全部消息 [DESTRUCTIVE]inboxes.markAsReadmailtrap.api.inboxes.markAsReadwrite将沙箱收件箱中全部消息标记为已读inboxes.resetCredentialsmailtrap.api.inboxes.resetCredentialsdestructive重置收件箱 SMTP 凭据旧凭据立即失效 [DESTRUCTIVE]messages消息操作Operation ID风险说明messages.listmailtrap.api.messages.listread列出沙箱收件箱中的消息messages.getHtmlmailtrap.api.messages.getHtmlread获取消息的格式化 HTML 正文端点的代码组织从源码结构看端点按资源分组实现于 packages/mailtrap/endpoints 目录下account.ts、contacts.ts、contact-lists.ts、contact-fields.ts、email-templates.ts、sending-domains.ts、stats.ts、projects.ts、inboxes.ts、messages.ts、suppressions.ts并在 endpoints/index.ts 聚合导出为Account、Contacts、ContactLists等命名空间最终由 index.ts 的mailtrapEndpointsNested组装成account.listAccounts这种两级嵌套结构与 README 中的 Operation ID 一一对应。以收件箱为例endpoints/inboxes.ts每个端点都有统一的执行模式解析账号路径accountPath如/api/accounts/{id}/inboxes/{inbox_id}/clean→ 发起 HTTP 调用mailtrapCall→ 把结果写入本地缓存cacheInbox→ 通过logEventFromContext记录审计事件。inboxes.clean的实现还体现了证据边界原则由于真实清空沙箱会删除测试消息其响应形状并未实测而是依据同资源其他变更操作的形态建模为返回更新后的收件箱。错误处理与重试策略插件内置了一套完整的错误分类与重试决策逻辑定义在 packages/mailtrap/error-handlers.ts错误类别匹配条件行为CONFIGURATION_ERRORMailtrapAccountIdMissingError配置性故障重试无意义maxRetries: 0RATE_LIMIT_ERRORHTTP 429 或消息含 rate limit请求层已做 429 退避重试操作层不再重复避免两层相乘AUTH_ERRORHTTP 401 或消息含 unauthorized提示检查 tokenmaxRetries: 0PERMISSION_ERRORHTTP 403 或消息含 forbidden可能因免费套餐限制如account.getPermissionResources实测返回 403 Unavailable on your plan升级套餐才能解决不重试NOT_FOUND_ERRORHTTP 404 或消息含 not foundmaxRetries: 0VALIDATION_ERRORHTTP 422Mailtrap 的校验错误体会回显提交的邮箱或非法字段值仅记录状态码不记录错误体NETWORK_ERROR网络/ECONNREFUSED/ENOTFOUND/ETIMEDOUT/fetch failed依据操作是否幂等决定重试次数DEFAULT兜底记录未分类状态码不重试其中值得特别说明的是幂等性判断isNonIdempotenterror-handlers.ts将contacts.create、contacts.createExport、contacts.import、contactLists.create、contactFields.create、emailTemplates.create、sendingDomains.create列为不可重放操作。原因是 Corsair 重试时会整段重放端点调用而 Mailtrap 的这些 POST 路由不接受幂等键网络失败发生在服务端已提交之后会导致重复创建记录。唯一的例外是contacts.createEvent——Mailtrap 将联系人事件建模为仅追加的流且不返回可去重的标识重放最多产生一条重复日志条目而不会重复创建资源因此被排除在不可重放清单之外。endpoints.test.ts 会对照完整路由表断言该清单防止其与真实操作漂移。调用方式与本地数据同步类型化调用示例按 docs/plugins/mailtrap/overview.mdx 的示例接入租户后即可类型安全地调用const tenant corsair.withTenant(acme); // 查询计费用量 await tenant.mailtrap.api.account.getBillingUsage({}); // 创建自定义联系人字段 await tenant.mailtrap.api.contactFields.create({});每个端点的输入/输出都有 zod schema 定义index.ts 的mailtrapEndpointSchemas并在 endpoints/types.ts 中导出MailtrapEndpointInputs/MailtrapEndpointOutputs等完整类型IDE 中可直接获得参数提示。7 个同步实体插件会把慢变的结构性数据镜像到本地数据库schema/database.ts实体清单在 schema/index.ts 中登记为 schema 版本1.0.0contactsid、email、创建/更新时间、list_ids、订阅状态subscribed/unsubscribed、自定义字段键值contactListsid、namecontactFieldsid、name、merge_tag、data_typetext/number/boolean/dateemailTemplatesid、uuid、name、subject、category、HTML/文本正文、时间戳sendingDomainsid、domain_name、demo、入站/打开/点击追踪开关projectsid、nameinboxesid、name、status、email_username、project_id、domain、消息计数等。同步后的实体可通过tenant.mailtrap.db.entity.search()/.list()快速查询。设计上有两个刻意取舍源码注释明确说明消息、统计、导入/导出任务与联系人事件不做本地存储——它们属于高吞吐或持续追加型数据始终以实时视图为准收件箱实体刻意排除 SMTP 的password/username——这两项仅在 API 输出类型中提供给调用者直接使用不镜像进本地缓存与 Botpress 插件对signingSecret的处理同理。字段名沿用 Mailtrap 官方 JSON 的 snake_case 命名与线上响应一致无需 camelCase 转换层字段来源为 2026-08-17 对真实账号的实测响应。Webhooks暂无按 packages/mailtrap/README.md 的说明本插件不提供 webhook。源码也印证了这一点Mailtrap SDK 虽然导出了完整的WebhooksApi但本插件目录OSS catalog中没有任何触发器/Webhook 操作因此 index.ts 中mailtrapWebhooksNested为空对象pluginWebhookMatcher恒返回falsewebhooks 目录下仅保留租户匹配与 OAuth 租户链接解析等辅助逻辑。许可证corsair-dev/mailtrap采用Apache-2.0许可证见 packages/mailtrap/README.md 与 package.json 的license字段可自由用于商业项目。延伸阅读docs/plugins/mailtrap/api.mdx全部mailtrap.api.*操作的输入/输出类型参考docs/plugins/mailtrap/database.mdx同步实体的搜索过滤与操作符docs/plugins/mailtrap/overview.mdx安装、连接租户与示例调用docs/management/connect.mdxcreateLink 与 Hub 交付、租户连接流程docs/concepts/api-key.mdx 与 docs/concepts/multi-tenancy.mdxAPI Key 与多租户隔离机制docs/mcp-adapters/mcp-adapters.mdx把插件操作暴露为 MCP 工具供 Agent 直接调用。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考