Sending your own HTML: what's tracked and what's required

When you send a letter from your own HTML instead of using the Letterhead composer, tracking still works — you don’t add any markup for it — but a few limits on what gets tracked, an unsubscribe link you need to add yourself, and two requirements that can get the request rejected, are easy to miss if you’re coming from another ESP.

What’s tracked automatically

Opens are tracked with no setup on your part. Letterhead doesn’t inject a tracking pixel into your HTML — your sending email service provider’s own open tracking handles it.

Clicks are tracked by default too, but only for links that meet two conditions:

• Only <a href="..."> anchors are tracked. A bare URL written directly into the HTML body text (not wrapped in an anchor tag) gets no click tracking.
• Links containing a merge tag ({{ ... }}) or a data-feed expression ([[ ... ]]) are excluded from tracking. Rewriting one of these hrefs for tracking would corrupt the expression before it’s resolved, so Letterhead leaves them alone — the link still works, it just won’t appear in your click report.

You need to add your own unsubscribe link

Unlike a letter built in the Letterhead composer, this endpoint never inserts an unsubscribe link into your HTML — include a working one yourself. (Your HTML isn’t left completely untouched: as described above, a tracked link’s href is rewritten. An unsubscribe link is simply never added if it wasn’t there.)

Use the {{ unsubscribe }} merge tag rather than a URL you build yourself, and Letterhead fills in the right per-reader link when the letter goes out:

<a href="{{ unsubscribe }}">Unsubscribe</a>

There’s a companion tag for linking to the browser version of the letter, {{ viewinbrowser }}. Both are resolved at send time, and both are recognized by HTML validation, so neither counts as an unrecognized merge tag below. Capitals and inner spaces don’t matter — {{unsubscribe}} and {{ unsubscribe }} are the same tag.

What can get a send rejected

Two things reject the request outright, before anything is sent:

The channel must send through Letterhead’s own delivery system. If the channel you’re sending to is connected to a third-party email service provider instead, the request is rejected — this endpoint only supports Letterhead’s native sending path. Create the letter as a draft and send it from the Letterhead dashboard instead if your channel uses a third-party ESP.

The HTML has to pass validation. The following are rejected:

• Forbidden tags: <iframe>, <form>, <input>, <embed>, <object>, <applet>, <frame>, <frameset>
• Forbidden attributes: onclick, onload
• Merge tags ({{ ... }}) that Letterhead doesn’t recognize

A common cause of an unexpected rejection is an unescaped & in the HTML — escape it as &.

See also

• Send a letter — the endpoint itself
• Using the Letterhead API — authentication and the full range of what you can build
• How can I use HTML in Letterhead? — every merge tag available in an HTML template