Documentação Referência
Referência do SDK
Consulte opções de montagem, configurações em tempo real, métodos, callbacks e campos do documento.
Nesta página
mount(target, options)
mount(target, options) retorna um EditorInstance de forma síncrona. target é um HTMLElement existente ou seletor CSS. Configuração inválida lança erro.
| Opção | Uso |
|---|---|
| editorKey | Chave pública obrigatória. Resolve o espaço do cliente e a configuração salva do editor. |
| userId / organizationId | Namespaces estáveis da aplicação. Prefira userId explícito; organizationId é opcional. |
| emailDocument | Envelope versionado completo de conteúdo inicial, assunto e pré-cabeçalho. |
| document / subject / preheader | Conteúdo bruto e metadados iniciais; use no lugar de emailDocument. |
| draftId | Retoma um rascunho hospedado; não combine com conteúdo ou metadados iniciais. |
| editorConfig | Configuração base abaixo das preferências explícitas de nível superior. Restrições do serviço continuam valendo. |
| mode | edit, readonly, preview, previewDesktop ou previewMobile. Exige SDK 0.1.7 e editor hospedado compatível. |
| theme / locale | Aparência e idioma da interface do editor. |
| mergeTags | Definições de variáveis: id, label, token, kind (text ou url); description e sampleValue opcionais. |
| allowedBlocks | IDs de blocos da paleta. Omita para usar padrões do painel; [] oculta todas as opções. |
| customBlocks | Array de definições versionadas: id, version, label, defaultProps, controls, render; iconSvg opcional. Aceito na montagem, em editorConfig, no React e em atualizações em tempo real. |
| displayConditions | Regras nomeadas de layout: id, label, before, after; description e category opcionais. |
| enableTestEmail | true por padrão. Defina false para ocultar o botão de teste; aceita editorConfig e atualizações em tempo real. Sua aplicação pode manter um fluxo próprio de envio. |
| Opções de recursos | Veja as preferências abaixo. Restrições do painel continuam valendo. |
updateConfig(config)
Configurações em tempo real: mode, theme, locale, mergeTags, displayConditions, customBlocks, allowedBlocks, enableTemplates, enableAutosave, enableOrganizationBlocks, enableEmailAudit, enableTestEmail, enableAi.
Chave, identidade, conteúdo inicial e draftId exigem nova montagem. O React segue as mesmas regras.
Modos do editor
| Modo | Comportamento |
|---|---|
| edit | Edição normal (padrão). |
| readonly | Painéis e barra visíveis; todos os controles desativados. |
| preview | Prévia do e-mail com alternância entre computador e celular. |
| previewDesktop / previewMobile | Apenas a prévia selecionada, sem controles do editor. |
Métodos da instância
| Membro | Resultado |
|---|---|
| ready | Promise<void>; resolve quando a aplicação aceita métodos. |
| exportHTML() | Promise<EditorExport>: html, text, document, subject, preheader, mergeTags, mergeTagIssues; displayConditions, displayConditionIssues e requiresConditionEvaluation opcionais. Não salva nem envia. |
| previewTemplate() | Promise<EmailDocument>; envelope com captura previewHtml opcional. |
| flushAutosave() | Promise<{ draft }>; aguarda confirmação de salvamento hospedado. Pode retornar draft: null antes de existir rascunho. |
| updateConfig(config) | void; atualiza preferências suportadas em tempo real. |
| destroy() | void; remove iframe e ouvintes e cancela solicitações pendentes. Pode ser chamado novamente com segurança. |
Callbacks
| Callback | Quando usar |
|---|---|
| onReady() | Ative ações depois que o SDK inicializar o editor e a aplicação estiver pronta. |
| onError(error) | Mostre um erro útil de integração. Capture separadamente erros síncronos de montagem e rejeições de métodos. |
| onChange(document) | Observe apenas o conteúdo bruto; não inclui o envelope completo de assunto e pré-cabeçalho. |
| onDocumentChange(email) | Observe o envelope versionado para persistência na aplicação. Não confirma salvamento hospedado. |
| onDraftChange({ draftId, revision }) | Associe o rascunho hospedado a um registro da sua aplicação. |
| onSaveStatusChange(value) | Observe status, draftId e revisão da persistência hospedada. |
| onTestEmail(request) | Envie ao seu backend. Retorne uma promise que rejeite se a solicitação de envio falhar. |
EmailDocument
Salve schemaVersion, content, subject e preheader juntos. Esquema 1 é o documento base; esquema 2 oferece condições; esquema 3 adiciona referências de blocos personalizados, propriedades e capturas HTML validadas. previewHtml é uma captura opcional de exibição. Reabra com emailDocument.
{
"schemaVersion": 1,
"content": { "type": "doc", "content": [] },
"subject": "Your next announcement",
"preheader": "A short preview for the inbox"
}Valores de tema
| Configuração de tema | Valores aceitos |
|---|---|
| mode | light ou dark |
| Cores | primaryColor, backgroundColor, surfaceColor, shellColor, inputColor, textColor, mutedColor, borderColor: cores hexadecimais de seis dígitos. |
| cornerRadius / density | 0–24 pixels; comfortable ou compact. |
| fontFamily | Inter, Arial, Georgia ou system-ui. |
Preferências de recursos
| Opção | Controla |
|---|---|
| enableTemplates | Seletor de modelos. |
| enableAutosave | Rascunhos hospedados, salvamento e histórico. |
| enableOrganizationBlocks | Salvamento e reutilização de blocos da organização. |
| enableEmailAudit | Verificações de conteúdo e avaliação em tempo real. |
| enableTestEmail | Botão de e-mail de teste na barra. |
| enableAi | Ações de IA, conforme acesso pago e configurações do painel. |
Blocos personalizados
Defina blocos renderizados pela aplicação com campos editáveis, esquemas automáticos de layout ou iconSvg opcional. Substituir customBlocks atualiza o registro sem reescrever propriedades ou capturas salvas. Veja o guia para contrato, controles, política SVG, versionamento e persistência do esquema 3.
IDs de blocos
allowedBlocks aceita: text, heading, button, image, video, gif, timer, menu, social, unsubscribe, list, html, space, divider, section, columns. Isso filtra a inserção; não valida nem exclui conteúdo existente. Inclua custom:<id> para cada bloco personalizado que deseja inserir.
Estados de salvamento e códigos de erro
O status de salvamento hospedado é idle, unsaved, saving, saved, failed, conflict ou read-only. Preserve o editor se o salvamento falhar; um callback de alteração não significa que salvou.
EditorError estende Error e expõe code. Trate not_ready, destroyed, reloaded, timeout, config_failed, invalid_config, autosave_disabled, export_failed e incompatible_editor. Preserve a mensagem para orientar a correção.
A prontidão do SDK espera até 15 segundos, a exportação e prévia até 20 segundos e a conclusão do salvamento até 45 segundos. Um timeout não prova que a gravação falhou no servidor.