Documentación del SDK del editor de email

Inicio rápido

Inserta el cargador, dale al editor un elemento con altura y móntalo con tu clave pública. Encontrarás la clave en tu panel, en la sección 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 y Vue

El SDK no tiene dependencias, así que intégralo como cualquier otro widget: móntalo en el primer renderizado y destrúyelo al desmontar el componente.

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

Opciones

Solo publicKey y user.id son obligatorios.

Opción	Tipo	Descripción
publicKey	string	La clave pública de tu licencia (pk_live_…). Se puede usar sin riesgo en el navegador.
user	object	{ id, signature? } identifica a la persona que edita. El id cuenta para los usuarios activos mensuales.
design	string	El diseño que se abrirá: un JSON de diseño guardado o una plantilla MJML.
designId	string	Un id estable para el diseño; sirve para ofrecer la recuperación de un borrador sin guardar.
locale	string	Idioma de la interfaz: en, es, fr, de, pt, ro o el.
placeholders	array	Etiquetas de combinación (merge tags), sueltas o agrupadas: [{ label, items: [{ label, value, insert? }] }].
theme	object	Colores, tipografías y radio de la interfaz del editor. Se aplica en los planes con marca blanca.
storage	string \| false \| object	"mailblocks" (por defecto), false o { endpoints, auth } para usar tu propio almacenamiento de imágenes.
toolbar	object	{ save?: boolean, back?: boolean } para mostrar u ocultar los botones de la barra de herramientas.
ai	false \| object	false para ocultar el generador con IA, o { presets, sentence, texts } para personalizarlo.

Eventos

Pasa callbacks como onReady, onSave, etc., o suscríbete con editor.on(name, callback).

ready: El editor está cargado. Recibe { plan, features, development }.
save: El usuario guarda o tú llamas a save(). Recibe { html, design }.
change: El diseño ha cambiado desde que se abrió.
error: El editor no pudo iniciarse o cargar el diseño. Recibe { code, message }.
back: El usuario hace clic en el botón de volver.
generated: El generador con IA ha creado una plantilla. Recibe { mjml }.

Métodos

save(): Guarda y devuelve una promesa que se resuelve con { html, design }.
load(): Sustituye el diseño abierto por un JSON de diseño o una plantilla MJML.
destroy(): Elimina el editor y sus listeners.

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

editor.load(previouslySavedDesign);

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

editor.destroy();

Firma de ID de usuario

Firma el ID de usuario con tu clave secreta en tu servidor y pasa la firma. Activa en tu panel la opción que exige ID de usuario firmados para rechazar las sesiones sin firma. Nunca pongas la clave secreta en código que se ejecute en el navegador.

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

Dominios

Registra en tu panel cada nombre de host que ejecute el editor. localhost, 127.0.0.1 y *.test, *.local y *.localhost siempre funcionan y no se cuentan. Los comodines como *.example.com cubren todos los subdominios y están incluidos a partir del plan Growth.

Almacenamiento de imágenes

Por defecto, Mailblocks almacena las imágenes. Para usar tu propio almacenamiento, pasa endpoints compatibles con el protocolo del gestor de archivos y permite mediante CORS las solicitudes desde el origen del editor.

Cómo se protege el iframe

El editor se ejecuta en un iframe servido desde nuestro dominio. Solo se muestra en los orígenes de tu licencia, se comunica con tu página mediante postMessage restringido a ese origen y su código se sirve a través de URL firmadas de corta duración.

Códigos de error

unauthorized_origin: La página no está en un dominio autorizado para esta licencia.
inactive_license: El periodo de prueba ha terminado o la licencia está suspendida.
active_user_limit_reached: Se ha agotado el límite de usuarios activos de este mes.
invalid_user_signature: La firma es obligatoria o no coincide con el ID de usuario.
ticket_invalid: El editor ha tardado demasiado en iniciarse; vuelve a cargarlo.

DesarrolladoresSDK de Mailblocks