E-Mail-Editor-SDK: JavaScript-Dokumentation

Schnellstart

Binden Sie den Loader ein, geben Sie dem Editor ein Element mit definierter Höhe und mounten Sie ihn mit Ihrem Public Key. Den Key finden Sie in Ihrem Dashboard unter 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 und Vue

Das SDK hat keine Abhängigkeiten. Kapseln Sie es wie jedes andere Widget: beim ersten Rendern mounten, beim Unmount wieder entfernen.

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 }} />;
}

Optionen

Pflicht sind nur publicKey und user.id.

Option	Typ	Beschreibung
publicKey	string	Der Public Key Ihrer Lizenz (pk_live_…). Kann bedenkenlos im Browser verwendet werden.
user	object	{ id, signature? } identifiziert die bearbeitende Person. Die ID zählt zu den monatlich aktiven Nutzern.
design	string	Ein gespeichertes Design-JSON oder eine MJML-Vorlage, die geöffnet werden soll.
designId	string	Eine feste ID für das Design. Damit kann der Editor anbieten, einen ungespeicherten Entwurf wiederherzustellen.
locale	string	Sprache der Oberfläche: en, es, fr, de, pt, ro oder el.
placeholders	array	Merge-Tags, flach oder gruppiert: [{ label, items: [{ label, value, insert? }] }].
theme	object	Farben, Schriften und Radius für die Editor-Oberfläche. Wirkt in Tarifen mit White-Label.
storage	string \| false \| object	"mailblocks" (Standard), false oder { endpoints, auth } für Ihren eigenen Bildspeicher.
toolbar	object	{ save?: boolean, back?: boolean } blendet die Buttons der Werkzeugleiste ein oder aus.
ai	false \| object	false blendet den KI-Generator aus, { presets, sentence, texts } passt ihn an.

Events

Übergeben Sie Callbacks als onReady, onSave usw. oder abonnieren Sie Events mit editor.on(name, callback).

ready: Der Editor ist geladen. Erhält { plan, features, development }.
save: Der Nutzer hat gespeichert, oder Sie haben save() aufgerufen. Erhält { html, design }.
change: Das Design wurde seit dem Öffnen geändert.
error: Der Editor konnte nicht starten oder das Design nicht laden. Erhält { code, message }.
back: Der Nutzer hat auf den Zurück-Button geklickt.
generated: Der KI-Generator hat eine Vorlage erzeugt. Erhält { mjml }.

Methoden

save(): Speichert und liefert ein Promise mit { html, design }.
load(): Ersetzt das geöffnete Design durch ein Design-JSON oder eine MJML-Vorlage.
destroy(): Entfernt den Editor und seine Listener.

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

editor.load(previouslySavedDesign);

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

editor.destroy();

Signierte Nutzer-IDs

Signieren Sie die Nutzer-ID auf Ihrem Server mit Ihrem Secret Key und übergeben Sie die Signatur. Aktivieren Sie in Ihrem Dashboard „Signierte Nutzer-IDs verlangen“, um unsignierte Sitzungen abzulehnen. Der Secret Key gehört niemals in Browser-Code.

// 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],
]);

Domains

Tragen Sie in Ihrem Dashboard jeden Hostnamen ein, auf dem der Editor läuft. localhost, 127.0.0.1 sowie *.test, *.local und *.localhost funktionieren immer und werden nicht gezählt. Wildcards wie *.example.com decken alle Subdomains ab und sind ab dem Growth-Tarif enthalten.

Bildspeicher

Standardmäßig speichert Mailblocks die Bilder. Für Ihren eigenen Speicher übergeben Sie Endpunkte, die mit dem Dateimanager-Protokoll kompatibel sind, und erlauben per CORS Anfragen vom Origin des Editors.

So ist der Frame geschützt

Der Editor läuft in einem iframe von unserer Domain. Er wird nur für die Origins Ihrer Lizenz dargestellt und kommuniziert mit Ihrer Seite über postMessage, beschränkt auf genau diesen Origin. Sein Code wird über kurzlebige, signierte URLs ausgeliefert.

Fehlercodes

unauthorized_origin: Die Seite liegt nicht auf einer Domain, die für diese Lizenz freigegeben ist.
inactive_license: Die Testphase ist abgelaufen oder die Lizenz ist gesperrt.
active_user_limit_reached: Das Kontingent an aktiven Nutzern für diesen Monat ist aufgebraucht.
invalid_user_signature: Eine Signatur ist erforderlich, oder sie passt nicht zur Nutzer-ID.
ticket_invalid: Der Editor hat zu lange zum Starten gebraucht. Laden Sie ihn neu.

EntwicklerMailblocks SDK