mailinapp
Documentation menu

APIリファレンス

埋め込みAPIは4つのルートで構成されています — ウェビナーの作成/一覧、ウェビナー登録、コース受講登録、コース埋め込みトークンの発行です。すべて送信APIと同様に/api/v1の下でバージョン管理されており、そのベアラーキー認証を共有します。

認証

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

1人のエンドユーザーをウェビナーに登録し、確認/キャンセル待ちメールを送信します。

| フィールド | 型 | 必須 | 注記 | | --- | --- | --- | --- | | 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 | 必須 | 上記と同じ検証です。 |

エラー: コースが存在しない、自分のものでない、またはpublishedでない場合は404。アカウントがまだ/learn/<slug>のメンバーシップURLを取得していない場合は409。このメールアドレスが現在権利を持っていない場合は403(まずenrollを呼び出してください)。

レスポンス: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}。自分のアプリのiframeまたは新しいウィンドウをportalUrlにリダイレクトしてください — 訪問者をサインインさせ、通常のコースポータルに到達させます。

Lifecycle email bindings

コースまたはウェビナーは、そのライフサイクルイベントのいずれかを、プラットフォームの単純な確認文言の代わりにスタジオプロジェクトに紐付けられます:

| リソース | イベント | | --- | --- | | コース | enrolled、completed(reminderは整合性のために受け付けられますが、自動的なトリガーはありません — コースには、それに対して発火させる自然な期限がないためです) | | ウェビナー(LiveSession) | registered、reminder |

紐付けは、このAPIを通してではなく、コース/ウェビナー自身のダッシュボード内のライフサイクルメールパネルから設定します。これは、埋め込みAPIによってトリガーされたか、同等のダッシュボード/公開フォームの操作によってトリガーされたかにかかわらず、次のイベントから有効になります。紐付けのないイベント(または削除済み/他アカウントのプロジェクトを指すイベント)は、そのまま現在の単純なメールにフォールバックします — これによって送信が失敗することは一切ありません。

紐付けられたイベントは、送信APIのテンプレートモードと全く同じようにrenderSingleRecipientEmailを通じてレンダリングされます: フォールバックエンジン全体、インタラクティブブロック、そして個人向けの署名付きライブビューリンクです。プロジェクト自身のWebhook/回答トラッキングもこれを捕捉しますが、保存済みの連絡先の行ではなく、その特定のライフサイクルイベントに帰属します。

Rate limits

ルートごとに、2つの独立した上限が適用されます:

  • APIキーごと: 60リクエスト/分です。これを超えると、そのキーに対してのみ429 \{ "error": "Rate limit exceeded" \}が返されます。
  • アカウントごと、埋め込みAPIクォータ: プランには、上記4つのルート全体で共有される、1カレンダー月あたりの埋め込みAPI呼び出し回数が含まれます。Free/Starterでは0のため403 \{ "error": "The Embed API isn't included in your plan" \}が返され、有料プランのクォータを超えると、1日にリセットされるまで429 \{ "error": "Monthly Embed API quota for your plan exceeded" \}が返されます。

ウェビナー作成では、さらにライブ配信のクォータ(checkLiveSessionQuota)も再チェックされます — ダッシュボード自身の作成フロー自体が課している、同じ配信分数/コースのゲートです。このチェックが失敗した場合、そのチェック自身のメッセージ付きで403が返されます。

Error codes

| ステータス | 意味 | | --- | --- | | 400 | 不正なJSON、または必須フィールドの欠落/無効です — 各ルート自身の上記の表を参照してください。 | | 401 | Authorizationヘッダーが欠落もしくは無効、またはキーが取り消されています。 | | 403 | 埋め込みAPIがプランに含まれていない、クォータチェックに失敗、ライブセッションのクォータを超過、または(embed-token)そのメールアドレスが現在権利を持っていません。 | | 404 | ウェビナー/コースが存在しない、またはあなたのアカウントが所有していません — 意図的に「存在しない」と同じレスポンスであり、送信APIのテンプレートモードの404と同じ理由によるものです。 | | 409 | (ウェビナー)セッションがすでに終了しています。(embed-token)アカウントがまだメンバーシップURLを取得していません。 | | 429 | キーごとのレート制限、または月間クォータを超過しています。 |

Related

  • 送信APIリファレンス — このAPIが認証モデルを共有する、自由形式/テンプレートのトランザクションエンドポイントです。
  • 学習メンバーシップ概要 — コース、登録者、権利判定という、enroll/embed-tokenルートがラップしている概念です。
  • ライブセッション&ウェビナー — ウェビナー登録、人数上限/キャンセル待ち、参加リンクという、ウェビナールートがラップしている概念です。