Skip to content
Osama Hassouna

Link Tokens

A common silent failure in image-to-email generation: the generator emits href="https://example.com/sale" because the link target isn’t visible in the source design. The HTML looks correct, ships to production, and only fails when a recipient clicks the CTA and lands on a parked domain. The “obvious placeholder” was too obvious to the model and too invisible to the human doing the swap.

The fix is a louder placeholder convention. Use {{token}} syntax for everything that has to be filled in before send.

The convention

Section titled “The convention”

Wrap every value that needs human substitution in double-brace tokens. Tokens are not invented per email — they come from a fixed vocabulary so reviewers and tooling can detect and replace them programmatically.

link-token-button.html
<a href="{{cta_url}}" target="_blank"
   style="…">
  View the offer
</a>
link-token-unsubscribe.html
<a href="{{unsubscribe_url}}" style="color:#888;text-decoration:underline;">Unsubscribe</a>
link-token-text-field.html
<td>Dear {{employee_name}},</td>

Standard tokens

Section titled “Standard tokens”

Use these names when the field matches. Use custom names (still in {{}}) when the field is genuinely specific to the template.

TokenPurpose
{{cta_url}}Primary call-to-action link target.
{{secondary_cta_url}}Secondary CTA when an email has more than one button.
{{unsubscribe_url}}Required unsubscribe link for any marketing-class email.
{{preferences_url}}Email preferences / “manage subscriptions” link.
{{view_in_browser_url}}”View this email in your browser” fallback link.
{{logo_url}}Hyperlink on the header logo (usually the homepage).
{{preheader_text}}Preheader copy in the hidden preheader row.
{{employee_name}} / {{recipient_name}}Personalization fields when the source shows [Name] or similar.
{{support_phone}}Support contact number.
{{support_email}}Support contact email.
{{company_name}}Sender company name in footer.
{{company_address}}Required physical mailing address for marketing-class email.

Why double braces

Section titled “Why double braces”
  • Loud. {{cta_url}} is impossible to miss in a code review. https://example.com/sale blends in.
  • Detectable. Tooling can grep /\{\{[a-z_]+\}\}/g and refuse to send an email that still has unfilled tokens.
  • Standard. Mailchimp, SendGrid, Postmark, Customer.io, ConvertKit, and most internal CRM systems use {{...}} (Mustache / Handlebars syntax). Generated tokens map directly to merge tags downstream.

Don’t use example.com or made-up URLs

Section titled “Don’t use example.com or made-up URLs”

Codex review found this was the single highest-impact addition for generation quality. Some examples of what NOT to emit:

<!-- ❌ Looks real, will not fail fast -->
<a href="https://example.com/job-offer">…</a>
<a href="https://example.com/unsubscribe">…</a>


<!-- ❌ Invented CDN URL — broken image guaranteed -->
<img src="https://cdn.example.com/logo.png" … />


<!-- ❌ Random-looking real URL — same problem -->
<a href="https://hr.healthholding.sa/offer/abc123">…</a>

All four examples ship as “working HTML” and silently break when delivered.

<!-- ✅ Loud, replaceable, won't go to production by accident -->
<a href="{{cta_url}}">…</a>
<a href="{{unsubscribe_url}}">…</a>

Interaction with image placeholders

Section titled “Interaction with image placeholders”

Tokens are for href targets and text values. Images stay on the placehold.co convention (Image Placeholders) — that pattern already provides the same fail-fast property for <img src> because placehold.co URLs are obviously grey blocks, not invented CDN URLs. Two different conventions, same goal: nothing real-looking that the human might forget to swap.

Section titled “Related”