Riferimento API

Quattro rotte compongono l'Embed API — creazione/elenco webinar, registrazione al webinar, iscrizione al corso, e generazione del token di incorporazione del corso. Tutte sono versionate sotto /api/v1, come la Send API, e condividono la sua autenticazione a chiave bearer.

Autenticazione

Authorization: Bearer mia_live_...

Una chiave mancante o non valida restituisce 401 \{ "error": "Missing or invalid Authorization: Bearer <apiKey>" \} su ogni rotta qui sotto. Le chiavi si gestiscono sotto Sviluppatori nella dashboard — vedi la guida rapida.

POST /api/v1/webinars

Crea un webinar. accessMode è sempre forzato a "registration" — l'Embed API si occupa solo di sessioni a registrazione pubblica, mai di sessioni live riservate agli abbonati.

Campo	Tipo	Obbligatorio	Note
`title`	string	sì	Ripulito dagli spazi; vuoto dopo la pulizia restituisce `400`.
`scheduledAt`	number	no	Timestamp Unix in ms.
`courseId`	string	no	Collega il webinar a un corso esistente.
`capacity`	number	no	Deve essere `>= 0` se presente. Le registrazioni oltre la capienza vengono messe in lista d'attesa, non rifiutate.

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

GET /api/v1/webinars

Nessun corpo. Restituisce 200 \{ "webinars": LiveSession[] \} — ogni sessione sull'account con accessMode: "registration"; le sessioni riservate agli abbonati vengono filtrate ed escluse.

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

Registra un utente finale per un webinar e invia l'email di conferma/lista d'attesa.

Campo	Tipo	Obbligatorio	Note
`email`	string	sì	Deve corrispondere a un pattern email di base, altrimenti `400 \{ "error": "A valid \`email` is required" }`.
`name`	string	sì	Ripulito dagli spazi, massimo 200 caratteri, altrimenti `400 \{ "error": "A \`name` is required" }`.

Errori: 404 se il webinar non esiste o non è tuo; 400 se non è accessMode: "registration"; 409 se è già terminato.

Risposta:

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

oppure, una volta raggiunta la capienza:

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

Una registrazione confermata attiva l'email di ciclo di vita registered del webinar; una in lista d'attesa riceve il semplice avviso di lista d'attesa a prescindere da qualsiasi associazione.

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

Concede o revoca l'accesso al corso per un indirizzo email, in base alla tua stessa decisione sul diritto d'accesso piuttosto che a un checkout MailInApp.

Campo	Tipo	Obbligatorio	Note
`email`	string	sì	Stessa validazione della registrazione; convertito in minuscolo e ripulito dagli spazi prima dell'uso.
`active`	boolean	no	Predefinito `true`. `false` revoca l'accesso.

404 se il corso non esiste o non è tuo. Risposta: 200 \{ "subscriberId": "...", "active": true \}.

Una nuova concessione (active: true su un abbonato che non era già autorizzato) attiva l'email di ciclo di vita enrolled del corso. Revocare l'accesso non invia mai un'email all'utente finale per tuo conto.

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

Genera un token firmato di breve durata (5 minuti) per incorporare il portale del corso, dopo aver riverificato che l'abbonato sia effettivamente autorizzato.

Campo	Tipo	Obbligatorio	Note
`email`	string	sì	Stessa validazione di cui sopra.

Errori: 404 se il corso non esiste, non è tuo, o non è published; 409 se l'account non ha ancora rivendicato un URL del portale dei membri /learn/<slug>; 403 se questa email non è attualmente autorizzata (chiama prima enroll).

Risposta: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}. Reindirizza l'iframe della tua app o una nuova finestra a portalUrl — autentica il visitatore e lo porta nel normale portale del corso.

Associazioni email di ciclo di vita

Un corso o un webinar può associare uno qualsiasi dei suoi eventi di ciclo di vita a un progetto dello Studio invece del testo di conferma semplice della piattaforma:

Risorsa	Eventi
Corso	`enrolled`, `completed` (`reminder` accettato per parità, nessuna attivazione automatica — i corsi non hanno una scadenza naturale su cui basarne una)
Webinar (`LiveSession`)	`registered`, `reminder`

Le associazioni si impostano dal pannello Email di ciclo di vita del corso/webinar stesso nella dashboard, non tramite questa API. Hanno effetto sul prossimo evento indipendentemente dal fatto che sia stato attivato dall'Embed API o dall'azione equivalente da dashboard/modulo pubblico. Un evento senza alcuna associazione (o che punta a un progetto eliminato o estraneo) ricade direttamente sull'email semplice di oggi — questo non interrompe mai un invio.

Un evento associato viene renderizzato tramite renderSingleRecipientEmail esattamente come la modalità modello della Send API: motore di fallback completo, blocchi interattivi, e un link della vista live personale e firmato. Anche il webhook/tracciamento Risposte del progetto lo intercetta, attribuito a quello specifico evento di ciclo di vita piuttosto che a una riga di contatto memorizzata.

Limiti di velocità

Si applicano due limiti indipendenti, per rotta:

Per Chiave API: 60 richieste/minuto. Superarlo restituisce 429 \{ "error": "Rate limit exceeded" \} specificamente per quella chiave.
Per account, quota dell'Embed API: il tuo piano include un numero di chiamate all'Embed API per mese di calendario, condiviso tra tutte e quattro le rotte sopra. 0 su Free/Starter restituisce 403 \{ "error": "The Embed API isn't included in your plan" \}; superare la quota di un piano a pagamento restituisce 429 \{ "error": "Monthly Embed API quota for your plan exceeded" \} finché non si azzera il giorno 1.

La creazione di webinar riverifica inoltre la tua quota di live streaming (checkLiveSessionQuota) — lo stesso limite su minuti di trasmissione/corsi applicato dal flusso di creazione della dashboard — e restituisce 403 con il messaggio proprio di quel controllo se fallisce.

Codici di errore

Stato	Significato
`400`	JSON malformato o un campo obbligatorio mancante/non valido — vedi la tabella di ogni singola rotta sopra.
`401`	Intestazione `Authorization` mancante o non valida, oppure la chiave è stata revocata.
`403`	Embed API non inclusa nel tuo piano, controllo quota fallito, quota di sessione live superata, oppure (embed-token) l'email non è attualmente autorizzata.
`404`	Il webinar/corso non esiste o non è di proprietà del tuo account — deliberatamente la stessa risposta di "non esiste", stesso ragionamento del `404` in modalità modello della Send API.
`409`	(Webinar) la sessione è già terminata. (Embed-token) l'account non ha ancora rivendicato un URL del portale dei membri.
`429`	Limite di velocità per chiave o quota mensile superati.

Vedi anche

Riferimento della Send API — l'endpoint transazionale libero/modello con cui questa API condivide il proprio modello di autenticazione.
Panoramica dell'abbonamento didattico — corsi, abbonati e diritto d'accesso, i concetti che le rotte enroll/embed-token avvolgono.
Sessioni in diretta e webinar — registrazione al webinar, capienza/lista d'attesa e link di partecipazione, i concetti che le rotte webinar avvolgono.