Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.outpost.pub/llms.txt

Use this file to discover all available pages before exploring further.

This is an advanced, developer-level feature with limited debugging support.HTML email is genuinely hard. The same template renders differently in Gmail, Outlook for Windows (which uses Microsoft Word’s rendering engine), Apple Mail, and Yahoo, and a small mistake can break the layout for a whole audience without any error message. When you use a Custom HTML Template, you own all email-client compatibility and debugging yourself — Outpost cannot debug your template for you.Only use this if you are comfortable hand-writing table-based, inline-styled HTML email and testing it across real inboxes. If you just want to match your brand’s colors, fonts, and logo, use the standard Default Design settings instead — they cover the vast majority of cases.
Custom HTML mode (set via Email Settings → Template mode → Custom HTML) lets you replace Outpost’s entire email shell with your own HTML. Your template wraps the post content and the footer, and you control the full layout. This guide explains exactly how Outpost processes your template at send time so you can avoid the failure modes that are unique to this feature.

​
When to use it (and when not to)

Use the standard Default Design settings unless you need something they genuinely cannot express, such as:
  • A custom masthead (a text wordmark, a multi-element header, a non-centered logo)
  • A precise CTA button shape, or per-element layout the standard slots don’t expose
  • A section treatment (a tinted “featured” band, a custom divider) that isn’t available as a setting
If a single missing detail is the only reason, accept the standard rendering. The cost of a custom template is ongoing: you maintain Outlook compatibility, dark-mode behavior, and mobile breakpoints yourself, forever.

​
How Outpost renders your template

At send time Outpost runs two passes over your template. Understanding both is the difference between a template that works and one that breaks silently.

​
Pass 1 — merge-tag substitution

Outpost performs a literal, global string replacement for every merge tag (the %NAME% tokens). This replacement runs over the entire template string with no awareness of HTML structure.
Substitution happens everywhere, including inside comments. A merge tag written inside an HTML comment (<!-- … -->) or a CSS comment (/* … */) is replaced exactly like one in live markup. The most damaging case: a stray %BODY% left in a comment injects the entire post body into that comment. If the comment is inside a <style> block, the duplicated, tag-filled <style> corrupts the document and the post content escapes your layout in Gmail.When you reference a tag inside a comment for documentation, write the name without the % delimiters (for example, write BODY, not the percent-wrapped form) so it can’t match.

​
Pass 2 — CSS inlining

Outpost extracts the CSS from the <style> block(s) in your template and inlines those rules onto the post body before injecting it at %BODY%. This is how your typography and link colors reach the post content. Two consequences to design around:
  • Your element rules restyle the post content. A blanket rule like a { color: #1B3A5C }, p { margin: 0 0 16px }, or blockquote { … } is stamped onto every matching element inside the post body, overriding any inline styling the author applied in the editor. This is usually what you want (brand consistency), but it means an author cannot, for example, set a one-off link color in a post and have it survive.
  • Structural rules stay on your shell. body, html, and table rules in your <style> apply to your outer layout and are not leaked onto the injected post fragment. You can put structural CSS on body/table without corrupting the post content.
Because email clients strip <head> styles and ignore <style> blocks inconsistently, keep your real layout in inline style="…" attributes on the table elements. Treat the <style> block as defaults for the injected post content, not as your primary layout mechanism.

​
Merge tags

TagDescription
%BODY%The rendered post/email content (inject this exactly once)
%CURRENT_DATE%Today’s date
%SITE_NAME% / %BLOG_NAME%Your publication name
%SITE_URL% / %BLOG_URL%Your publication URL
%SITE_PATH% / %BLOG_PATH%Your site’s base path
%SITE_LOGIN_URL% / %BLOG_LOGIN_URL%Your publication’s sign-in URL
%ACCOUNT_LINK%Member’s account page URL
%EMAIL_FROM_NAME%The sender name from Email Settings
%EMAIL_HEADER_IMAGE%The uploaded header image URL (only substituted if a header image is set)
%PHYSICAL_ADDRESS%Your mailing address from Email Settings, formatted with line breaks (see Compliance)
%SUBSCRIPTION_EXPIRATION_DATE%The recipient’s subscription expiration date
%UNSUBSCRIBE_URL%The recipient’s unsubscribe link (required, see Compliance)
The %BLOG_*% and %SITE_*% prefixes are interchangeable: %BLOG_NAME% and %SITE_NAME% produce the same output.

​
Conditional content blocks

Wrap content so it only renders for paid or free members:
Tag pairShows the wrapped content to
%RECIPIENT.PAID_BLOCK_START% … %RECIPIENT.PAID_BLOCK_END%Paid members only
%RECIPIENT.FREE_BLOCK_START% … %RECIPIENT.FREE_BLOCK_END%Free members only
The matching is case-insensitive, and the _END tags are honored. Always close every block you open.

​
Fonts

Most email clients strip the Google Fonts <link> that Outpost includes, including Gmail and Outlook for Windows desktop, which together dominate most audiences. A web font you specify will only render in a minority of inboxes (Apple Mail, recent Outlook for Mac, Samsung Mail, Thunderbird). For a font that renders consistently everywhere, choose a system font in your inline styles: Arial, Georgia (the one widely available serif), Verdana, Times New Roman, Courier. If you want a web font, always provide a system fallback in the same family (serif fallback for a serif, sans fallback for a sans), because the fallback is what most recipients will actually see.

​
CTA buttons

CTA buttons come from the post body, not from your template shell. Outpost renders an editor button as <a class="btn btn-primary"> inside <p class="text-center">. In Custom HTML mode, Outpost’s default button styling does not apply, so if you don’t style these classes your button renders as an unstyled link. Style the button by targeting the classes directly in your <style> block (the button is the anchor, so target .btn / .btn-primary, never a descendant a): 
.text-center { text-align: center; }
.btn,
.btn-primary {
  background-color: #F2513B !important;
  color: #FFFFFF !important;
  font-family: Verdana, Geneva, sans-serif !important;
  text-transform: uppercase;
  text-decoration: none !important;
  padding: 16px 40px;
  border-radius: 9999px;
  display: inline-block;
  mso-padding-alt: 16px 40px;
}
A padded inline-block link is not bulletproof in Outlook for Windows. The Word rendering engine drops the padding box, so the button degrades to a colored, underlined text link rather than a filled button. It stays legible and clickable, but it will not look like a pill or a rectangle there. Because the button is injected from post content, you cannot wrap it in the usual VML “bulletproof button” markup. Plan for this degradation rather than fighting it.

​
Outlook and dark mode

  • Fixed-width centered card: Outlook for Windows centers a fixed-width table unreliably. Wrap your card in a Microsoft-Office conditional “ghost table” so it stays 600px and centered: 
    <!--[if mso]><table role="presentation" width="600" align="center" cellpadding="0" cellspacing="0" border="0"><tr><td><![endif]-->
<table role="presentation" width="600" style="width:600px;max-width:600px;">
  <!-- your card -->
</table>
<!--[if mso]></td></tr></table><![endif]-->
  • Dark mode: Apple Mail and some Outlook clients auto-invert light backgrounds, which can turn a white card dark and wreck your contrast. Declaring light-only color schemes reduces (but does not fully prevent) this: 
    <meta name="color-scheme" content="light only">
<meta name="supported-color-schemes" content="light only">
    Always confirm contrast in a real dark-mode client; no setting guarantees the card stays light everywhere.

​
Compliance (required)

A Custom HTML Template replaces Outpost’s default footer, so you are responsible for the legal footer. Your template must include:
  • An unsubscribe link, using %UNSUBSCRIBE_URL%.
  • Your physical mailing address.
For the address, set From Physical Address in Email Settings and place %PHYSICAL_ADDRESS% in your footer. It is rendered with line breaks, so the first line of that field can be your publication name.
Unlike the default template, Custom HTML mode has no fallback address. If From Physical Address is empty, %PHYSICAL_ADDRESS% renders as nothing and your footer will be missing the legally required address. Set it before sending.

​
Preview the template

The Custom HTML editor has a Preview tab that renders your template in the browser, with a Free Member / Paid Member toggle so you can check your %RECIPIENT.PAID_BLOCK_*% and %RECIPIENT.FREE_BLOCK_*% conditional blocks. It’s good for fast visual iteration on the shell: masthead, spacing, colors, and fonts.
Treat the preview as a rough check, not proof the email will render. It is a browser-side approximation and does not reproduce the real send:
  • It does not fill in %BODY%, so you see the shell, not real post content.
  • It does not run the CSS inliner, so styles apply through the browser’s normal cascade rather than the inlining that happens at send time.
  • It renders in a browser, which is far more forgiving than Outlook for Windows or Gmail. A template that looks perfect here can still break in those clients.
  • Some per-recipient tags (for example %UNSUBSCRIBE_URL%) are not substituted in the preview and appear as literal text.
Use the preview to iterate quickly, then confirm with real test sends.

​
Testing

There is no substitute for real test sends to real inboxes. Send a complete post (heading, body paragraphs, an inline link, a list, a blockquote, and a CTA button) to test accounts and check, at minimum:
  • Gmail (web and mobile app) — the largest reach for most audiences
  • Outlook for Windows desktop — the worst-case renderer; if it holds here, it holds almost everywhere
  • Apple Mail (macOS and iOS) — including dark mode
  • Outlook.com web and Yahoo Mail
In each, verify the card stays intact, fonts and colors render as intended, the CTA is legible and clickable, the unsubscribe link works, and %PHYSICAL_ADDRESS% is present. If a layout fails in Outlook for Windows, the fix is in your template, not in your Email Settings.

​
Minimal starting template

A bare, Outlook-safe skeleton you can build on. Note there are no merge tags inside comments. 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="color-scheme" content="light only">
  <meta name="supported-color-schemes" content="light only">
  <title>%SITE_NAME%</title>
  <style type="text/css">
    body { font-family: Georgia, 'Times New Roman', serif; color: #333333; }
    p, li { font-size: 16px; line-height: 1.6; }
    a { color: #1B3A5C; }
    .text-center { text-align: center; }
    .btn, .btn-primary {
      background-color: #F2513B !important; color: #FFFFFF !important;
      text-decoration: none !important; padding: 14px 32px; display: inline-block;
    }
  </style>
</head>
<body style="margin:0; padding:0; background-color:#F7F9FC;">
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" bgcolor="#F7F9FC">
    <tr>
      <td align="center" style="padding:24px 12px;">
        <!--[if mso]><table role="presentation" width="600" align="center" cellpadding="0" cellspacing="0" border="0"><tr><td><![endif]-->
        <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" bgcolor="#FFFFFF" style="width:600px; max-width:600px; background-color:#FFFFFF;">
          <tr><td align="center" style="padding:32px;"><strong style="font-size:24px;">%SITE_NAME%</strong></td></tr>
          <tr><td style="padding:0 32px 24px;">%BODY%</td></tr>
          <tr><td style="padding:24px 32px; font-size:12px; color:#6A7383;">
            %PHYSICAL_ADDRESS%<br>
            <a href="%UNSUBSCRIBE_URL%" style="color:#6A7383;">Unsubscribe</a>
          </td></tr>
        </table>
        <!--[if mso]></td></tr></table><![endif]-->
      </td>
    </tr>
  </table>
</body>
</html>