mailinapp
Documentation menu

Referencia de la API

Cuatro rutas componen la Embed API — creación/listado de webinars, registro a webinars, inscripción a cursos, y creación de tokens de incrustación de cursos. Todas están versionadas bajo /api/v1, igual que la API de envío, y comparten su autenticación por clave tipo bearer.

Autenticación

Authorization: Bearer mia_live_...

Una clave faltante o inválida devuelve 401 \{ "error": "Missing or invalid Authorization: Bearer <apiKey>" \} en cada ruta a continuación. Las claves se administran bajo Desarrolladores en el panel — mira la guía rápida.

POST /api/v1/webinars

Crea un webinar. accessMode siempre se fuerza a "registration" — la Embed API solo trabaja con sesiones de registro público, nunca con sesiones en vivo exclusivas para suscriptores.

| Campo | Tipo | Requerido | Notas | | --- | --- | --- | --- | | title | string | sí | Recortado; si queda vacío después de recortar devuelve 400. | | scheduledAt | number | no | Marca de tiempo Unix en ms. | | courseId | string | no | Vincula el webinar a un curso existente. | | capacity | number | no | Debe ser >= 0 si está presente. Los registros que superen la capacidad quedan en lista de espera, no se rechazan. |

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

GET /api/v1/webinars

Sin cuerpo. Devuelve 200 \{ "webinars": LiveSession[] \} — cada sesión de la cuenta con accessMode: "registration"; las sesiones exclusivas para suscriptores se filtran.

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

Registra a un usuario final para un webinar y envía el correo de confirmación/lista de espera.

| Campo | Tipo | Requerido | Notas | | --- | --- | --- | --- | | email | string | sí | Debe coincidir con un patrón básico de correo, si no 400 \{ "error": "A valid \email` is required" }. | | name| string | sí | Recortado, máximo 200 caracteres, si no400 { "error": "A `name` is required" }`. |

Errores: 404 si el webinar no existe o no es tuyo; 400 si no tiene accessMode: "registration"; 409 si ya finalizó.

Respuesta:

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

o, una vez alcanzada la capacidad:

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

Un registro confirmado dispara el correo de ciclo de vida registered del webinar; uno en lista de espera recibe el aviso plano de lista de espera sin importar ninguna vinculación.

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

Otorga o revoca el acceso a un curso para una dirección de correo, según tu propia decisión de derecho de acceso en lugar de un pago de MailInApp.

| Campo | Tipo | Requerido | Notas | | --- | --- | --- | --- | | email | string | sí | Misma validación que el registro; se pone en minúsculas y se recorta antes de usarse. | | active | boolean | no | Por defecto true. false revoca el acceso. |

404 si el curso no existe o no es tuyo. Respuesta: 200 \{ "subscriberId": "...", "active": true \}.

Un otorgamiento nuevo (active: true en un suscriptor que aún no tenía derecho de acceso) dispara el correo de ciclo de vida enrolled del curso. Revocar el acceso nunca envía correo al usuario final en tu nombre.

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

Crea un token firmado de corta duración (5 minutos) para incrustar el portal del curso, después de volver a verificar que el suscriptor realmente tiene derecho de acceso.

| Campo | Tipo | Requerido | Notas | | --- | --- | --- | --- | | email | string | sí | Misma validación que arriba. |

Errores: 404 si el curso no existe, no es tuyo, o no está published; 409 si la cuenta aún no ha reclamado una URL de membresía /learn/<slug>; 403 si este correo no tiene derecho de acceso actualmente (primero llama a enroll).

Respuesta: 200 \{ "portalUrl": "https://mailinapp.com/learn/<slug>/courses/<courseId>/embed?token=..." \}. Redirige el iframe o una ventana nueva de tu aplicación a portalUrl — inicia sesión al visitante y lo lleva al portal del curso normal.

Vinculaciones de correos de ciclo de vida

Un curso o webinar puede vincular cualquiera de sus eventos de ciclo de vida a un proyecto del estudio en lugar del texto de confirmación plano de la plataforma:

| Recurso | Eventos | | --- | --- | | Curso | enrolled, completed (reminder se acepta por paridad, sin disparo automático — los cursos no tienen una fecha límite natural contra la cual dispararlo) | | Webinar (LiveSession) | registered, reminder |

Las vinculaciones se configuran desde el propio panel Correos de ciclo de vida del curso/webinar en el panel de control, no a través de esta API. Tienen efecto en el siguiente evento sin importar si fue disparado por la Embed API o la acción equivalente del panel/formulario público. Un evento sin vinculación (o que apunta a un proyecto eliminado o ajeno) recurre directamente al correo plano de hoy — esto nunca rompe un envío.

Un evento vinculado se renderiza a través de renderSingleRecipientEmail exactamente igual que el modo de plantilla de la API de envío: motor de alternativas completo, bloques interactivos, y un enlace de vista en vivo firmado y personal. El propio seguimiento de webhook/Respuestas del proyecto también lo recoge, atribuido a ese evento de ciclo de vida específico en lugar de a una fila de contacto almacenada.

Límites de tasa

Aplican dos límites independientes, por ruta:

  • Por clave de API: 60 solicitudes/minuto. Superarlo devuelve 429 \{ "error": "Rate limit exceeded" \} para esa clave específicamente.
  • Por cuenta, cuota de la Embed API: tu plan incluye una cantidad de llamadas a la Embed API por mes calendario, compartida entre las cuatro rutas anteriores. 0 en Free/Starter devuelve 403 \{ "error": "The Embed API isn't included in your plan" \}; superar la cuota de un nivel de pago devuelve 429 \{ "error": "Monthly Embed API quota for your plan exceeded" \} hasta que se reinicia el día 1.

La creación de webinars además vuelve a verificar tu cuota de streaming en vivo (checkLiveSessionQuota) — el mismo límite de minutos de transmisión/curso que aplica el propio flujo de creación del panel — y devuelve 403 con el mensaje propio de esa verificación si falla.

Códigos de error

| Estado | Significado | | --- | --- | | 400 | JSON malformado o falta/es inválido un campo requerido — mira la tabla propia de cada ruta arriba. | | 401 | Falta el encabezado Authorization o es inválido, o la clave ha sido revocada. | | 403 | La Embed API no está en tu plan, falló la verificación de cuota, se superó la cuota de sesión en vivo, o (embed-token) el correo no tiene derecho de acceso actualmente. | | 404 | El webinar/curso no existe o no le pertenece a tu cuenta — deliberadamente la misma respuesta que "no existe", el mismo razonamiento que el 404 del modo de plantilla de la API de envío. | | 409 | (Webinar) la sesión ya finalizó. (Embed-token) la cuenta aún no ha reclamado una URL de membresía. | | 429 | Se superó el límite de tasa por clave o la cuota mensual. |

Relacionado