Skip to main content
Writing a component starts with a decision. What may a future editor change, and what must stay fixed so the block works everywhere it is used? This article covers that decision, the MJML itself, and the one place Liquid belongs in a component. Prerequisites
  • Familiarity with the MJML tags mj-section, mj-column, mj-text, mj-button, and mj-image. If they are new to you, read How MJML works. For allGood’s EDIT and LOCKED convention, read Email components.
  • Access to a component library’s Workshop in allGood. This is where you write and save a component.

​
What makes a component worth adding

A component earns a place in the library when it does one nameable job, such as a hero, a footer, or a two-column offer row. Describe it in plain language so that someone choosing between it and a similar block on Overview picks correctly the first time. A component that covers three loosely related layouts is usually two or three components that have not been split yet.

​
Steps

1

Decide what is EDIT and what is LOCKED before you write markup

EDIT is anything a send genuinely varies: copy, links, colors, and padding. LOCKED is the element tree. That means which sections and columns exist, what is nested inside them, and their order. Decide this first. The markup and its documenting comment both follow from it.
2

Build the structure from MJML tags, not raw HTML

Use mj-section and mj-column for layout, mj-text for copy, mj-button for any call to action, and mj-image for images. Put real placeholder copy directly in the tags. Write a headline that reads like a headline and a button labeled like a button, not a note about what should go there:
3

Document the EDIT and LOCKED boundary in an ag: comment

Put the comment at the top of the file. Say what the component is for, then list what is editable and what is fixed:
A future editor, human or allGood’s AI, reads this comment before touching the component. A boundary that is not documented here does not exist for anyone else.The EDIT: and LOCKED: labels are not the only acceptable style. Plain-language guidance works if it is unambiguous. The library’s own hero block documents itself this way:
The hero block's MJML source, with its inline ag: comment describing what is safe to change.

The hero block's MJML source, with its inline ag: comment describing what is safe to change.

4

Use Liquid only for values that must resolve at send time

An unsubscribe link, a postal address, and a copyright year come from the send itself, not from a person filling in a field. Cite them instead of typing placeholder copy:
Keep everything else as plain text, including headlines, button labels, and body copy. A component is not where per-send personalization happens. That belongs to a template’s copySchema, which sits on top once components are composed.
5

Preview and iterate in the Workshop

Open the component in the Workshop. Describe changes to Ask Mary in plain language. You can view a component’s MJML, but you can’t edit it by hand. Each save creates a new version. A version does not affect a live email until it is published, so iterating costs nothing.
6

Track the component through publishing

In the History tab, confirm your new version shows a Published entry. For History, rollback, and checking what a component is used by, see Setting up and reviewing email components.
The component is ready when it appears on Overview with an accurate description and preview, and its status shows the version you published.

​
If something is not working

The validator flags your component every time it is used. Something inside the LOCKED boundary changed. An element was added, removed, or re-nested. Revert the structural change, and limit your edit to what the ag: comment lists as EDIT. A Liquid token renders literally instead of resolving. allGood does not resolve that token at the component level. Use confirmed system values only, such as send.unsubscribeUrl, sender.postalAddress, or a "now" | date filter. Anything else belongs in plain text, or in a template’s copySchema if it needs to vary per send. If neither fix explains what you see, contact the team that maintains allGood’s email tooling. Include the component’s name and the version you are comparing against.