mailinapp
Documentation menu

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, altrimenti400 { "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