Documentación Referencia
Referencia del SDK
Consulta opciones de montaje, ajustes en vivo, métodos, callbacks y campos del documento.
En esta página
mount(target, options)
mount(target, options) devuelve una EditorInstance de forma síncrona. target es un HTMLElement existente o un selector CSS. Una configuración inválida lanza un error.
| Opción | Uso |
|---|---|
| editorKey | Clave pública obligatoria. Resuelve el espacio de cliente y la configuración guardada. |
| userId / organizationId | Espacios de nombres estables de tu aplicación. Usa userId explícito; organizationId es opcional. |
| emailDocument | Sobre versionado con contenido inicial, asunto y preencabezado. |
| document / subject / preheader | Contenido y metadatos sin envolver; se usan en lugar de emailDocument. |
| draftId | Reanuda un borrador alojado; no lo combines con contenido o metadatos iniciales. |
| editorConfig | Configuración base bajo las preferencias explícitas. Las restricciones del servicio siguen vigentes. |
| mode | edit, readonly, preview, previewDesktop o previewMobile. Requiere el SDK 0.1.7 y un editor alojado compatible. |
| theme / locale | Apariencia del editor e idioma de interfaz. |
| mergeTags | Etiquetas: id, label, token, kind (text o url); description y sampleValue opcionales. |
| allowedBlocks | ID de bloques de la paleta. Omite para usar los del panel; [] oculta todas las opciones. |
| customBlocks | Array de definiciones versionadas: id, version, label, defaultProps, controls, render; iconSvg opcional. Disponible al montar, en editorConfig, en React y mediante actualizaciones en vivo. |
| displayConditions | Reglas de diseño: id, label, before, after; description y category opcionales. |
| enableTestEmail | Activado por defecto. false oculta el botón de prueba; admite editorConfig y cambios en vivo. Tu aplicación puede conservar su propio envío. |
| Feature flags | Consulta las opciones de funciones más abajo. Se mantienen las restricciones del panel. |
updateConfig(config)
Ajustes en vivo: mode, theme, locale, mergeTags, displayConditions, customBlocks, allowedBlocks, enableTemplates, enableAutosave, enableOrganizationBlocks, enableEmailAudit, enableTestEmail, enableAi.
La clave, la identidad, el contenido inicial y draftId requieren otro montaje. React sigue las mismas reglas.
Modos del editor
| Modo | Comportamiento |
|---|---|
| edit | Edición normal (predeterminado). |
| readonly | Paneles y barra visibles; controles desactivados. |
| preview | Vista previa con selector de escritorio/móvil. |
| previewDesktop / previewMobile | Solo la vista previa elegida, sin controles del editor. |
Métodos de la instancia
| Miembro | Resultado |
|---|---|
| ready | Promise<void>; se resuelve cuando la aplicación acepta métodos. |
| exportHTML() | Promise<EditorExport>: html, text, document, subject, preheader, mergeTags, mergeTagIssues; displayConditions, displayConditionIssues y requiresConditionEvaluation opcionales. No guarda ni envía. |
| previewTemplate() | Promise<EmailDocument> con previewHtml opcional. |
| flushAutosave() | Promise<{ draft }> tras confirmar el guardado. draft puede ser null si aún no se creó un borrador. |
| updateConfig(config) | void; actualiza preferencias compatibles en vivo. |
| destroy() | void; elimina iframe y listeners, y cancela peticiones pendientes. Se puede volver a llamar. |
Callbacks
| Callback | Cuándo usarlo |
|---|---|
| onReady() | Habilita acciones cuando el SDK confirma que la aplicación está lista. |
| onError(error) | Muestra el error. Captura aparte errores síncronos y rechazos de métodos. |
| onChange(document) | Observa solo el contenido sin el sobre completo de metadatos. |
| onDocumentChange(email) | Observa el sobre versionado. No confirma un guardado alojado. |
| onDraftChange({ draftId, revision }) | Asocia el borrador con un registro de tu aplicación. |
| onSaveStatusChange(value) | Observa status, draftId y revision. |
| onTestEmail(request) | Envía a tu backend. Devuelve una promesa que rechace si falla la entrega al proveedor. |
EmailDocument
Guarda schemaVersion, content, subject y preheader juntos. El esquema 1 es el documento base; el esquema 2 admite condiciones; el esquema 3 añade referencias, propiedades y capturas HTML validadas de bloques personalizados. previewHtml es una vista previa opcional. Abre con emailDocument.
{
"schemaVersion": 1,
"content": { "type": "doc", "content": [] },
"subject": "Your next announcement",
"preheader": "A short preview for the inbox"
}Valores del tema
| Ajuste | Valores |
|---|---|
| mode | light o dark |
| Colores | primaryColor, backgroundColor, surfaceColor, shellColor, inputColor, textColor, mutedColor, borderColor: hexadecimal de seis dígitos. |
| cornerRadius / density | 0–24 píxeles; comfortable o compact. |
| fontFamily | Inter, Arial, Georgia o system-ui. |
Opciones de funciones
| Opción | Controla |
|---|---|
| enableTemplates | Selector de plantillas. |
| enableAutosave | Borradores alojados, guardado e historial. |
| enableOrganizationBlocks | Guardado y reutilización de bloques de organización. |
| enableEmailAudit | Análisis y puntuación del contenido en vivo. |
| enableTestEmail | Botón de prueba en la barra de herramientas. |
| enableAi | Acciones de IA, según el acceso de pago y los ajustes. |
Bloques personalizados
Define bloques renderizados por tu aplicación con campos editables, esquemas automáticos o iconSvg opcional. Sustituir customBlocks actualiza el registro sin reescribir las propiedades ni capturas guardadas. La guía explica definiciones, controles, SVG, versiones y documentos de esquema 3.
Identificadores de bloques
allowedBlocks acepta: text, heading, button, image, video, gif, timer, menu, social, unsubscribe, list, html, space, divider, section, columns. Filtra herramientas de inserción; no valida ni elimina contenido existente. Incluye custom:<id> para cada bloque personalizado registrado que quieras insertar.
Estados de guardado y códigos de error
Los estados son idle, unsaved, saving, saved, failed, conflict y read-only. Conserva el editor si falla un guardado. Un callback de cambio no significa que el documento esté guardado.
EditorError extiende Error y expone code: not_ready, destroyed, reloaded, timeout, config_failed, invalid_config, autosave_disabled, export_failed o incompatible_editor. Conserva también el mensaje para dar indicaciones útiles.
El SDK espera hasta 15 segundos para ready, 20 para exportación/vista previa y 45 para flushAutosave. Un timeout no demuestra que haya fallado una escritura del servidor.