API 레퍼런스

임베드 API는 네 가지 경로로 구성됩니다 — 웨비나 생성/목록 조회, 웨비나 등록, 강좌 수강 신청, 강좌 임베드 토큰 발급입니다. 모두 Send 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 ms 타임스탬프. | | 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 | 예 | 위와 동일한 검증을 거칩니다. |

오류: 강좌가 존재하지 않거나, 자신의 것이 아니거나, published 상태가 아니면 404, 계정이 아직 /learn/<slug> 멤버십 URL을 확보하지 않았으면 409, 이 이메일이 현재 자격이 없으면 403(먼저 enroll을 호출하세요).

응답: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}. 앱의 iframe이나 새 창을 portalUrl로 리디렉션하세요 — 방문자를 로그인시키고 일반 강좌 포털로 이동시킵니다.

라이프사이클 이메일 연동

강좌나 웨비나는 플랫폼의 단순한 확인 문구 대신, 자신의 라이프사이클 이벤트를 스튜디오 프로젝트에 연동할 수 있습니다.

| 리소스 | 이벤트 | | --- | --- | | 강좌 | enrolled, completed(reminder도 대칭성을 위해 허용되지만 자동 트리거는 없습니다 — 강좌에는 이를 발동시킬 자연스러운 마감일이 없기 때문입니다) | | 웨비나(LiveSession) | registered, reminder |

연동은 이 API가 아니라 대시보드의 강좌/웨비나 자체 라이프사이클 이메일 패널에서 설정합니다. 임베드 API에 의해 트리거되었든, 이에 대응하는 대시보드/공개 폼 동작에 의해 트리거되었든 상관없이 다음 이벤트부터 적용됩니다. 연동이 없는 이벤트(또는 삭제되었거나 다른 계정의 프로젝트를 가리키는 연동)는 곧바로 오늘날의 단순한 이메일로 돌아가며, 이로 인해 발송이 실패하는 일은 없습니다.

연동된 이벤트는 Send API의 템플릿 모드와 완전히 동일하게 renderSingleRecipientEmail을 통해 렌더링됩니다 — 전체 폴백 엔진, 인터랙티브 블록, 개인용 서명된 라이브 뷰 링크가 모두 포함됩니다. 프로젝트 자체의 웹훅/응답 추적도 이를 감지하며, 저장된 연락처 행이 아니라 그 특정 라이프사이클 이벤트로 귀속됩니다.

속도 제한

경로별로 두 가지 독립적인 한도가 적용됩니다.

API 키당: 분당 60회 요청. 초과하면 해당 키에 한해 429 \{ "error": "Rate limit exceeded" \}를 반환합니다.
계정당 임베드 API 할당량: 플랜에는 달력 월 기준 임베드 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을 반환합니다.

오류 코드

| 상태 코드 | 의미 | | --- | --- | | 400 | 형식이 잘못된 JSON이거나 필수 필드가 누락/유효하지 않음 — 위의 각 경로별 표를 참고하세요. | | 401 | Authorization 헤더가 없거나 유효하지 않거나, 키가 폐기되었습니다. | | 403 | 플랜에 임베드 API가 포함되어 있지 않거나, 할당량 검사에 실패했거나, 라이브 세션 할당량을 초과했거나, (embed-token의 경우) 이메일이 현재 자격이 없습니다. | | 404 | 웨비나/강좌가 존재하지 않거나 계정 소유가 아닙니다 — Send API의 템플릿 모드 404와 동일한 이유로, 의도적으로 "존재하지 않음"과 동일한 응답을 사용합니다. | | 409 | (웨비나) 세션이 이미 종료되었습니다. (embed-token) 계정이 아직 멤버십 URL을 확보하지 않았습니다. | | 429 | 키별 속도 제한 또는 월간 할당량을 초과했습니다. |