Developer tools · URL encoder & decoder
How to encode a mailto: link with subject, body line breaks and ampersands
· Why it matters
mailto url-encoding html
A mailto: link with a subject and body is a URL, so spaces, line breaks and & must be percent-encoded. This post shows what breaks when they are not and how to build a link that opens correctly in mail clients.
The contact link whose subject stopped at the first space — a concrete broken mailto: and what the mail client received
Contact links like <a href="mailto:test@example.com?subject=Support Inquiry">Send</a> break because spaces in "Support Inquiry" terminate links in mail clients. Many clients receive only "Support" as subject. This occurs because mailto: links follow RFC 6068, specifying that spaces and special characters require percent-encoding in query parameters. Ampersands need %26 encoding to avoid being parameter separators.
Broken mailto: links demonstrate the problem clearly. Constructed links like <a href="mailto:test@example.com?subject=Support Inquiry&body=Reply">Contact</a> result in messages with subject "Support" only. Testing in different mail clients reveals varying tolerance: Apple Mail partially handles links, Gmail shows only "Support", Outlook fails completely.
mailto: is a URL scheme — RFC 6068 in brief, and which parts are the query string
RFC 6068 defines mailto: URL schemes with component-specific encoding rules. Unlike regular URLs, mailto: has specific rules per component. Address parts (test@example.com) remain unencoded; @ and domains are structural. Query parameters (subject, body, cc, bcc) need encoding. RFC 6068 references RFC 3986 for rules, mandating percent-encoding for spaces and special characters. Ampersands within values become %26 when appearing as data, not delimiters.
Understanding mailto: scheme structure prevents encoding mistakes. The form is: mailto:address?parameter1=value1¶meter2=value2. Question marks introduce query sections. Ampersands separating parameters remain unencoded; only ampersands within values encode as %26. If subjects contain "Tom & Jerry", encode as Tom%20%26%20Jerry. Ampersands between subject and body remain unencoded. This nested encoding is error-prone.
Encoding the subject and body — spaces as %20, line breaks as %0D%0A, and & as %26 inside values
Encoding subjects and bodies requires careful handling of spaces and special characters. Spaces become %20 in mailto: links, not plus signs unlike HTML forms. This critical difference trips up developers familiar with web forms. Line breaks encode as %0D%0A (CRLF line endings in email). Ampersands become %26. Percent signs become %25. Subjects typically contain spaces, accents, and parentheses. Bodies contain spaces, accents, line breaks.
Common encodings in mailto: links include: spaces as %20, newlines as %0D%0A, ampersands as %26, percent as %25, hash as %23, question as %3F. Non-ASCII like accents first convert to UTF-8 bytes then percent-encode. "Über report" becomes %C3%9ber%20report. "Hello! Goodbye" becomes Hello%21%0D%0AGoodbye. Encode only values, not structural ? and & characters.
Worked example: building a link with subject, two-line body and cc — the encoded result and how it appears in a mail client
Worked example: building links with subject "Meeting agenda (Sept)", body "Let us discuss: Quarterly goals", and cc "manager@example.com" demonstrates complete encoding. Subjects need: spaces as %20, parentheses as %28 and %29. Bodies need: "Let us discuss:" mostly unchanged (space is %20), line breaks as %0D%0A, "Quarterly goals" mostly unchanged. The cc field requires no encoding.
The resulting mailto: is: mailto:contact@example.com?subject=Meeting%20agenda%20%28Sept%29&body=Let%20us%20discuss%3A%0D%0AQuarterly%20goals&cc=manager@example.com. Testing in browsers reveals different mail client interpretations. Gmail opens compose windows with correct subject, two-line body, and cc. Outlook shows similar results. Apple Mail requires permissions. Older clients fail lacking body support.
Why + is wrong here — mailto: follows RFC 3986, not form encoding, so + stays a plus
Why plus signs are wrong—mailto: follows RFC 3986, not form encoding, so plus stays literal—clarifies critical distinctions. HTML form encoding uses plus for spaces in query strings. RFC 3986 and RFC 6068 both specify %20 for spaces. A mailto: with subject="Meeting+Agenda" creates subjects with literal plus signs, not spaces. This mistake happens copying form-encoding logic to mailto: generation. Plus means plus, not space.
Why this matters: developers copying form GET submission logic to mailto: generation break links. A subject "Meeting Agenda" becomes "Meeting+Agenda" in forms. In mailto: links, it creates "Meeting+Agenda" with literal pluses. Users manually fix subject lines. Testing mailto: links requires clicking them or examining generated links, not analyzing form rules.
Common mistakes — forgetting to HTML-escape the & separators in the href, and percent-encoding the @ in the address
Common mailto: building mistakes include forgetting HTML ampersand escaping in href attributes. In HTML, ampersands in attributes should be & for valid XHTML. href="mailto:address?subject=Test&body=Test" is invalid HTML; it should be href="mailto:address?subject=Test&body=Test". This represents different encoding from URL encoding. HTML parsers interpret & as & before browsers process URLs.
Testing for these mistakes requires examining HTML source and browser consoles. Right-click and select "Inspect Element" to view actual href values. Copy-paste href values into address bars (with mailto: prefix) and check mail clients. Some email links work in certain browsers but not others. Automated testing is difficult because mailto: involves external clients, making manual verification common.
What this does not cover — mail client support differences and multiple recipients in depth
What this does not cover includes mail client support differences and multiple recipients. Not all clients equally support RFC 6068 parameters. The body parameter has wide support but some older clients ignore it. The cc and bcc parameters have variable support. Multiple recipients require comma-separating email addresses, encoding commas as %2C for complex addresses. Different locales require proper UTF-8 encoding for display.
Mail client evolution affects mailto: behavior across platforms. Modern web mail clients (Gmail, Outlook.com) have better RFC 6068 compliance than older desktop clients. Mobile clients sometimes have stricter parsing. Some support rich text while others support only plain text. Developers should test with mail clients their audiences actually use. Real implementations vary despite RFC 6068 specifications.
Takeaway: encode each value, keep the structure — how the URL encoder & decoder's single-value mode gives you the encoded subject and body to paste
Takeaway: encode each value, keep structure—the URL encoder & decoder single-value mode produces encoded subjects and bodies ready to paste into links. The tool accepts unencoded values like "Meeting agenda (Sept)" and produces "Meeting%20agenda%20%28Sept%29". Copy output directly into mailto: href attributes. For multi-line bodies, paste plaintext versions with line breaks, getting %0D%0A-encoded versions.
Best practice assembles mailto: links from encoded parts rather than manual construction. When building HTML dynamically in JavaScript or templates, encode each parameter separately before concatenating with & separators. For static HTML, URL encoder & decoder reliably tests encoding before hand-writing. Document encoding processes in code comments. Test resulting mailto: links by clicking them with actual mail clients before deployment.