Documentation Référence
Référence du SDK
Retrouvez les options de montage, réglages à chaud, méthodes, callbacks et champs du document.
Sur cette page
mount(target, options)
mount(target, options) renvoie immédiatement une EditorInstance. target désigne un HTMLElement existant ou un sélecteur CSS. Une configuration invalide lève une erreur.
| Option | Usage |
|---|---|
| editorKey | Clé publique obligatoire. Résout l’espace client et les réglages de l’éditeur. |
| userId / organizationId | Espaces de noms stables de votre application. Fournissez userId explicitement ; organizationId est facultatif. |
| emailDocument | Enveloppe versionnée contenant le contenu initial, l’objet et le préheader. |
| document / subject / preheader | Contenu et métadonnées bruts, à utiliser à la place de emailDocument. |
| draftId | Reprise d’un brouillon hébergé, sans contenu initial ni métadonnées initiales. |
| editorConfig | Configuration de base sous les préférences explicites. Les restrictions du service restent applicables. |
| mode | edit, readonly, preview, previewDesktop ou previewMobile. Nécessite le SDK 0.1.7 et un éditeur hébergé compatible. |
| theme / locale | Apparence de l’éditeur et langue de l’interface. |
| mergeTags | Variables : id, label, token, kind (text ou url) ; description et sampleValue facultatifs. |
| allowedBlocks | ID des blocs de la palette. Omettez pour les réglages du tableau de bord ; [] masque toutes les entrées. |
| customBlocks | Tableau de définitions versionnées : id, version, label, defaultProps, controls, render ; iconSvg facultatif. Disponible au montage, dans editorConfig, dans React et lors des mises à jour en direct. |
| displayConditions | Règles de mise en page : id, label, before, after ; description et category facultatifs. |
| enableTestEmail | Activé par défaut. false masque le bouton de test ; disponible dans editorConfig et les mises à jour en direct. Votre application peut conserver son propre envoi. |
| Feature flags | Voir les options de fonctionnalités ci-dessous. Les restrictions du tableau de bord restent applicables. |
updateConfig(config)
Réglages à chaud : mode, theme, locale, mergeTags, displayConditions, customBlocks, allowedBlocks, enableTemplates, enableAutosave, enableOrganizationBlocks, enableEmailAudit, enableTestEmail, enableAi.
La clé, l’identité, le contenu initial et draftId nécessitent un nouveau montage. Les mêmes règles s’appliquent à React.
Modes de l’éditeur
| Mode | Comportement |
|---|---|
| edit | Édition normale (par défaut). |
| readonly | Panneaux et barre d’outils visibles ; contrôles désactivés. |
| preview | Aperçu avec sélecteur ordinateur/mobile. |
| previewDesktop / previewMobile | Uniquement l’aperçu choisi, sans contrôles de l’éditeur. |
Méthodes de l’instance
| Membre | Résultat |
|---|---|
| ready | Promise<void> ; se résout quand l’application accepte les méthodes. |
| exportHTML() | Promise<EditorExport> : html, text, document, subject, preheader, mergeTags, mergeTagIssues ; displayConditions, displayConditionIssues et requiresConditionEvaluation facultatifs. Ne sauvegarde ni n’envoie. |
| previewTemplate() | Promise<EmailDocument> avec un previewHtml facultatif. |
| flushAutosave() | Promise<{ draft }> après confirmation de sauvegarde. draft peut être null avant la création d’un brouillon. |
| updateConfig(config) | void ; met à jour les préférences prises en charge à chaud. |
| destroy() | void ; supprime l’iframe et ses écouteurs, annule les requêtes en cours. Peut être rappelée. |
Callbacks
| Callback | Utilisation |
|---|---|
| onReady() | Activer les actions après initialisation complète avec le SDK adapté. |
| onError(error) | Afficher l’erreur. Intercepter séparément les erreurs synchrones et les rejets des méthodes. |
| onChange(document) | Observer le contenu brut uniquement, sans l’enveloppe objet/préheader. |
| onDocumentChange(email) | Observer l’enveloppe versionnée. Ce n’est pas une confirmation de sauvegarde hébergée. |
| onDraftChange({ draftId, revision }) | Associer le brouillon à un enregistrement de votre application. |
| onSaveStatusChange(value) | Observer status, draftId et revision. |
| onTestEmail(request) | Soumettre à votre backend. Retourner une promesse qui rejette si la soumission échoue. |
EmailDocument
Conservez schemaVersion, content, subject et preheader ensemble. Le schéma 1 est le document de base ; le schéma 2 prend en charge les conditions ; le schéma 3 ajoute références, propriétés et aperçus HTML validés des blocs personnalisés. previewHtml est un aperçu facultatif. Rechargez avec emailDocument.
{
"schemaVersion": 1,
"content": { "type": "doc", "content": [] },
"subject": "Your next announcement",
"preheader": "A short preview for the inbox"
}Valeurs du thème
| Réglage | Valeurs |
|---|---|
| mode | light ou dark |
| Couleurs | primaryColor, backgroundColor, surfaceColor, shellColor, inputColor, textColor, mutedColor, borderColor : hexadécimal à six chiffres. |
| cornerRadius / density | 0–24 pixels ; comfortable ou compact. |
| fontFamily | Inter, Arial, Georgia ou system-ui. |
Options de fonctionnalités
| Option | Contrôle |
|---|---|
| enableTemplates | Sélecteur de modèles. |
| enableAutosave | Brouillons hébergés, sauvegarde et historique. |
| enableOrganizationBlocks | Enregistrement et réutilisation des blocs d’organisation. |
| enableEmailAudit | Contrôles et note du contenu en direct. |
| enableTestEmail | Bouton de test dans la barre d’outils. |
| enableAi | Actions IA, selon l’accès payant et les réglages. |
Blocs personnalisés
Définissez des blocs dont votre application produit le rendu, avec champs modifiables, miniature filaire automatique ou iconSvg facultatif. Remplacer customBlocks actualise le registre sans réécrire les propriétés ni aperçus enregistrés. Le guide détaille les définitions, contrôles, SVG, versions et documents de schéma 3.
Identifiants des blocs
allowedBlocks accepte : text, heading, button, image, video, gif, timer, menu, social, unsubscribe, list, html, space, divider, section, columns. Ce réglage filtre les outils d’insertion ; il ne valide ni ne supprime le contenu existant. Ajoutez custom:<id> pour chaque bloc personnalisé enregistré à insérer.
États de sauvegarde et codes d’erreur
Les états sont idle, unsaved, saving, saved, failed, conflict et read-only. Conservez l’éditeur si une sauvegarde échoue. Un callback de changement ne signifie pas que le document est enregistré.
EditorError étend Error et expose code : not_ready, destroyed, reloaded, timeout, config_failed, invalid_config, autosave_disabled, export_failed ou incompatible_editor. Conservez aussi le message pour guider l’utilisateur.
Les délais SDK sont de 15 secondes pour ready, 20 secondes pour export/aperçu et 45 secondes pour flushAutosave. Un délai dépassé ne prouve pas l’échec d’une écriture côté serveur.