API 参考

嵌入 API 由四个接口组成——网络研讨会创建/列出、网络研讨会报名、课程开通报名,以及课程嵌入令牌铸造。全部接口都以 /api/v1 版本化,与发送 API 相同,并共用其持有者密钥鉴权方式。

身份验证

Authorization: Bearer mia_live_...

下面的每一个接口,如果密钥缺失或无效,都会返回 401 \{ "error": "Missing or invalid Authorization: Bearer <apiKey>" \}。密钥在仪表盘的开发者页面下管理——参见快速入门。

POST /api/v1/webinars

创建一场网络研讨会。accessMode 始终会被强制设为 "registration"——嵌入 API 只处理公开报名场次,永远不涉及仅限会员的直播场次。

| 字段 | 类型 | 是否必需 | 说明 | | --- | --- | --- | --- | | title | string | 是 | 会去除首尾空格;去除后为空则返回 400。 | | scheduledAt | number | 否 | Unix 毫秒时间戳。 | | courseId | string | 否 | 将该网络研讨会与一个已有课程绑定。 | | capacity | number | 否 | 如果提供,必须 >= 0。超出容量的报名会被记录为候补,而不是被拒绝。 |

返回 201 \{ "webinar": LiveSession \}。

GET /api/v1/webinars

无需请求体。返回 200 \{ "webinars": LiveSession[] \}——该账户下 accessMode: "registration" 的每一个场次;仅限会员的场次会被过滤掉。

POST /api/v1/webinars/[id]/register

为一名终端用户报名一场网络研讨会,并发送确认/候补邮件。

| 字段 | 类型 | 是否必需 | 说明 | | --- | --- | --- | --- | | email | string | 是 | 必须匹配一个基本的邮箱格式,否则返回 400 \{ "error": "A valid \email` is required" }。 | | name| string | 是 | 会去除首尾空格,最多 200 个字符,否则返回400 { "error": "A `name` is required" }`。 |

错误:如果该网络研讨会不存在或不属于你,返回 404;如果它不是 accessMode: "registration",返回 400;如果它已经结束,返回 409。

响应:

{ "status": "confirmed", "joinUrl": "https://mailinapp.com/webinar/<id>/join?token=..." }

或者,一旦达到容量上限:

{ "status": "waitlisted", "joinUrl": null }

一次已确认的报名会触发该网络研讨会的 registered 生命周期邮件;一次候补报名则始终收到朴素的候补通知,无论是否配置了绑定。

POST /api/v1/courses/[id]/enroll

为一个邮箱地址授予或撤销课程访问权限,依据的是你自己的授权判断,而不是一次 MailInApp 结账。

| 字段 | 类型 | 是否必需 | 说明 | | --- | --- | --- | --- | | email | string | 是 | 校验规则与报名接口相同;使用前会转为小写并去除首尾空格。 | | active | boolean | 否 | 默认为 true。false 表示撤销访问权限。 |

如果该课程不存在或不属于你,返回 404。响应:200 \{ "subscriberId": "...", "active": true \}。

一次全新的授权(对一个此前尚未开通权限的会员传入 active: true)会触发该课程的 enrolled 生命周期邮件。撤销访问权限永远不会代表你向终端用户发送邮件。

POST /api/v1/courses/[id]/embed-token

在重新核验该会员确实拥有权限之后,铸造一个短期有效(5 分钟)的签名令牌,用于嵌入课程门户。

| 字段 | 类型 | 是否必需 | 说明 | | --- | --- | --- | --- | | email | string | 是 | 校验规则与上面相同。 |

错误:如果该课程不存在、不属于你,或不是已发布状态,返回 404;如果该账户尚未认领 /learn/<slug> 会员门户 URL,返回 409;如果该邮箱当前未拥有权限(请先调用开通报名接口),返回 403。

响应:200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}。将你应用的 iframe 或一个新窗口重定向到 portalUrl——它会让访问者登录,并把他们带入普通的课程门户。

生命周期邮件绑定

一个课程或网络研讨会可以将其任意一个生命周期事件绑定到一个工作室项目,而不是使用平台朴素的确认文案:

| 资源 | 事件 | | --- | --- | | 课程 | enrolled、completed(为保持一致也接受 reminder,但没有自动触发条件——课程没有天然的到期日可供触发) | | 网络研讨会(LiveSession) | registered、reminder |

绑定是在仪表盘中课程/网络研讨会自己的生命周期邮件面板中设置的,而不是通过这个 API。它们会在下一次事件发生时生效,无论该事件是由嵌入 API 触发,还是由等效的仪表盘/公开表单操作触发。一个没有绑定的事件(或绑定指向一个已删除/不属于你的项目)会直接回退到今天这套朴素的邮件——这永远不会导致发送失败。

一个已绑定的事件会通过 renderSingleRecipientEmail 渲染,与发送 API 的模板模式完全一样:完整的降级引擎、互动模块,以及一个专属的已签名实时预览链接。该项目自己的 Webhook/响应跟踪也会捕获到它,归因到这个特定的生命周期事件,而不是一条已存储的联系人记录。

速率限制

每个接口都适用两个独立的上限:

每个 API 密钥: 每分钟 60 次请求。超出后,该密钥会收到 429 \{ "error": "Rate limit exceeded" \}。
每个账户的嵌入 API 配额: 你的套餐包含每个自然月可调用嵌入 API 的次数,由以上全部四个接口共享。免费版/入门版为 0,会返回 403 \{ "error": "The Embed API isn't included in your plan" \};超出付费套餐的配额会返回 429 \{ "error": "Monthly Embed API quota for your plan exceeded" \},直到配额在每月 1 日重置。

创建网络研讨会时还会额外重新核验你的直播配额(checkLiveSessionQuota)——与仪表盘自身创建流程所执行的、关于直播时长/课程数量的同一项检查——如果检查失败,会返回 403 及该检查自身的错误信息。

错误代码

| 状态码 | 含义 | | --- | --- | | 400 | JSON 格式有误,或缺少/字段无效——具体见上方各接口自己的表格。 | | 401 | 缺少或无效的 Authorization 头,或该密钥已被撤销。 | | 403 | 嵌入 API 不在你的套餐内、配额检查失败、直播配额超限,或(嵌入令牌接口)该邮箱当前未拥有权限。 | | 404 | 该网络研讨会/课程不存在,或不属于你的账户——刻意与"不存在"返回相同的响应,理由与发送 API 模板模式的 404 相同。 | | 409 | (网络研讨会)该场次已经结束。(嵌入令牌接口)该账户尚未认领会员门户 URL。 | | 429 | 超出单密钥速率限制或月度配额。 |