Referência da API

Quatro rotas compõem a Embed API — criação/listagem de webinars, inscrição em webinar, matrícula em curso e geração de embed-token de curso. Todas são versionadas sob /api/v1, assim como a Send API, e compartilham sua autenticação por chave bearer.

Autenticação

Authorization: Bearer mia_live_...

Uma chave ausente ou inválida retorna 401 \{ "error": "Missing or invalid Authorization: Bearer <apiKey>" \} em todas as rotas abaixo. As chaves são gerenciadas em Developers, no painel — veja o guia rápido.

POST /api/v1/webinars

Cria um webinar. accessMode é sempre forçado para "registration" — a Embed API só lida com sessões de inscrição pública, nunca com sessões ao vivo exclusivas para assinantes.

Campo	Tipo	Obrigatório	Notas
`title`	string	sim	Recebe trim; se ficar vazio depois do trim, retorna `400`.
`scheduledAt`	number	não	Timestamp Unix em ms.
`courseId`	string	não	Vincula o webinar a um curso existente.
`capacity`	number	não	Precisa ser `>= 0`, se informado. Inscrições que excedem a capacidade entram em lista de espera, não são rejeitadas.

Retorna 201 \{ "webinar": LiveSession \}.

GET /api/v1/webinars

Sem corpo. Retorna 200 \{ "webinars": LiveSession[] \} — toda sessão da conta com accessMode: "registration"; sessões exclusivas para assinantes são filtradas.

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

Inscreve um usuário final em um webinar e envia o e-mail de confirmação/lista de espera.

Campo	Tipo	Obrigatório	Notas
`email`	string	sim	Precisa corresponder a um padrão básico de e-mail, senão `400 \{ "error": "A valid \`email` is required" }`.
`name`	string	sim	Recebe trim, máximo de 200 caracteres, senão `400 \{ "error": "A \`name` is required" }`.

Erros: 404 se o webinar não existir ou não for seu; 400 se ele não for accessMode: "registration"; 409 se já tiver terminado.

Resposta:

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

ou, quando a capacidade é atingida:

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

Uma inscrição confirmada dispara o e-mail de ciclo de vida registered do webinar; uma em lista de espera recebe apenas o aviso padrão de lista de espera, independentemente de qualquer vinculação.

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

Concede ou revoga o acesso a um curso para um endereço de e-mail, baseado na sua própria decisão de elegibilidade, e não em um checkout do MailInApp.

Campo	Tipo	Obrigatório	Notas
`email`	string	sim	Mesma validação da inscrição; convertido para minúsculas e com trim antes do uso.
`active`	boolean	não	Usa `true` por padrão. `false` revoga o acesso.

404 se o curso não existir ou não for seu. Resposta: 200 \{ "subscriberId": "...", "active": true \}.

Uma nova concessão (active: true para um(a) assinante que ainda não tinha direito de acesso) dispara o e-mail de ciclo de vida enrolled do curso. Revogar o acesso nunca envia e-mail ao usuário final em seu nome.

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

Gera um token assinado de curta duração (5 minutos) para incorporar o portal do curso, depois de reverificar que o(a) assinante realmente tem direito de acesso.

Campo	Tipo	Obrigatório	Notas
`email`	string	sim	Mesma validação de antes.

Erros: 404 se o curso não existir, não for seu, ou não estiver published; 409 se a conta ainda não reivindicou uma URL de assinatura /learn/<slug>; 403 se este e-mail não tiver direito de acesso no momento (chame o enroll primeiro).

Resposta: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}. Redirecione o iframe do seu app, ou uma nova janela, para portalUrl — isso autentica o visitante e o leva para o portal de curso normal.

Vinculações de e-mail de ciclo de vida

Um curso ou webinar pode vincular qualquer um de seus eventos de ciclo de vida a um projeto do estúdio, em vez do texto de confirmação padrão da plataforma:

Recurso	Eventos
Curso	`enrolled`, `completed` (`reminder` aceito por paridade, sem disparo automático — cursos não têm uma data de vencimento natural para disparar um)
Webinar (`LiveSession`)	`registered`, `reminder`

As vinculações são definidas no próprio painel Lifecycle emails do curso/webinar, no painel de controle, não por esta API. Elas passam a valer no próximo evento, independentemente de ele ter sido disparado pela Embed API ou pela ação equivalente do painel/formulário público. Um evento sem vinculação (ou com uma apontando para um projeto excluído/de outra conta) volta diretamente para o e-mail simples de hoje — isso nunca quebra um envio.

Um evento vinculado é renderizado via renderSingleRecipientEmail exatamente como o modo modelo da Send API: motor de fallback completo, blocos interativos e um link de visualização ao vivo pessoal e assinado. O próprio rastreamento de webhook/Respostas do projeto também capta isso, atribuído a esse evento de ciclo de vida específico, e não a uma linha de contato armazenada.

Limites de taxa

Dois limites independentes se aplicam, por rota:

Por chave de API: 60 requisições por minuto. Excedê-lo retorna 429 \{ "error": "Rate limit exceeded" \} especificamente para aquela chave.
Por conta, cota da Embed API: seu plano inclui um número de chamadas da Embed API por mês civil, compartilhado entre as quatro rotas acima. 0 no Free/Starter retorna 403 \{ "error": "The Embed API isn't included in your plan" \}; exceder a cota de um nível pago retorna 429 \{ "error": "Monthly Embed API quota for your plan exceeded" \} até ela ser reiniciada no dia 1º.

A criação de webinar também reverifica sua cota de transmissão ao vivo (checkLiveSessionQuota) — a mesma restrição de minutos de transmissão/curso que o próprio fluxo de criação do painel aplica — e retorna 403 com a mensagem dessa própria verificação, se ela falhar.

Códigos de erro

Status	Significado
`400`	JSON malformado ou um campo obrigatório ausente/inválido — veja a própria tabela de cada rota acima.
`401`	Cabeçalho `Authorization` ausente ou inválido, ou a chave foi revogada.
`403`	Embed API não incluída no seu plano, verificação de cota falhou, cota de sessão ao vivo excedida, ou (embed-token) o e-mail não tem direito de acesso no momento.
`404`	O webinar/curso não existe ou não pertence à sua conta — deliberadamente a mesma resposta de "não existe", pelo mesmo motivo do `404` do modo modelo da Send API.
`409`	(Webinar) a sessão já terminou. (Embed-token) a conta ainda não reivindicou uma URL de assinatura.
`429`	Limite de taxa por chave ou cota mensal excedidos.

Veja também

referência da Send API — o endpoint transacional livre/modelo com o qual esta API compartilha seu modelo de autenticação.
visão geral da assinatura de aprendizado — cursos, assinantes e direito de acesso, os conceitos que as rotas de enroll/embed-token encapsulam.
Sessões ao vivo e webinars — inscrição em webinar, capacidade/lista de espera e links de acesso, os conceitos que as rotas de webinar encapsulam.