Broadcast Docs
Back to main site
On this page

Opt-In Forms

Opt-in forms are the signup forms you put on your own website. A visitor fills one in, and Broadcast creates the subscriber in the channel that owns the form, applies your tags, and optionally sends a confirmation or welcome email.

Each form is built from blocks in a visual editor, styled without CSS, and installed with a single script tag.

Opt-In Forms list showing two forms with views, conversion rate, and status toggles

The list shows every form in the current channel with its view count, conversion rate, and an on/off toggle. Use Filter by label to search, or the checkboxes to enable and disable forms in bulk.

Choosing a Widget Type

Click New Form and pick how the form should appear on your page. The choice determines which display settings you get later. It is fixed once the form is created: the editor’s Widget tab shows the type but cannot change it. To use another type, create a new form, or change widget_type through the Opt-In Forms API.

3.2+

New form page with the Inline Embed, Popup Modal, and Full Page options and, below them, a row of 12 themes with Clean selected

Below the widget types you pick the Theme the form starts with. Clean is selected. You can change the theme later, see Styling the Form.

Widget type Where it appears Best for
Inline Embed In the flow of your page content, where you put the script tag Sidebars, end-of-post signup, footers
Popup Modal A centered overlay on top of the page Lead magnets and offers that need attention
Full Page A dedicated page of its own, linked directly Landing pages and campaign links

The Form Builder

Opening a form takes you to a three-pane editor: blocks on the left, a live canvas in the middle, and properties on the right.

Form builder with block palette, canvas showing a rendered signup form, and style panel

Your work saves automatically, which the header confirms with Saved just now. The Published toggle in the top right controls whether the form accepts submissions, and it is the same switch as the status toggle on the list page.

Adding Blocks

The left panel lists everything you can drop onto the canvas. Click a block to append it, then drag it by its handle to reorder.

There are thirteen block types, falling into three groups:

Group Blocks Notes
Content Heading, Text, Image, Divider, Spacer Presentation only, collects nothing
Input Email, Name, Checkbox, Dropdown, Radio Group, Custom Field, Topic Each one writes to a subscriber field or topic
Action Button Submits the form

Note

Every form needs an Email block and a Button block. Without an email input there is nothing to create a subscriber from, and without a button there is no way to submit.

Editing a Block

Click any block on the canvas and the right panel becomes its inspector. The fields shown depend on the block type.

Block inspector for an email field showing field type, label, placeholder, and required checkbox

Input blocks all share a Label, a Placeholder, and a Required field switch. What differs is where the answer is stored.

Where Answers Are Stored

Standard input blocks map onto the subscriber’s own columns. Anything else goes into custom data.

Field type Stored as
Email The subscriber’s email address
Name, First name, Last name The matching subscriber name field
Custom Field, Checkbox, Dropdown, Radio Group A key inside the subscriber’s custom data
Topic The value of one subscriber topic: its custom data field, or its tag

Custom keys must start with a letter and contain only lowercase letters, numbers, and underscores, so signup_source is valid and Signup Source is not. Use the same key across forms and you can segment on it later. See Managing Subscribers for how custom data is used elsewhere.

A Topic Checkbox

The Topic block is a checkbox for one of the channel’s Subscriber Topics. Pick the topic in the block’s inspector. The checkbox shows the topic’s name and description, so edit those in Settings > Topics, not on the form.

When a new subscriber submits the form:

  • A ticked box stores true for the topic.
  • An unticked box stores false, never “not set”. So a topic set to send to subscribers with no value does not email someone who left the box unticked.
  • A tag topic adds its tag only when the box is ticked. An unticked box adds nothing.

A subscriber who is already on the list keeps their topics when they submit the form again. They change their topics on the preference page.

Each topic can be on a form one time. A new Topic block takes the first topic that is not on the form yet. The channel needs at least one topic: on a channel with no topics, adding a Topic block shows an error that tells you to create one in Settings > Topics first.

Note

A form sets a topic only through its own blocks. If a signup posts custom data for a topic key that no block on the form writes, Broadcast ignores that key. A Checkbox or Custom Field block that you point at a topic’s key also writes it.

A “Select all” Checkbox

A checkbox whose key ends in _all acts as select all for every checkbox that shares the start of its key. For example, with checkboxes keyed city_markham, city_vaughan and city_richmond_hill, add one more keyed city_all and label it “All cities”.

  • Ticking city_all ticks every city_ checkbox and locks them, so the reader can see what they chose.
  • Only city_all is submitted, not the individual cities. So a segment for “everyone interested in Markham” should match city_markham or city_all; matching city_markham alone misses the people who ticked all of them.
  • Unticking it unlocks the group and restores whatever the reader had ticked before.
Checkbox block inspector with the custom data key city_all and a note explaining that it selects every city_ checkbox

The checkbox inspector explains the convention under the key field. Nothing else needs setting: the _all suffix is what turns it on.

Styling the Form

The Form Style panel restyles the whole form without touching CSS. Changes render on the canvas as you make them.

3.2+

Form builder with the York Region events form on the canvas and the Form Style panel on the right, which shows the 12 themes with Clean selected

The panel starts with Themes and Design, and then has the single values: Colors, Input Fields, Button and corners, Typography, Layout, and Effects. Select a theme first, then adjust.

Themes

A theme is a complete design: colors, fonts, the shape of the box, the fields and the button, and the shadow. There are 12.

Theme Look
Clean White, blue button, Inter. The theme of a new form.
Editorial Off-white, serif heading, square black button
Midnight Dark navy with a light blue button
Candy Pink, round fields and button
Poster Black borders, yellow button, hard shadow, capital labels
Terminal Black and green, a monospace font
Grove Soft green, serif heading
Sunrise White with an orange to pink button
Lilac Light purple, rounded
Civic White with a teal line at the top, small corners
Noir Black with a cream button, serif heading
Tide Blue to teal background, white text

The same signup form in four themes: Clean, Poster, Midnight, and Tide

The same form in four of the themes.

Click a theme to apply it. The whole theme of the form is replaced and the form is saved, so every value below shows what the theme set. You can then change any single value, and you can pick the theme when you create the form.

The themes use 8 fonts (Inter, Instrument Serif, Space Grotesk, Nunito, Archivo, JetBrains Mono, Fraunces, and Bricolage Grotesque). The font files are part of Broadcast and load from your own Broadcast server. A visitor’s browser makes no request to Google Fonts or another font service. The fonts have Latin and extended Latin letters; text in another script shows in a font of the visitor’s device.

Note

Forms made before 3.2 keep the look they have. An upgrade changes nothing on your site. To give an older form the new look, open it and click a theme. This cannot be undone with one click, so note the old colors first if you may want them back.

Design

These settings are not part of a theme. A change of theme keeps them.

Design section of the Form Style panel with the Layout, Choice style, and Button style selects and the Cover image field

Setting Options What it does
Layout Card, Color band, Split with image, Inline row Card is the plain box. Color band shows the heading and text above the first field in a band in the primary color. Split with image puts them in a panel on the left of the fields; on a narrow screen it becomes the color band. Inline row puts a one-line field and the button that follows it on one row.
Choice style List, Pills, Cards How a group of choices looks. A group is two or more Checkbox or Topic blocks in a row that are not required. A Text block directly before them is the question of the group. A new form uses Pills.
Button style From theme, Pill, Outline The shape and fill of the button
Cover image A JPEG, PNG, WebP or GIF file, 5 MB or smaller The picture of the split panel and of the color band. Without one they use the primary color.

Three forms: the Color band layout with choices as pills, the Cards choice style, and the Split with image layout with the heading in a panel on the left

The color band with pills, the cards, and the split layout. This split form has no cover image, so its panel has the primary color.

A few things happen with no setting:

  • A First Name field next to a Last Name field share one row when there is room.
  • A required checkbox (a consent) is never part of a choice group. It stays a checkbox.
  • A choice group that has a topic with a description is shown as cards, also in the Pills style, because a pill has no room for the description.
  • The box that a popup or an inline form sits in takes the theme too: its background, corners, border, shadow, and the close button.
  • The Turnstile check is dark on a dark theme.
  • The confirmation page of a double opt-in takes the theme of the form, unless the Brand Kit is switched on for confirmation pages.

Apply brand kit copies the colors, the font and the corner radius of your Brand Kit into the form, over the theme. It also copies the kit’s background colors, so the kit’s text color is always readable.

Warning

Preview Settings at the top of the panel, including Page Background, only change the editor canvas. They are there to help you judge contrast against your real site, and they are never applied to the embedded form.

Use the Desktop and Mobile buttons under the canvas to check both widths before you publish.

The Success View

The Success tab switches the canvas to what a visitor sees after submitting. It has its own blocks, so you can write a proper thank-you message rather than relying on a default.

Success view of the form builder showing a Check your inbox thank-you message

Only content blocks are offered here (Heading, Text, Divider, Image, and Spacer), because the visitor has already submitted and there is nothing left to collect.

If you would rather send people to a page on your own site, set an After Confirmation URL in the form settings instead. To keep the page but give subscribers a way onward, add a button to it (see Confirmation Pages).

Language of Broadcast’s own messages

Everything you put in the form’s blocks is shown exactly as you wrote it. What Broadcast adds around it follows the channel’s language: the thank-you shown when a form has no Success blocks of its own, the page title, and the messages when a submission cannot be accepted (an invalid email address, a submission sent too fast, too many attempts, a failed security check, or a field that is too long).

The language is the one the channel’s unsubscribe and confirmation pages use: the Default language under Settings > Unsubscribe Page, or the visitor’s browser language when Match the subscriber’s browser language is on and it is one of the channel’s languages. See Unsubscribe Settings. This requires Broadcast 2.36.0 or later; earlier versions show these messages in English.

Display Settings

The Widget tab holds the settings specific to your chosen widget type. For an inline embed that is just width and maximum width. A popup modal has considerably more, including when it should appear.

Widget tab for a popup modal, with the settings on the left, a live preview of the modal over a page in the middle, and the Form Style panel on the right

The preview beside the settings shows the result, overlay and all, so you can judge how intrusive a popup will feel before publishing it.

Triggers

Show widget decides what makes the popup appear:

Trigger Behaviour
Immediately Shows as soon as the page loads
After a time delay Waits a number of seconds you choose (1 to 300, default 5)
After scrolling Waits until the visitor scrolls a share of the page you choose (10% to 100% in steps of 10%, default 50%)
On exit intent Shows when the pointer leaves toward the browser chrome

Show frequency decides how often the same visitor sees it again: Every visit, Once per session, Once per day, or Only once (ever). The Opt-In Forms API also accepts once_per_week. Frequency is tracked in the visitor’s browser storage, so it resets if they clear their browser data.

2.49+

Every N days is also on the list. Choose it, then enter the number of days in Days between shows (30 by default). The visitor sees the popup again once that many days have passed since it last showed. Forms that already had an “every N days” value from an older version now use it in the widget too.

The form’s own page (/opt_in/<identifier>) ignores the frequency, so the popup shows on every reload there. A visit to that page does not count as a view, so it never hides the popup from you on your real site.

Show on devices lets you run a popup on desktop but not mobile, which is worth considering since mobile popups are both more intrusive and more likely to be penalised in search.

Installing the Form

The form’s detail page gives you two ways to install it.

Installation card showing the embed script tag and the direct link

Embed Script

Paste the script tag into your HTML wherever the form should appear. This is the recommended method and the only one that supports popup triggers.

HTML
<script
  src="https://your-broadcast-domain.com/widget.js"
  data-opt-in="your-form-identifier"
  async
></script>

The script reads the form identifier from data-opt-in, fetches the form’s configuration, and renders it inside an iframe. The iframe matters: it means your site’s CSS cannot leak in and break the form’s styling, and the form’s styling cannot leak out and affect your page.

Every form also works as a standalone page at /opt_in/<identifier>. Share it in a bio link, a QR code, or an email, no embedding required. For a Full Page widget this is the primary way to use the form.

A Referral Code in the Address

3.0+

Add ?ref= and a code to the address of the page that shows the form, for example https://example.com/newsletter?ref=ada-42, or to the direct link. This works with the embed script and with the direct link.

When a new subscriber signs up through that address, Broadcast keeps the code on the subscriber as signup_ref. It is in the subscriber webhook events and in the Subscribers API. Use it to see which link brought a person in, or to credit a referrer (see Build a Referral Program).

  • The code can have letters, numbers, - and _, up to 100 characters. Broadcast ignores any other code.
  • Only a new subscriber gets the code. A person who is already on the list keeps their old one.

Form Settings

The Settings button in the editor header opens everything that is not about layout.

Automation

Automation settings showing add tags, double opt-in with a confirmation template, redirect URL and unsubscribe-link option, and welcome email
Setting What it does
Add Tags Comma-separated tags applied to every subscriber from this form. Useful for tracking which form someone came from
Double opt-in Requires the subscriber to confirm by email before they are added to the list
Confirmation Email Template The template sent to confirm. It must include {{ confirmation_url }}. Leave it empty to use the channel’s default confirmation template
After Confirmation A URL on your own site to redirect to after confirming. Leave blank to use Broadcast’s Confirmation Pages
Include unsubscribe link in confirmation email On by default. Turn it off to send double opt-in confirmation emails with no unsubscribe link and no footer
Send welcome email Sends a welcome template after signup, or after confirmation when double opt-in is on

2.49+

Add Tags applies its tags after the subscriber’s own signup or confirmation click, so it counts as the subscriber’s choice. If a tag is the tag of a topic the subscriber turned off, the form adds it back and the topic is on again.

An address that unsubscribed

When someone submits the form with an address that unsubscribed from the channel, the form always sends the confirmation email first, also when Double opt-in is off. Anyone can type an address into a public form, so only the owner of the address can undo their unsubscribe. Nothing changes until they click the link: then they are subscribed again, the form’s Add Tags and sequences apply, and the welcome email goes out if it is on. The email uses the form’s Confirmation Email Template, or the channel’s default confirmation template. Every channel has a default confirmation template, so the email goes out. The exception is an address on a suppression list (a hard bounce, a spam complaint, or added by hand): it gets no email, because mail to it hurts your sender reputation and a confirmation could not make it active again.

The form shows the same message for every address, new, already subscribed or unsubscribed, so a submission does not reveal whether an address was on your list.

Note

Leave Double opt-in enabled unless you have a specific reason not to. It costs you some signups and buys you a list that actually engages, which is what your sending reputation is built on. See Confirmation Pages.

Allowed Embedding Domains

By default a form can be embedded on any domain. List one domain per line here and Broadcast will only render it on those domains. Set this once your form is live, so nobody can lift your script tag onto a site you do not control.

Security

Public forms attract bots. Broadcast layers four defences:

Defence How it works Default
Honeypot A field invisible to humans. Anything that fills it in is a bot On
Time-based validation Rejects submissions faster than a human could type, with a configurable minimum On, 3 seconds
Rate limiting Caps submissions per IP address within a time window On, 5 per hour
Cloudflare Turnstile A privacy-preserving CAPTCHA alternative Off

Honeypot and time validation are invisible to real visitors, so leave both on. Turnstile needs a Cloudflare account and a site key, and is worth adding only if the first three are not holding.

The panel ends with a summary, which is the quickest way to confirm a form is actually protected rather than assuming it:

Security summary listing honeypot, time validation, and rate limiting as enabled, with Turnstile not configured

Tracking Performance

The form’s detail page summarises how it is doing.

Performance metrics showing 1,287 views, 213 submissions, and a 16.55% conversion rate

Views counts how many times the form was displayed and Submissions how many were completed, with Conversion the ratio between them. Below these, a Configuration panel restates the form’s key settings, so you can confirm at a glance that double opt-in is on and the right confirmation template is attached.

The same page lists the people who have signed up most recently.

Recent Submissions card listing the latest subscribers from the form

What Visitors See

Use Preview in the editor header at any point to open the form exactly as a visitor gets it.

The finished opt-in form as a visitor sees it, with name and email fields and a subscribe button

Always submit a test through the preview before you publish. It confirms the subscriber is created in the channel you expected, the tags land, and the confirmation email arrives.

Managing Forms

From the row menu on the list page you can:

  • Edit to reopen the builder
  • Preview to open the public form
  • Duplicate to copy a form, including its blocks, its thank-you (Success view) blocks, and its styling, as a starting point
  • Delete to remove it

Duplicating is the quickest way to run the same form with different copy on two parts of your site, and keeping them as separate forms means the view and conversion numbers stay separate too.

Disabling a form with the status toggle stops it accepting submissions while leaving the script tag in place. The embedded widget removes itself on the next page load.

Permissions

Access to opt-in forms is controlled by two channel permissions:

  • View opt-in forms & performance (opt_in_forms_read) to see forms and their analytics
  • Create & manage opt-in forms (opt_in_forms_write) to build, edit, duplicate, and delete them

Both are included in the built-in Editor role. See Users & Permissions.

API Access

Everything above is available over HTTP, plus A/B variants, which are API-only and have no dashboard equivalent. See Opt-In Forms API for creating forms, reading per-form analytics, and splitting traffic across weighted variants.