Builder in iframe — Frontend guidelines

Use this page when your app embeds the builder in an iframe and you need Save and Save as template buttons in your own UI (outside the iframe). All communication uses the browser postMessage API with the BUILDER_BRIDGE protocol.

0. Authentication

All builder and documented API routes require a bearer token. Send the JWT in the Authorization header for fetch/XHR; use ?token= on the iframe src when loading the builder page.

fetch(`${BUILDER_URL}/api/builder/launchToken`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ newsletterid: 123 }),
});

On exit impersonate or logout, discard the impersonated token and reload/close the iframe (revoked server-side). API reference: /documentation.

1. Message envelope

Every message must use this shape:

2. Security

In your window.addEventListener('message', ...) handler, always check event.origin against the builder’s origin (e.g. the origin of your iframe’s src) before using event.data. Only process messages where event.data?.channel === "BUILDER_BRIDGE".

3. Builder tabs and SAVE_STATE

The builder has tabs: Builder, Headers, Footers, and Social. Saving a campaign or template is only valid on the Builder tab (the in-builder Save buttons are disabled on the other tabs).

Your parent app must mirror this: disable your external Save and Save as template buttons when the user is not on the Builder tab.

After READY, the iframe sends SAVE_STATE whenever the active tab changes:

{
  channel: 'BUILDER_BRIDGE',
  type: 'SAVE_STATE',
  payload: {
    saveEnabled: true,           // enable your Save button
    saveTemplateEnabled: true    // enable your Save as template button
  }
}

On Headers, Footers, or Social, both flags are false. Re-enable them when the user returns to Builder.

Do not enable Save buttons on READY alone — wait for SAVE_STATE (sent immediately after READY). Optionally show a hint such as “Switch to Builder tab to save” when saveEnabled is false.

4. Save campaign (temporary save)

Flow

1. After the builder loads, it sends READY once, then SAVE_STATE with the current tab.
2. Enable or disable your Save button from payload.saveEnabled on each SAVE_STATE.
3. When the user clicks Save (only if enabled): show “Saving...”, then send SAVE_REQUEST to the iframe.
4. Wait for exactly one SAVE_RESULT (same requestId if you sent one). Then hide “Saving...” and show success or payload.error.

Send SAVE_REQUEST

const builderOrigin = new URL(iframeEl.src).origin;
iframeEl.contentWindow.postMessage({
  channel: 'BUILDER_BRIDGE',
  type: 'SAVE_REQUEST',
  payload: {},
  requestId: 'save-' + Date.now()  // optional, for correlation
}, builderOrigin);

Handle READY, SAVE_STATE, and SAVE_RESULT

let ready = false;
let saveEnabled = false;
let saveTemplateEnabled = false;
let saving = false;
let savingTemplate = false;

function updateSaveButtons() {
  saveBtn.disabled = !ready || saving || !saveEnabled;
  saveTemplateBtn.disabled = !ready || savingTemplate || !saveTemplateEnabled;
}

window.addEventListener('message', function (event) {
  if (event.origin !== builderOrigin || event.data?.channel !== 'BUILDER_BRIDGE') return;
  const { type, payload, requestId } = event.data;

  if (type === 'READY') {
    ready = true;
    updateSaveButtons();
  }
  if (type === 'SAVE_STATE') {
    saveEnabled = !!payload.saveEnabled;
    saveTemplateEnabled = !!payload.saveTemplateEnabled;
    updateSaveButtons();
  }
  if (type === 'SAVE_RESULT') {
    saving = false;
    updateSaveButtons();
    if (payload.ok) {
      // Success: payload.newsletterId
    } else {
      // Failure: show payload.error (e.g. "Switch to the Builder tab to save")
    }
  }
});

5. Save as template

Same idea as Save: you send SAVE_TEMPLATE_REQUEST, the iframe runs “Save as template without content” (user may be prompted for template name inside the iframe), then you receive one SAVE_TEMPLATE_RESULT.

Send SAVE_TEMPLATE_REQUEST

iframeEl.contentWindow.postMessage({
  channel: 'BUILDER_BRIDGE',
  type: 'SAVE_TEMPLATE_REQUEST',
  payload: {},
  requestId: 'template-' + Date.now()
}, builderOrigin);

Handle SAVE_TEMPLATE_RESULT

if (type === 'SAVE_TEMPLATE_RESULT') {
  if (payload.ok) {
    // Success: payload.templateName
  } else {
    // Failure: show payload.error (e.g. "Template name missing or cancelled", "Duplicate template name")
  }
}

The template name is entered by the user in a modal inside the iframe. Your app only triggers the action and then handles success/error.

6. Campaign name sync

If your parent app has its own campaign name field, keep it in sync with the builder using these message types:

Receive CAMPAIGN_FIELDS (iframe → parent)

After READY, the iframe sends the current #campaign_name value whenever the user edits it in the builder:

{
  channel: 'BUILDER_BRIDGE',
  type: 'CAMPAIGN_FIELDS',
  payload: { name: 'My campaign name' }
}

Send SET_CAMPAIGN_FIELDS (parent → iframe)

When the user edits the campaign name in your parent UI, push the new value to the iframe:

iframeEl.contentWindow.postMessage({
  channel: 'BUILDER_BRIDGE',
  type: 'SET_CAMPAIGN_FIELDS',
  payload: { name: 'My campaign name' }
}, builderOrigin);

No response is sent. Updates from the parent do not echo back as CAMPAIGN_FIELDS.

7. Checklist for your app

• Load the builder in an iframe: /builder/launch?token=<token> (JWT or launch token; optional: &parent_origin=<your origin>). Use impersonated_user_token when impersonating.
• Listen for message; filter by channel === "BUILDER_BRIDGE" and event.origin.
• On READY, mark the builder as loaded; keep Save buttons disabled until SAVE_STATE.
• On SAVE_STATE, set saveEnabled / saveTemplateEnabled and update button disabled state.
• On Save click (only when saveEnabled): show “Saving...”, send SAVE_REQUEST, then on SAVE_RESULT handle payload.ok / payload.error.
• On Save as template click (only when saveTemplateEnabled): send SAVE_TEMPLATE_REQUEST, then on SAVE_TEMPLATE_RESULT handle success or payload.error.

← Back to Builder launch