Popup document

Here is the newsletter template in full:

{
  "blocks": [
    { "id": "h1", "kind": "HEADING", "content": "Join the list" },
    { "id": "p1", "kind": "PARAGRAPH", "content": "One email when something worth reading goes up." },
    { "id": "b1", "kind": "INPUT", "type": "EMAIL", "label": "Email", "required": true }
  ],
  "settings": { "name": "Newsletter signup" },
  "popup": {
    "layout": "center",
    "size": "md",
    "overlay": true,
    "closeButton": true,
    "animation": "fade",
    "trigger": { "kind": "delay", "seconds": 10 },
    "frequency": { "kind": "days", "days": 7 },
    "action": { "kind": "close" }
  }
}

It has three parts. blocks is what’s inside the popup, settings is for you, and popup controls where, when and how often it appears.

This page covers the parts you’ll run into most. For the complete list, ask your agent to call popup_schema.

BlocksCopy Anchor Link

Blocks are listed in the order they appear. Each one has an id and a kind.

Two things work inside text:

• A discount code. Wrap it in <code> in a paragraph, as in Use <code>SAVE10</code> at checkout., and the popup draws it as a chip with a Copy button.
• An earlier answer. @{{name|there}} in a heading, a paragraph or a question’s label puts in what the visitor answered to the question whose id is name, or “there” if they left it empty. It’s inserted as plain text, never as HTML.

Field typesCopy Anchor Link

An input’s type can be TEXT, LONG_TEXT, EMAIL, PHONE, NUMBER, DATE, SINGLE_CHOICE, MULTI_CHOICE, DROPDOWN, RATING, SCALE, LINK, FILE or SIGNATURE.

The three choice types take their options as a simple list of strings, for example "options": ["Small", "Medium", "Large"].

LINK is a box the visitor types a web address into. It is not a button: a call to action is a link inside a paragraph.

Each type has a few settings of its own:

The Spam check is a block too: { "id": "sc", "kind": "CAPTCHA" }, a Cloudflare Turnstile widget drawn exactly where it sits, so put it on the last page, just before the submit button. A popup has at most one, and one without it isn’t checked. It has no settings: it follows the popup’s light or dark theme. It needs a Turnstile key that covers the popup’s site: the deploy’s own on a site under the deploy’s domain, or the site’s own keys, pasted on the dashboard’s Sites page. Without one, a popup that has it can’t be published.

Files and signatures are kept in your deploy’s private storage, never in the answer itself. You download them from the dashboard’s Leads page; everywhere else (the CSV, a webhook, your mailing list) they show as “file: cv.pdf, 182 KB”. Files, signatures and pictures has the accepted types, the limits and the spam check they need.

Give every input a different label. Answers are saved under the label, so two inputs with the same one overwrite each other.

Verified email addressesCopy Anchor Link

Turn on Verify email on an email question (in the builder, the question’s settings; in a document, "verifyEmail": true) when a wrong or borrowed address costs you something: a quote, a booking, a download sent by email.

• The visitor types their address and presses Verify inside the box. A 6-digit code arrives by email, from your deploy’s sender, with your site’s domain in it. They type it into the box that appears, and a tick shows the address is confirmed.
• Until then the popup will not submit, and the server refuses an answer without proof for that exact address, so a script cannot skip the step.
• A code works for 10 minutes and only once. Five wrong guesses and it stops working; the visitor asks for a new one. One address gets at most one code every 45 seconds, five an hour and ten a day. If the popup has the spam check on, each code needs it too.
• Nobody who unsubscribed from, or bounced, your deploy’s emails gets a code. The visitor is told the code could not be sent, the same as for an address that does not exist.

It needs an email provider on the deploy (EMAIL_API_KEY and EMAIL_FROM) and a site kept in an account. Without either, the box stays a plain email box and nothing is asked; the builder and audit_popup say which. In the builder’s canvas the box is plain; the preview shows the code step and takes any six digits.

Every extra step loses visitors, so leave it off on a plain newsletter signup.

SettingsCopy Anchor Link

settings.name is the name you see in your list of popups. Visitors never see it. The heading they see is the HEADING block.

settings.submitLabel is the text on the submit button; without it the button says “Submit”. settings.theme sets your brand colours; popup_schema lists its keys.

Where it appearsCopy Anchor Link

When, how often and for whomCopy Anchor Link

These keys decide when the popup opens and who sees it. Targeting and timing covers each one with examples.

A teaserCopy Anchor Link

The teaser is a small pill on the page that opens the popup when it’s pressed. It can stand in for the trigger, or bring the popup back for someone who closed it.

"teaser": {
  "when": "after-close",
  "label": "Still want 10% off?",
  "sub": "Ends Sunday",
  "icon": "🎁",
  "position": "bottom-left"
}

The builder’s eight looks (Pill, Minimal, Tab, Photo pill, Bar, Dark bar, Photo card and Badge) are just combinations of shape, the colours and the pictures.

Pressing the pill opens the popup, so the frequency still decides. An after-close pill needs a frequency that lets the popup show again, such as always, or it never appears. Your agent’s audit_popup points that out. Closing the pill hides it for the rest of the visit.

After someone submitsCopy Anchor Link

Answers are always saved, whatever you set here. Where answers go covers each of these in full.

Questions that depend on answersCopy Anchor Link

A CONDITIONAL_LOGIC block shows, hides or requires other blocks, or jumps to a page, depending on earlier answers - for example a different follow-up for a low and a high NPS score. Ask your agent to call popup_schema for the exact shape and an example.