HubSpot Email
Use this workflow for HubSpot email requests, including “make sure this aligns
to HubSpot emails” and “add HubSpot tokens.” It replaces the web stack,
interaction, typography, CSS-variable and animation defaults in
design-generation. Any HTML frame can export when its content passes
validation; the email frame type is not required for export.
For a review-only assignment, read hubspot-email-review and follow its review
workflow directly. Do not author content or delegate another reviewer.
Resolve the relevant design and frame(s) from conversation references, frame
names, and current application state. Use view-screen for current navigation,
selection and screens, then get-design-snapshot for the relevant source. Do
not require manual frame selection when that context identifies the target.
Apply requests about multiple named frames to those frames; ask for a target
only when the available context leaves materially different choices.
- Create the design if needed, then author complete email HTML with
create-file (fileType: "html") or generate-design (fixedCanvas: true, a
600px-wide canvasFrames placement), passing frameType: "hubspot-email"
on each email file. The frame type is stored with the screen and keeps email
authoring defaults on future edits; do not add a frame-type meta tag. To make
an email frame an ordinary screen again, call update-file with
frameType: "web". Include the leading
HubSpot header comment containing templateType: email and
isAvailableForNewContent: true so new emails are selectable. The leading
templateType: email is required; availability controls template selection
and is not a compilation requirement.
- Build a fluid 600px container using presentation tables with
cellpadding="0",
cellspacing="0", explicit widths and table-cell padding. Use inline styles
or simple class rules the exporter can inline. Media-query overrides may
remain for mobile. Use email-safe font fallback stacks matching the brand.
Keep a multi-column desktop layout intact at 600px: put its stacking
breakpoint below 600px. Let long and unbroken words wrap within constrained
table cells instead of widening the email.
Do not include scripts, Tailwind/Alpine, external stylesheets, CSS variables,
flex/grid, absolute positioning, forms, or browser-only interactions.
- Add a nonempty hidden preheader element with
data-email-preheader. Include
visible company footer text with {{ site_settings.company_name }},
{{ site_settings.company_street_address_1 }}, {{ site_settings.company_city }},
and {{ site_settings.company_state }}. Include a visible anchor whose href
is exactly {{ unsubscribe_link }} for both Unsubscribe and Preferences links;
HubSpot uses it for the subscription preferences page. Do not invent a
subscription_preferences_url alias. Optional unsubscribe_link_single and
unsubscribe_link_all URLs opt out of this email type or all email;
view_as_page_url opens the web version. Use the
official HubL variable reference.
Keep footer text and a nonempty unsubscribe label visible outside the preheader,
including after inherited/class styles. Prefer readable 14px or larger footer
type with sufficient contrast; 14px is a HubSpot recommendation, not an export
minimum. Preserve these tokens on follow-ups.
- Use
{{ personalization_token('contact.firstname', 'there') }} for contact
personalization, with a literal default and no filters. This export requires
the function form and rejects direct contact.* tokens. HubSpot does not
support personalization filters in email; CMS/blog examples do not establish
email support. The
official function reference
documents the default argument, and the
filter reference
excludes personalization filters in emails. Dynamic CTA defaults must be
actual absolute HTTP(S), mailto, or tel URLs; empty strings, plain text and
script/data URLs are not fallbacks. Preserve HubL in exported HTML, never
fictional customer values. HubL control blocks ({% ... %}) are unsupported.
- Verify CTA destinations against the user's approved sources, the referenced
repository, or official product documentation. Confirm the destination serves
the CTA's stated purpose; a plausible-looking or reachable URL is not enough.
Research missing destinations before reporting a remaining user decision;
do not invent a repository or signup URL and call it finished.
- Hero images are optional. Images you include require publicly reachable HTTPS
PNG/JPEG/GIF sources, explicit positive pixel width and height, and alt text
(empty alt only for decorative images). Describe what the rendered image
actually shows; verify inherited alt text against the preview rather than
copying a stale description. Private app/blob URLs, SVGs, data/blob
URLs, relative paths, local assets and CSS background images cannot be handed
off as reliable email assets; obtain a public email-safe asset or omit it.
To convert an ordinary web frame, use the resolved designId and fileId to
read its current snapshot. Keep its approved copy, content hierarchy and
branding, and re-author its layout using the email contract above. Save a new
sibling HTML file in the same design with a unique filename; preserve the
source frame. Adding HubSpot tokens or the email frame type alone does not
convert browser layout. Existing email-safe content, including unmarked HTML,
can be refined in place with edit-design after a fresh snapshot. Re-read the
saved frame and confirm the original is unchanged after creating a sibling.
After saving, call export-hubspot-html with id (design id) and the saved
fileId. For a conversion that keeps the original business links, pass
preserveLinksFromFileId with the original content frame's ID, not a branding
reference or the converted frame itself. This checks destination preservation;
still review link labels and media meaning against the original content.
Fix reported markup/token/image/link problems and retry until validation
succeeds. Then call take-design-screenshot once for that exact designId and
fileId, with widths: [600, 375] and templatePreview: "hubspot-email".
This returns both images for visual inspection from one browser allocation.
This opt-in preview uses clearly fake company values and literal contact defaults
in an in-memory HTML copy; source and exported HTML keep their HubL tokens.
Inspect returned preview.unresolvedTokens and resolve unsupported expressions
rather than treating their literal text as final layout. This is sample browser
layout evidence, not HubSpot compilation or inbox-rendering proof.
For personalized content, use sampleContactValues on this same preview action
to test normal and deliberately long/unbroken names and populated dynamic CTA
fields. Pass an array such as [{field: "contact.firstname", value: "Alex"}],
with at most 8 unique fields and values up to 500 characters. Each contact.field
must match a supported personalization_token call in the frame. Omit a
field to inspect its literal default. Check preview.usedContactFields and
preview.unresolvedTokens. Samples are in-memory only: do not create QA frame
copies just to test recipient variants. Include a 320px preview for complex
layouts or long/unbroken text, then repair the email CSS and repeat the affected
samples before the final default 600/375 pass.
Inspect both returned images and their diagnostics
for overflow, clipped copy, broken or distorted images, and unreadable content;
repair problems and render both widths again after layout changes. A successful
HTML export alone does not complete these visual checks. If rendering is
unavailable, report that check as unfinished instead of calling the email ready.
Optional independent review
After successful export validation and desktop/mobile visual checks, hand off
the HTML with truthful limits. Independent review is optional and runs when the
user explicitly requests it.
For a requested independent review, use agent-teams with a short read-only
review task. Put the target/reference IDs, campaign facts, approved destinations
and fresh index.source.contentHash fingerprints from
get-design-surface-index in the child instructions. These fingerprints are
opaque values, not SHA-256 digests or versionHash values. Ask the reviewer to
read hubspot-email-review. Child tool access is inherited; read-only is an
instruction rather than an enforced restriction.
Use read-result with waitMs: 20000 to await the requested review, continuing
bounded waits while it is queued or running. Read current target/reference
fingerprints again before relying on its findings. Report an incomplete or
stale review honestly; do not present it as a completed review. The parent owns
any requested repairs and repeats export/affected previews after changes.
Finish concisely with the saved email and verified HTML handoff. Mention actual
remaining gaps or researched CTA decisions; omit unrequested audit/publishing
checklists, canvas coordinates and style inventories. Offer manual import
without claiming HubSpot compilation or inbox fidelity.
1---2name: hubspot-email3description: >-4 Create, convert, personalize, and validate HubSpot marketing email HTML.5 Use when creating emails, aligning existing frames with HubSpot, adding6 personalization tokens, or exporting HTML, including follow-ups.7metadata:8 source: https://skillmd.com/skills/builderio/hubspot-email9---1011# HubSpot Email1213Use this workflow for HubSpot email requests, including “make sure this aligns14to HubSpot emails” and “add HubSpot tokens.” It replaces the web stack,15interaction, typography, CSS-variable and animation defaults in16`design-generation`. Any HTML frame can export when its content passes17validation; the email frame type is not required for export.1819For a review-only assignment, read `hubspot-email-review` and follow its review20workflow directly. Do not author content or delegate another reviewer.2122Resolve the relevant design and frame(s) from conversation references, frame23names, and current application state. Use `view-screen` for current navigation,24selection and screens, then `get-design-snapshot` for the relevant source. Do25not require manual frame selection when that context identifies the target.26Apply requests about multiple named frames to those frames; ask for a target27only when the available context leaves materially different choices.2829- Create the design if needed, then author complete email HTML with30 `create-file` (`fileType: "html"`) or `generate-design` (`fixedCanvas: true`, a31 600px-wide `canvasFrames` placement), passing `frameType: "hubspot-email"`32 on each email file. The frame type is stored with the screen and keeps email33 authoring defaults on future edits; do not add a frame-type meta tag. To make34 an email frame an ordinary screen again, call `update-file` with35 `frameType: "web"`. Include the leading36 HubSpot header comment containing `templateType: email` and37 `isAvailableForNewContent: true` so new emails are selectable. The leading38 `templateType: email` is required; availability controls template selection39 and is not a compilation requirement.40- Build a fluid 600px container using presentation tables with `cellpadding="0"`,41 `cellspacing="0"`, explicit widths and table-cell padding. Use inline styles42 or simple class rules the exporter can inline. Media-query overrides may43 remain for mobile. Use email-safe font fallback stacks matching the brand.44 Keep a multi-column desktop layout intact at 600px: put its stacking45 breakpoint below 600px. Let long and unbroken words wrap within constrained46 table cells instead of widening the email.47 Do not include scripts, Tailwind/Alpine, external stylesheets, CSS variables,48 flex/grid, absolute positioning, forms, or browser-only interactions.49- Add a nonempty hidden preheader element with `data-email-preheader`. Include50 visible company footer text with `{{ site_settings.company_name }}`,51 `{{ site_settings.company_street_address_1 }}`, `{{ site_settings.company_city }}`,52 and `{{ site_settings.company_state }}`. Include a visible anchor whose href53 is exactly `{{ unsubscribe_link }}` for both Unsubscribe and Preferences links;54 HubSpot uses it for the subscription preferences page. Do not invent a55 `subscription_preferences_url` alias. Optional `unsubscribe_link_single` and56 `unsubscribe_link_all` URLs opt out of this email type or all email;57 `view_as_page_url` opens the web version. Use the58 [official HubL variable reference](https://developers.hubspot.com/docs/cms/reference/hubl/variables).59 Keep footer text and a nonempty unsubscribe label visible outside the preheader,60 including after inherited/class styles. Prefer readable 14px or larger footer61 type with sufficient contrast; 14px is a HubSpot recommendation, not an export62 minimum. Preserve these tokens on follow-ups.63- Use `{{ personalization_token('contact.firstname', 'there') }}` for contact64 personalization, with a literal default and no filters. This export requires65 the function form and rejects direct `contact.*` tokens. HubSpot does not66 support personalization filters in email; CMS/blog examples do not establish67 email support. The68 [official function reference](https://developers.hubspot.com/docs/cms/reference/hubl/functions#personalization-token)69 documents the default argument, and the70 [filter reference](https://developers.hubspot.com/docs/cms/reference/hubl/filters)71 excludes personalization filters in emails. Dynamic CTA defaults must be72 actual absolute HTTP(S), mailto, or tel URLs; empty strings, plain text and73 script/data URLs are not fallbacks. Preserve HubL in exported HTML, never74 fictional customer values. HubL control blocks (`{% ... %}`) are unsupported.75- Verify CTA destinations against the user's approved sources, the referenced76 repository, or official product documentation. Confirm the destination serves77 the CTA's stated purpose; a plausible-looking or reachable URL is not enough.78 Research missing destinations before reporting a remaining user decision;79 do not invent a repository or signup URL and call it finished.80- Hero images are optional. Images you include require publicly reachable HTTPS81 PNG/JPEG/GIF sources, explicit positive pixel width and height, and alt text82 (empty alt only for decorative images). Describe what the rendered image83 actually shows; verify inherited alt text against the preview rather than84 copying a stale description. Private app/blob URLs, SVGs, data/blob85 URLs, relative paths, local assets and CSS background images cannot be handed86 off as reliable email assets; obtain a public email-safe asset or omit it.8788To convert an ordinary web frame, use the resolved `designId` and `fileId` to89read its current snapshot. Keep its approved copy, content hierarchy and90branding, and re-author its layout using the email contract above. Save a new91sibling HTML file in the same design with a unique filename; preserve the92source frame. Adding HubSpot tokens or the email frame type alone does not93convert browser layout. Existing email-safe content, including unmarked HTML,94can be refined in place with `edit-design` after a fresh snapshot. Re-read the95saved frame and confirm the original is unchanged after creating a sibling.9697After saving, call `export-hubspot-html` with `id` (design id) and the saved98`fileId`. For a conversion that keeps the original business links, pass99`preserveLinksFromFileId` with the original content frame's ID, not a branding100reference or the converted frame itself. This checks destination preservation;101still review link labels and media meaning against the original content.102Fix reported markup/token/image/link problems and retry until validation103succeeds. Then call `take-design-screenshot` once for that exact `designId` and104`fileId`, with `widths: [600, 375]` and `templatePreview: "hubspot-email"`.105This returns both images for visual inspection from one browser allocation.106This opt-in preview uses clearly fake company values and literal contact defaults107in an in-memory HTML copy; source and exported HTML keep their HubL tokens.108Inspect returned `preview.unresolvedTokens` and resolve unsupported expressions109rather than treating their literal text as final layout. This is sample browser110layout evidence, not HubSpot compilation or inbox-rendering proof.111For personalized content, use `sampleContactValues` on this same preview action112to test normal and deliberately long/unbroken names and populated dynamic CTA113fields. Pass an array such as `[{field: "contact.firstname", value: "Alex"}]`,114with at most 8 unique fields and values up to 500 characters. Each `contact.field`115must match a supported `personalization_token` call in the frame. Omit a116field to inspect its literal default. Check `preview.usedContactFields` and117`preview.unresolvedTokens`. Samples are in-memory only: do not create QA frame118copies just to test recipient variants. Include a 320px preview for complex119layouts or long/unbroken text, then repair the email CSS and repeat the affected120samples before the final default 600/375 pass.121Inspect both returned images and their diagnostics122for overflow, clipped copy, broken or distorted images, and unreadable content;123repair problems and render both widths again after layout changes. A successful124HTML export alone does not complete these visual checks. If rendering is125unavailable, report that check as unfinished instead of calling the email ready.126127## Optional independent review128129After successful export validation and desktop/mobile visual checks, hand off130the HTML with truthful limits. Independent review is optional and runs when the131user explicitly requests it.132133For a requested independent review, use `agent-teams` with a short read-only134review task. Put the target/reference IDs, campaign facts, approved destinations135and fresh `index.source.contentHash` fingerprints from136`get-design-surface-index` in the child instructions. These fingerprints are137opaque values, not SHA-256 digests or `versionHash` values. Ask the reviewer to138read `hubspot-email-review`. Child tool access is inherited; read-only is an139instruction rather than an enforced restriction.140141Use `read-result` with `waitMs: 20000` to await the requested review, continuing142bounded waits while it is queued or running. Read current target/reference143fingerprints again before relying on its findings. Report an incomplete or144stale review honestly; do not present it as a completed review. The parent owns145any requested repairs and repeats export/affected previews after changes.146147Finish concisely with the saved email and verified HTML handoff. Mention actual148remaining gaps or researched CTA decisions; omit unrequested audit/publishing149checklists, canvas coordinates and style inventories. Offer manual import150without claiming HubSpot compilation or inbox fidelity.