HubSpot personalization tokens: fallbacks, HTML and DKIM

To add a personalization token to a HubSpot marketing email, click a rich text module, click Personalize, choose a Type and a Token, enter a fallback value and click Insert (HubSpot's token guide). In code, the same token is {{ contact.firstname }}. If the contact has no value and no fallback or default is set, the token appears as blank, so "Hi first name," goes out as "Hi ,".

How do I insert a personalization token in a HubSpot email?

For the subject line, click the inbox content module at the top of the email, then Personalize in the Subject line field; that dialog asks for a fallback value too. HubSpot's steps for sending information do not mention Personalize for the preview text field, so check that field in your own account.

In a coded template, type the variable in double braces, such as {{contact.firstname}}, and publish. The HubL variables reference reads contact properties, custom and default, by internal name, not by label.

HubSpot personalization tokens list: what each type pulls

The types and their limits are from HubSpot's token guide. In its own example, a user named John owns a contact named Cynthia, and the Contact owner first name token prints John. HubSpot's references do not list the HubL names for owner tokens, so insert those with Personalize.

Fallback values and default values: which one wins?

There are two places to set what an empty property prints (default values guide):

• A global default per property. As of October 2026: settings, Marketing, Email, the Personalization tab, then Edit defaults. Email defaults are stored apart from page defaults.
• A fallback on one token. If the property has a global default, the Personalize dialog shows Use this property's global default value. Clear it to give that one token its own fallback, which then overrides the global default.

The guide says tokens in marketing emails must have a fallback value, and the dialog has a field for one. A token typed straight into a coded template never passes through that dialog. And a fallback only covers an empty property: a first name stored as "info" prints "info".

Does the HubL default filter work in HubSpot email?

Not according to HubSpot. Its HubL filter reference says: "You can apply HubL filters to personalization tokens, such as contact and company tokens, on HubSpot CMS and blog pages, but not in emails." So {{ contact.firstname|default("there") }} is not a fallback HubSpot documents for email. The token guide does say HubL filters can add tokens to a coded template, but that sentence covers page templates too; the filter reference is the page that names email.

Even where it runs, the default filter returns its value only when the variable is undefined, unless you pass true as a second parameter for values that evaluate to false, such as an empty string.

The HubL reference also documents a function, personalization_token, which "Returns the value of a contact or contact related property, or a default":

Hi {{ personalization_token("contact.firstname", "there") }},

It is not a filter, so the rule above does not name it, but the reference does not say it runs in email either. Preview it against a contact with an empty first name before you send.

Where personalization tokens work, and how to test them

• Documented in email: rich text modules, coded templates in the Design Manager, and the subject line.
• Dates: default date and time properties such as Create date print only the date in marketing emails.
• Link URLs: the articles cited here do not document a token inside a link's address, so test a personalized link with a real contact.

To test, choose Preview & test, then Preview as a contact, and pick a contact whose first name is empty. A test email can carry a contact's values too, but it arrives from noreply@hubspot.com, so it says nothing about your domain's authentication.

How do I build a custom coded email template in HubSpot?

Coded email templates need Marketing Hub Professional or Enterprise (HubSpot's coded template guide). As of October 2026 the path is Content, Design Manager, File, New file, HTML + HubL, Template, with email as the template type.

The HubL variables HubSpot requires before it will publish

If a required variable is missing, HubSpot says an error message may appear when you try to publish. For email, that is the CAN-SPAM footer and one unsubscribe variable, above the closing body tag:

<!-- Enter variables above the closing </body> tag -->
{{ site_settings.company_name }}
{{ site_settings.company_street_address_1 }}
{{ site_settings.company_city }}
{{ site_settings.company_state }}
{{ site_settings.company_zip }}
{{ site_settings.company_country }}

<!-- Choose one unsubscribe variable -->
{{ unsubscribe_link }}
{{ unsubscribe_link_all }}

The values come from your footer settings, and the unsubscribe variables print a URL for the href of a link (HubL variables reference). That reference lists a shorter set, without zip and country; use the longer one. {{ standard_footer_includes }} is required in page and blog templates, not email ones. Email templates also need HubSpot's hidden preview text block:

<div id="preview_text" style="display:none!important">{% text "preview_text" label="Preview Text <span class=help-text>This will be used as the preview text that displays in some email clients</span>", value="", no_wrapper=True %}
</div>

How HubSpot inlines your CSS

CSS in a style tag with the id hs-inline-css is compiled into inline styles on the matching elements, one such tag per template (email template markup). Media queries cannot be inlined, so they go in a separate style tag.

<style type="text/css" id="hs-inline-css">
td {
font-family: Arial, sans-serif;
}
</style>

How regions become editable

Content is editable per email only where a module sits, such as the text module in the preview block; HubSpot's own layouts wrap the body in {% content_attribute "email_body" %}. For drag and drop inside your frame, add a drag and drop area (drag and drop email templates):

{% dnd_area "main" %}
	<!-- generates an empty drag and drop area drop-section -->
{% end_dnd_area %}

The head then needs {{ dnd_area_stylesheet }}. A template holds one drag and drop area at most, its minimum width is 624 pixels and cannot be overridden, and dnd_row is not supported in email.

Why does pasting HTML into the drag and drop editor change it?

Because HubSpot rebuilds it. Upload design, under Create email, takes a file or pasted HTML and uses AI to recreate it in drag and drop modules (HubSpot's upload guide). It needs Marketing Hub Professional or Enterprise with generative AI on, allows 100 uploads a month, and adds HubSpot's default footer. HubSpot lists what it cannot recreate: rounded corners and border colors on modules, custom fonts and modules, background gradients, designs wider than 600px, and text over images.

So a VML button for classic Outlook, or a table tuned by hand, does not survive. If the HTML has to arrive as written, put it in a coded template; the Outlook button pattern is that kind of code.

What size should a HubSpot email template be?

For width, coded templates read the email body width setting through {{ email_body_width }}. A drag and drop area cannot go below 624 pixels, while the AI upload will not recreate a design wider than 600px.

For weight, the editor shows an estimated size in the top right so you can stay under Gmail's clipping threshold of 102 KB. The estimate leaves out the content of personalization tokens, and each tracked link can add hundreds of characters. More in the Gmail clipping guide.

How do I connect my email sending domain in HubSpot?

Until DKIM is connected, you cannot send with your domain in From: HubSpot changes user@yourcompany.com to an address such as user=yourcompany.com@hs-domain.com on a domain it manages (HubSpot's authentication overview). Connecting a domain needs a Starter subscription, and HubSpot recommends a subdomain such as news.example.com that hosts no pages (how sending works).

As of October 2026 the path is settings, Content, Domains & URLs, the Email Sending tab, then Connect sending domain (HubSpot's connection guide). Enter an address you send from, and HubSpot generates the records to add.

• DKIM: two CNAMEs. If your DNS provider appends your domain to every host, enter hs1-123456._domainkey alone, or it becomes hs1-123456._domainkey.example.com.example.com (troubleshooting guide).
• SPF: add HubSpot's include to the record you have. HubSpot's example ends in -all; we use ~all and let DMARC enforce, as SPF, DKIM and DMARC explained sets out.
• DMARC: one TXT at _dmarc. A subdomain counts as authenticated when the root domain has one.
• MX: HubSpot lists it among the four record types, but its setup steps name only the CNAMEs and TXT records. Its MX advice is to remove a null MX (MX 0 .), which some providers reject mail from.
• Cloudflare: turn off CNAME flattening and the proxy.

Does HubSpot's DKIM align with your From domain for DMARC?

Yes, once the CNAMEs are live. HubSpot says SPF is checked against the envelope return path, which it already sets up on its shared servers. On shared IPs that return path is HubSpot's, so your aligned pass comes from DKIM. With a dedicated IP the return path is a subdomain of yours, 12345m.example.com in HubSpot's examples, so SPF can align as well.

HubSpot's DMARC examples still use pct, which RFC 9989 removed. Start at p=none with a rua address, and read the reports before tightening.

How to check it once it is live

The Email Sending tab shows each domain as Not authenticated, Partially authenticated (DKIM verified, SPF or DMARC not yet) or Authenticated (DKIM, SPF and DMARC). Records usually take 10 to 70 minutes, and up to 48 hours. From outside, a DKIM host should return a CNAME shaped like yourdomain-com.hs[#]a.dkim.hubspotemail.net., per the troubleshooting guide:

dig +short CNAME hs1-123456._domainkey.example.com
dig +short CNAME hs2-123456._domainkey.example.com
dig +short TXT _dmarc.example.com

The connection guide also tells you to look up the selector smtpapi, which does not match the hs1- hosts its setup creates. Go by your own setup screen, and by the s= value in a real message's DKIM-Signature header. A branded click tracking domain is set on the Tracking tab of the email settings (tracking settings).

Before a send, the mail-merge preview flags every empty merge field in your list, and the email domain checker reads your SPF, DKIM and DMARC records from outside. The free editor exports HTML for HubSpot. Draftship also builds and runs outbound inside a client's own platform.