mailinapp
Documentation menu

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ão400 { "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