Documentation du SDK d’éditeur d’e-mails

Démarrage rapide

Ajoutez le chargeur, donnez à l’éditeur un élément doté d’une hauteur, puis montez-le avec votre clé publique. La clé se trouve dans votre tableau de bord, rubrique Plugin.

<div id="editor" style="height: 720px"></div>

<script src="https://customer.mailblocks.app/sdk/v1.js"></script>
<script>
  const editor = Mailblocks.mount('#editor', {
    publicKey: 'pk_live_…',
    user: { id: 'user-42' },
    design: savedDesign,            // optional: design JSON or MJML
    placeholders: [
      { label: 'Contact', items: [{ label: 'First name', value: '{{first_name}}' }] },
    ],
    onReady: ({ plan }) => console.log('Editor ready on', plan),
    onSave: ({ html, design }) => saveTemplate({ html, design }),
    onError: ({ code, message }) => console.warn(code, message),
  });
</script>

React et Vue

Le SDK n’a aucune dépendance : enveloppez-le comme n’importe quel widget, en le montant au premier rendu et en le détruisant au démontage.

import { useEffect, useRef } from 'react';

export function EmailEditor({ user, design, onSave }) {
  const element = useRef(null);

  useEffect(() => {
    const editor = window.Mailblocks.mount(element.current, {
      publicKey: process.env.NEXT_PUBLIC_MAILBLOCKS_KEY,
      user: { id: user.id, signature: user.mailblocksSignature },
      design,
      onSave,
    });

    return () => editor.destroy();
  }, []);

  return <div ref={element} style={{ height: 720 }} />;
}

Options

Seuls publicKey et user.id sont obligatoires.

Option	Type	Description
publicKey	string	La clé publique de votre licence (pk_live_…). Utilisable sans risque dans le navigateur.
user	object	{ id, signature? } identifiant la personne qui édite. L’id est pris en compte dans les utilisateurs actifs mensuels.
design	string	Un JSON de design enregistré ou un modèle MJML à ouvrir.
designId	string	Un identifiant stable pour le design, qui permet de proposer la restauration d’un brouillon non enregistré.
locale	string	Langue de l’interface : en, es, fr, de, pt, ro ou el.
placeholders	array	Balises de personnalisation, à plat ou regroupées : [{ label, items: [{ label, value, insert? }] }].
theme	object	Couleurs, polices et arrondis de l’habillage de l’éditeur. Appliqué sur les offres avec marque blanche.
storage	string \| false \| object	"mailblocks" (par défaut), false, ou { endpoints, auth } pour votre propre stockage d’images.
toolbar	object	{ save?: boolean, back?: boolean } pour afficher ou masquer les boutons de la barre d’outils.
ai	false \| object	false pour masquer le générateur IA, ou { presets, sentence, texts } pour le personnaliser.

Événements

Passez les callbacks sous la forme onReady, onSave, etc., ou abonnez-vous avec editor.on(name, callback).

ready: L’éditeur est chargé. Reçoit { plan, features, development }.
save: L’utilisateur a enregistré, ou vous avez appelé save(). Reçoit { html, design }.
change: Le design a été modifié depuis son ouverture.
error: L’éditeur n’a pas pu démarrer ou charger le design. Reçoit { code, message }.
back: L’utilisateur a cliqué sur le bouton retour.
generated: Le générateur IA a produit un modèle. Reçoit { mjml }.

Méthodes

save(): Enregistre et résout la promesse avec { html, design }.
load(): Remplace le design ouvert par un JSON de design ou un modèle MJML.
destroy(): Supprime l’éditeur et ses écouteurs d’événements.

const { html, design } = await editor.save();

editor.load(previouslySavedDesign);

const stop = editor.on('change', () => markUnsaved());
stop();

editor.destroy();

Identifiants utilisateur signés

Signez l’identifiant utilisateur avec votre clé secrète, côté serveur, et transmettez la signature. Activez « Exiger des identifiants utilisateur signés » dans votre tableau de bord pour refuser les sessions non signées. Ne mettez jamais la clé secrète dans du code exécuté par le navigateur.

// Laravel, in the controller that renders the page with the editor
$signature = hash_hmac('sha256', (string) $user->id, config('services.mailblocks.secret'));

return view('templates.edit', [
    'mailblocksUser' => ['id' => (string) $user->id, 'signature' => $signature],
]);

Domaines

Ajoutez dans votre tableau de bord chaque nom d’hôte qui affiche l’éditeur. localhost, 127.0.0.1 ainsi que *.test, *.local et *.localhost fonctionnent toujours et ne sont pas comptés. Les domaines génériques comme *.example.com couvrent tous les sous-domaines et sont inclus à partir de l’offre Growth.

Stockage des images

Par défaut, les images sont stockées par Mailblocks. Pour utiliser votre propre stockage, fournissez des endpoints compatibles avec le protocole du gestionnaire de fichiers et autorisez via CORS les requêtes provenant de l’origine de l’éditeur.

Comment l’iframe est protégée

L’éditeur tourne dans une iframe servie depuis notre domaine. Il ne s’affiche que pour les origines de votre licence, communique avec votre page via postMessage, limité à cette origine, et son code est servi par des URL signées à courte durée de vie.

Codes d’erreur

unauthorized_origin: La page n’est pas sur un domaine autorisé pour cette licence.
inactive_license: L’essai est terminé ou la licence est suspendue.
active_user_limit_reached: Le quota d’utilisateurs actifs du mois est épuisé.
invalid_user_signature: La signature est obligatoire, ou elle ne correspond pas à l’identifiant utilisateur.
ticket_invalid: L’éditeur a mis trop de temps à démarrer ; rechargez-le.

DéveloppeursSDK Mailblocks