Clean Email HTML: 7 Steps to Avoid Gmail Clipping

Clean email HTML is not simply HTML with every unusual tag removed. A reliable cleaning pass has three separate jobs: keep the delivered markup within a practical byte budget, remove unsafe capabilities at the trust boundary, and preserve the layout features your target email clients actually support.

That distinction matters. A security sanitiser can make untrusted HTML safer without making an outbound template smaller. A minifier can reduce bytes without making unsafe markup safe. A thread stripper can isolate the newest inbound reply without changing the HTML policy at all.

Why Gmail clips large email HTML

Mailchimp documents Gmail clipping messages larger than 102KB and placing the hidden remainder behind a View entire message link. Treat 102KB as an observed Gmail behaviour and keep a margin below it rather than aiming for the last byte.

Measure the delivered message source, not the size of a template file before personalisation. The relevant bytes include text, HTML, full link URLs, tracking parameters, repeated inline styles, and any data embedded directly in the document. An image fetched from a URL is not counted as its binary file size, but a base64 data URI is part of the HTML payload.

Gmail can also combine repeated test sends into a conversation. Mailchimp recommends changing the subject or clearing earlier test messages before deciding that a production message is being clipped. Test both the generated source bytes and a newly delivered message.

Clean email HTML has three jobs

1. Control payload size

Remove markup that adds bytes without changing the approved message: duplicated style declarations, empty wrappers, editor metadata, obsolete comments, and accidental pasted formatting. Keep a measured budget in CI so later template edits cannot quietly cross it.

2. Enforce a safety policy

When HTML comes from a user, inbound message, CMS, or external template, treat it as untrusted.

OWASP recommends HTML sanitisation for untrusted HTML and warns that modifying the result after sanitisation can undo the protection.

Use a maintained, parser-based sanitiser with an explicit allowlist.

3. Preserve email-client rendering

Email HTML has a narrower rendering target than a browser page. Google publishes a defined set of CSS selectors, properties, and media queries supported by Gmail. Unsupported CSS may be ignored, so a cleaning pass must preserve tested email structure instead of applying generic web-page simplification.

A seven-step cleaning workflow

Step 1: freeze the input and measure it

Keep the original source, calculate its UTF-8 byte length, and record every external resource. This gives you a reproducible baseline and a rollback point. Do the same after template rendering, because personalisation and tracked links can make the delivered output larger than the source template.

Step 2: parse the document

Build a document tree before changing structure. Regex is useful for a narrow value after parsing, but it is not a safe HTML parser. It cannot reliably distinguish nested layout tables, attributes, comments, malformed tags, and text that merely resembles markup.

Step 3: sanitise at the trust boundary

Apply the policy before the HTML enters a trusted template or application view. Remove executable and embedded capabilities your email does not require, including scripts, event handlers, and unsafe URL schemes. Forms and frames should not be required for the message to work across clients.

Keep the sanitiser patched. The allowlist and library version are security controls, not a one-time cleanup script. Avoid appending unsanitised fragments after the pass.

Step 4: preserve intentional email structure

Retain layout tables, cell attributes, accessible text, alt text, and the tested CSS needed by the design. Do not flatten a table merely because a generic web cleaner considers it old-fashioned. Email-client compatibility, not modern website style, is the constraint.

Step 5: reduce the delivered bytes

Collapse empty wrappers, deduplicate repeated inline declarations, shorten generated identifiers, and remove editor-only metadata. Move accidental base64 data URIs out of the HTML. Keep meaningful text, accessibility attributes, and the unsubscribe mechanism intact.

Step 6: normalise inbound replies separately

Quoted history and signatures are content-history problems, not unsafe-markup problems. For an inbound workflow, decide whether the consumer needs the clean newest reply, the whole thread, or the exact raw body. Do not let a template sanitiser silently make that product decision.

Step 7: test the final artefact

Re-measure the exact rendered bytes. Check the message in the clients you support, including narrow screens and dark mode. Verify links, alt text, the plain-text alternative, and the unsubscribe path. Then run delivery checks separately; clean HTML does not repair SPF, DKIM, DMARC, reputation, or recipient consent.

What to remove, review, and preserve

Do not treat every hidden image as automatically malicious. Some senders use a reviewed open-tracking pixel under an appropriate privacy policy. The cleaning rule should make that choice explicit, not erase it accidentally or retain it by habit.

Attachments, data URIs, and cid references

Attachment handling is related to HTML size but is not the same operation. A data: image stores encoded file bytes inside the HTML and can consume the message budget quickly. A cid: source refers to a related MIME part; it should be preserved when the message intentionally uses an inline attachment and the MIME relationship is valid.

For Sendmux sends, attachments can use small inline base64 content or an uploaded blob reference. Received messages expose attachment metadata separately and provide a dedicated download endpoint. See the Sendmux Mailbox API introduction and attachment guide for the current request shapes.

The safe rule is to keep file bytes out of the HTML document, then choose between a related inline attachment and a hosted image based on the reviewed design. Do not rewrite every cid: reference to a public URL without checking privacy, expiry, and access requirements.

Clean inbound content for agents and applications

An agent or parser often needs the newest reply without the quoted conversation and signature. Sendmux keeps this choice explicit: the Mailbox API provides a raw body endpoint without cleaning and clean-content endpoints with strip_quoted and strip_signature controls.

That separation prevents two common errors. First, an application can retain exact source content when audit or debugging requires it. Second, an agent can request a focused content view without pretending that quoted-history removal is part of HTML security sanitisation.

Use mailbox events or signed webhooks to learn that new content is available, then fetch the representation the consumer needs. Keep attachment metadata attached to the message record instead of copying file bytes into the cleaned HTML.

A practical verification matrix

The practical rule

Measure first, parse before changing structure, sanitise at the trust boundary, and test the delivered artefact. Keep byte reduction, security policy, rendering compatibility, and inbound thread cleanup as separate gates. That makes failures explainable and prevents a cleaner from fixing one problem by creating another.