Merge Tags Cheat Sheet

Templates are plain HTML. Everything dynamic goes through a merge tag written {{name}}, resolved per recipient at send time.
One syntax only. Templates use {{name}}. Mailchimp's *|TAG|* syntax is converted when you save a pasted template — it is never a second syntax to maintain.

Supported merge tags

This is the entire built-in vocabulary. Your own contact fields come on top, under custom. — see Custom fields. Anything else is reported as unknown.
TagResolves toExample output
{{firstName}}Contact's first nameCamille
{{lastName}}Contact's last nameDubois
{{email}}Contact's email addresscamille@exemple.fr
{{unsubscribeUrl}}Unique unsubscribe link for this recipienthttps://app/u/a1b2c3
{{currentYear}}Year at the moment of rendering2026
{{today}}Today's date, long formAugust 22, 2026
{{postalAddress}}Your organization's postal address12 rue des Lilas, 59000 Lille
{{topicOptOutUrl}}Opt-out link for the send's topic (optional)https://app/t/d4e5f6
{{poweredBy}}A small "Sent with AgentsMail.io" linkSent with AgentsMail.io
{{previewText}}The preview text; compatible alias of {{preheader}}Three new things this month
{{preheader}}The preview text of the campaign or stepThree new things this month
{{today}} and {{currentYear}} are computed at render time, in the sending organization's time zone and language. Both come from Settings → Sending. The same instant produces a different date for an organization in Paris and one in New York — that is the point. Values passed for them in an API call are ignored: like {{unsubscribeUrl}}, AgentsMail decides them.
Language{{today}} renders
French22 août 2026
EnglishAugust 22, 2026
Spanish22 de agosto de 2026
In an automated sequence, {{today}} is resolved when the step actually sends — not when the sequence version was published. A published step is otherwise a frozen snapshot, so this is the one thing in it that moves.
{{poweredBy}} is the one merge tag that inserts a link for you. Every other tag resolves to text — with {{unsubscribeUrl}}, your template writes the <a> around it. This one arrives ready: a small, discreet link, no underline, in the colour of the surrounding text, so it sits in a footer without competing with anything. Because it is already a link, do not put it inside an attribute (href="{{poweredBy}}" produces broken HTML) — drop it on a line of its own.It is entirely optional: nothing requires it, nothing stops you from deleting it, and it is never added to your template behind your back. Templates from the gallery carry it in the footer; remove it and the template still sends.It follows your organization's email language, and it is not counted as a tracked link — it never appears in your campaign's click statistics.
{{previewText}} and {{preheader}} render the same preview text. The preview text is the line the inbox shows right after the subject. You write it next to the subject — on the campaign screen, on a sequence step, or through previewText (compatible alias: preheader) in the campaign API — and the template decides where it lives: a hidden block carrying {{previewText}} or {{preheader}}, usually right after <body>. Every template in the gallery ships with one; the starter template does too.Two consequences worth knowing:
  • A preview text without the tag goes nowhere. Nothing is inserted into your HTML for you. The send still leaves, and the render reports the warning missing_preheader_shortcode so you know the line was dropped — the inbox then falls back to the first visible text of your email.
  • The tag without a preview text is harmless. The hidden block simply stays empty.
The hidden block also keeps the preview text out of the plain-text version of the email, so it is never read twice.
Whitespace inside the braces is allowed — {{ firstName }} works like {{firstName}}. Merge tags are resolved in both the subject line and the HTML body.
{{unsubscribeUrl}} is mandatory. A template whose rendered HTML does not contain the unsubscribe link is refused at render time, with an explicit error. No footer is silently appended to your HTML — the link must be somewhere in your template.

Custom fields

Every custom field your organization defines is available as {{custom.<key>}}, where <key> is the field's key (lowercase letters, digits and _, starting with a letter).
html
<p>Your plan: {{custom.plan}}</p>
<p>Hello {{custom.nickname | "there"}},</p>
  • {{custom.<key>}} renders the contact's value, or nothing when the contact has none.
  • {{custom.<key> | "fallback"}} renders the fallback text when the contact has no value. Inside an HTML attribute, the editor stores the quotes as &quot; — {{custom.city | &quot;Paris&quot;}} works the same way.
  • Fallbacks exist for custom fields only: {{firstName | "there"}} is not a merge tag.
Each field type renders as text:
TypeRenders asExample output
TextThe value as writtenGold
NumberThe number, unformatted1234.5
DateLong date, in the contact's languageMarch 1, 2026
Booleanyes / no, in the contact's languageyes
The language is the contact's own, when it is French, English or Spanish; otherwise your organization's email language from Settings → Sending. A date is the calendar day you stored — it never shifts with a time zone. Values are escaped in the HTML body. A value such as <b>VIP</b> shows as that text, never as markup — a value imported or sent through the API cannot inject HTML into your email. In the subject line, which is plain text, the value appears exactly as stored. An unknown key never blocks a send. A key your organization has not defined renders its fallback, or nothing, and is reported as custom.<key> in the preview panel and in the unknownVariables of the render endpoint. Unlike an unknown built-in tag, it is never left visible in the email. Previews and the public archive never show a real contact's value. The editor preview, test sends, the render endpoint and the public page of a sent campaign have no recipient: every custom tag shows its fallback, or nothing. Only a real campaign or sequence send uses the recipient's values.
A merge tag inside the address of a tracked link is not replaced — the link is rewritten for click tracking before merge tags are resolved. This is true of every merge tag, {{firstName}} included. Keep custom tags in the text of your email, not in link URLs.

Mailchimp tags converted on save

Paste a Mailchimp template and save it: these are rewritten automatically.
Mailchimp tagBecomes
*|UNSUB|*{{unsubscribeUrl}}
*|FNAME|*{{firstName}}
*|LNAME|*{{lastName}}
*|EMAIL|*{{email}}
*|CURRENT_YEAR|*{{currentYear}}

Not supported

Any other *|TAG|* is left untouched in the HTML and reported in the editor when you save. It is never silently shipped to recipients.
Mailchimp tagWhy it is not supported
*|DATE:d F Y|*Carries a format string. Merge tags substitute, they do not format — converting it would silently throw your format away. Use {{today}} (long date) or {{currentYear}} (bare year); an arbitrary format is not supported.
*|IF:…|* etc.Conditional blocks require a template engine, not substitution.
*|ARCHIVE|*No merge tag. Sent campaigns get a public page when the public archive is on.
*|LIST:NAME|*List and account metadata are not exposed to templates.
*|MERGE1|*, …Not converted: Mailchimp's numbered fields do not map to your field keys. Replace each with {{custom.<key>}}.
If you paste a template using one of these, fix it in the editor: replace the tag with static text, or drop it.

Behaviour rules

A known tag with no value renders empty. If a contact has no first name, Salut {{firstName}}, renders as Salut ,. Write around it, or keep the tag out of a sentence that breaks without it. An unknown tag is left visible and reported. {{fistName}} (typo) stays in the output as {{fistName}} and is listed as an unknown variable in the preview panel — so you catch it before sending, not after. An unknown {{custom.…}} key is the exception: it renders its fallback or nothing, and is still reported. The preview uses sample data. The preview panel renders your template with example values and a placeholder unsubscribe URL, so what you see is what a real send actually produces.

Example

html
<td>Salut {{firstName}}, voici les nouvelles du mois.</td>
<!-- … -->
<a href="{{unsubscribeUrl}}">Se désinscrire</a>
Rendered for a contact named Camille:
html
<td>Salut Camille, voici les nouvelles du mois.</td>
<!-- … -->
<a href="https://agentsmail.io/unsubscribe/a1b2c3">Se désinscrire</a>