Email merge tags

A merge tag such as ##NAME## in an email's subject or body is replaced with a value for each recipient when the email is sent. This page lists the tags the editors offer and what each becomes.

Insert a tag

In any email editor, type #: a list of the tags that email can use opens, and it narrows as you type (#na finds ##NAME##). Pick one and the typed text becomes the whole tag. This works in the rich body editor and in plain fields such as the subject and preview line. The editors are described in Email engine.

The tags

"Offered in" names the editors whose # list shows the tag: a signup form's verification and welcome email templates, email marketing broadcasts, the composer, and the brand kit footer.

Tag	Becomes	Offered in
`##NAME##`	The recipient's name, or the part of their email address before the `@`.	Every editor except the brand kit footer.
`##EMAIL##`	An `email` value in the email's data. Arc CMS's own senders do not add one, so it comes out empty unless an app event's data has an `email` field.	Form verification and welcome templates, broadcasts, the composer.
`##OTP##`	The one-time sign-in or verification code.	The form verification email template; composer templates whose type contains `otp`.
`##COMPANY_NAME##`	The company name in the email settings.	The brand kit footer, the composer.
`##UNSUBSCRIBE_LINK##`	A signed one-click unsubscribe link for the recipient, on the site's address.	The brand kit footer, broadcasts, the form welcome email template, the composer.
`##PREFERENCES_LINK##`	A signed link to the recipient's email preferences page.	The brand kit footer, broadcasts, the composer.
`##WAITLIST##`	The signup form's name, or "our waitlist" when it has none.	The form welcome email template.
`##SUBJECT##`	The email's own subject line.	No editor.
`##CONTENT##`	A `content` value in the email's data. No core sender adds one.	No editor.
`##PAYMENT_AMOUNT##`	The currency and amount of the payment, such as `USD 29`.	Composer templates whose type contains `payment`.
`##SUBSCRIPTION_PLAN##`	The plan the payment is for.	Composer templates whose type contains `payment`.
`##RENEWAL_DATE##`	The subscription's next renewal date.	Composer templates whose type contains `payment`.

Tags you type yourself

These forms are not in the list above but are filled in the same way:

##FIELD:key##, or ##FIELD:key|fallback##: a custom contact field. The fallback is used when the recipient has no value. The contact fields page copies the tag for each field. See Audience.
##APP.path##, or ##APP.path|fallback##: a field of the host app's user, for emails to an App users list. The broadcast editor offers these when such a list is chosen; fields that look like credentials are never offered or merged. See App audience.
Any other ##UPPER_SNAKE## tag is looked up by name in the email's data (##TRIAL_ENDS_AT## reads trialEndsAt), then in five email settings: ##COMPANY_NAME##, ##SENDER_NAME##, ##SENDER_EMAIL##, ##REPLY_TO_EMAIL##, ##LIVE_URL##.
##POSITION##, ##REFERRAL_CODE##, ##REFERRAL_LINK## and ##LEADERBOARD_LINK##, from signup forms of older versions, have no value any more and come out empty. Remove them from any welcome email that still has them.

How tags are filled

The send happens in the Cloud Functions: each queued email is written to EmailLogs with its data, and the sender replaces every tag in the subject and the body in one pass. Values are escaped, so markup in a name shows as text, and a value that itself looks like a tag is not replaced again.

A tag with no value becomes empty text, not the tag itself. A subject such as Welcome, ##NAME## is safe, but a tag the email does not carry leaves a gap. Send yourself a test from the editor before a real send.

To add a tag to the list an editor offers, add it to EMAIL_TAG and the right context in src/shared/constants/email-tags.ts, and make sure the sender puts a value for it in the email's data.