Email Address Obfuscation

Email Address Obfuscation

Purpose

Publish contact email addresses on a static website without feeding harvesters: a JavaScript-assembled mailto pattern (the only technique that blocked 100% of live harvesters in testing) implemented so it survives a strict CSP, degrades accessibly without JavaScript, and is verified end to end so no plain address leaks from any served file.

When to use

Before a contact email goes onto any public page — and when auditing an existing site where addresses appear in HTML, JavaScript string literals, or auth-page error messages. Apply alongside static-website-config-and-csp (the decoder must fit the site's CSP) and before an address starts receiving spam, not after.

Inputs expected

Partial inputs are fine.

• The address(es) to publish and the pages/components that reference them
• The site's CSP (especially script-src) and whether a contact form exists or is planned
• Any email templates or files that legitimately must contain the plain address

Guiding principles

• JavaScript assembly is the only technique that fully works. 2026 honeypot testing against roughly 700 live harvesters ranks the options: JavaScript-assembled addresses blocked 100%, HTML entity encoding only 95–99%, and image or CSS-reversal tricks block bots but break screen readers and copy-paste. Major platforms use a contact form or support portal as the primary channel and never leave a raw mailto in HTML — prefer a form as the primary path where one exists.
• Use the self-implemented Scrape Shield pattern. Store the address as XOR-hex in a data attribute on a <span> (first byte is the key), have a tiny same-origin script rebuild a normal mailto anchor at load, and provide a <noscript> fallback showing "name [at] domain [dot] tld" so no-JS visitors still get the address accessibly.
• Sweep beyond mailto anchors. Addresses inside JS string literals (auth-page error messages, form fallback text) are regex-harvestable from source — build them at runtime with ['name','domain.tld'].join('@'). Leave a real mailto only in files that must contain it (email templates), unlinked and noindexed.
• Keep the decoder an external same-origin file so a strict CSP (script-src 'self') needs no change — no inline script, no new CSP source.
• Never hand-write or improvise encoded payloads. Generate them with the real encoder or copy a payload verbatim from an already-shipped page, then decode-verify each one before deploying — an invented hex string looks plausible and decodes to garbage. Keep a decode one-liner handy; payloads for the same address may legitimately differ because keys are random per instance.
• Verify by fetching, not by reading source. Curl every served page and grep for the plain address — the proof is that no served byte stream contains it.

Process

1. Inventory — every occurrence of each address: HTML anchors, JS literals, error strings, templates; note which files must keep the plain form.
2. Choose the primary channel — contact form where available; obfuscated mailto for direct-contact points.
3. Encode — run the encoder per instance (random key per payload); place XOR-hex payloads in data-* attributes on spans; add the <noscript> "[at]/[dot]" fallback.
4. Wire the decoder — one external same-origin script that rebuilds mailto anchors at load; no CSP change on a script-src 'self' site.
5. Fix JS literals — replace embedded addresses with runtime join('@') assembly.
6. Decode-verify every payload before deploying — each must round-trip to the exact intended address.
7. Verify live — curl every served page and grep for each plain address; confirm only the intended template files contain it, unlinked and noindexed.

Output format

1. Address inventory — every occurrence, its treatment (form / obfuscated / runtime-assembled / legitimately plain)
2. Implementation — payload spans, decoder file, noscript fallbacks, CSP confirmation
3. Verification log — per-payload decode check; per-page curl+grep result
4. Residual plain addresses — which files keep them and why, with unlinked/noindex status

Quality checklist

• No plain address in any served HTML, JS, or error string (curl + grep proven)
• Payloads generated by the real encoder or copied verbatim — none hand-written; each decode-verified
• Decoder is an external same-origin file; CSP unchanged on a script-src 'self' site
• <noscript> fallback present and screen-reader friendly ("name [at] domain [dot] tld")
• JS-literal addresses assembled at runtime with join('@')
• Remaining plain addresses confined to files that must contain them, unlinked and noindexed

Avoid

• HTML entity encoding as the protection — 1–5% of harvesters read straight through it
• Image or CSS-reversal tricks — they break screen readers and copy-paste
• Inline decoder scripts on a CSP site — keep the decoder external and same-origin
• Hand-writing a "plausible" hex payload — it decodes to garbage; generate or copy verbatim, then verify
• Assuming two different payloads for one address indicate an error — keys are random per instance
• Forgetting addresses in JS string literals and error messages — they are harvested from source like any other text

Example usage

"Our contact page has a plain mailto: link and the password-reset page embeds the support address in an error string. The site runs a script-src 'self' CSP. Obfuscate every published address the way Cloudflare's Scrape Shield does, keep it accessible without JavaScript, and prove nothing served still contains the plain address."

Source: This skill is sourced from the Matrix Skills library. Learn more at the AI Agent Skills Library.