Skip to main content

Settings

Settings are one of the core concepts in Better Email. They define what marketers can edit, how that editing experience is grouped, and how those values flow into the final email.

Both the template base and each module can have settings. The mechanics are the same, but the scope is different:

  • template settings affect the full email
  • module settings affect one module at a time

The template base also has two pinned, special settings at the top:

  • Global for cross-cutting values exposed under the global.* namespace, including a small Liquid script that can compute derived values. See Global settings & Global Script.
  • Shared for input definitions that can be reused across multiple modules and settings via Shared Reference inputs. See Shared inputs.

How to think about settings​

A setting is a group of related inputs. Good settings make the editor easier to scan and easier to understand.

For example, instead of scattering fields across the sidebar, you might group them like this:

  • Content for headline, body copy, and CTA
  • Layout for spacing or alignment
  • Media for images, alt text, and links

The structure you create here is the structure marketers see in the Email Editor.

Where settings live​

Use template settings for anything global, such as:

  • language
  • theme or brand
  • footer behavior
  • spacing systems

Use module settings for anything specific to a single piece of content, such as:

  • a headline
  • a CTA
  • an image
  • a layout toggle

For theme-related controls, color inputs are usually a better fit than freeform strings because you can offer a named palette like Primary Blue or Accent Red while still outputting the correct hex value in Liquid.

Conditional visibility​

Both settings and individual inputs can be shown conditionally with only_show_if.

Use this when you want to keep the editor clean and only reveal options when they are relevant. For example:

  • show a button label only when show_button is enabled
  • show a personalized greeting field only when the selected greeting mode is personalized
  • show advanced layout controls only when a certain mode is selected

only_show_if uses a Liquid expression and is configured in the Template Editor. In the input field, write the expression directly without {{ }} and reference values as setting_key.input_key.

Common patterns​

  • content.show_cta == true
  • layout.layout_mode == 'custom'
  • template.brand.market == 'uk'

When a field is hidden by only_show_if, it does not show in the editor and it does not block review or export while hidden.

Dynamic values in input authoring (FX mode)​

Most authoring fields in the input editor have a small TXT / FX toggle next to them. It controls whether the field is treated as literal text or as a Liquid expression.

  • TXT stores the literal text you type. What you see is what gets used.
  • FX stores the value as a Liquid expression that is resolved at render time. Type global.primary_color and the actual brand color is used wherever the field is rendered.

The toggle is available on:

  • hint text
  • placeholder text
  • select option name and value
  • color option value

Under the hood, an FX value is stored as a normal Liquid output expression (for example {{ global.primary_color }}) and resolved like any other Liquid reference. It can read Global values, Global Script outputs, template settings, or any other value in scope.

When to use it​

Use FX whenever an authoring field should follow a value defined elsewhere instead of being hardcoded. The clearest wins are:

  • Color palettes that should always reflect the current brand. Set the swatch values to global.primary_color, global.secondary_color, etc., and the marketer-facing palette updates automatically when the brand mapping changes.
  • Select option lists that need to stay aligned with global brand or product values.
  • Hints and placeholders that should reference the marketer's actual brand name, market, or other contextual value rather than a generic example.

Where FX is not available​

FX mode is intentionally disabled inside the Global setting itself. Global inputs feed the global.* namespace, so allowing them to reference global.* would create circular references. Use the Global Script to compute derived values instead.

TODO: Add a screenshot of a select option row with the TXT / FX toggle showing both modes side by side.

High-leverage patterns​

Beyond standard settings, Better Email supports a few patterns that are worth knowing about early:

These patterns are powerful, but they only work well when the underlying structure is simple and clearly named.

TODO: Add a screenshot of a well-structured settings panel with grouped sections and a conditional field visible.

Best practices​

  • Group inputs by the job the marketer is trying to do.
  • Keep setting names short and human-readable.
  • Avoid exposing technical implementation details in labels.
  • Use conditional visibility to reduce clutter.
  • Prefer one well-designed repeatable setting over several almost-identical single-item groups.