How to Create Custom mailto Links with Subject, Body, and Attachmentsmailto links are a simple, built-in way to open a user’s default email client with fields pre-filled: recipient, subject, body, and more. They’re useful for contact links, feedback buttons, and quick email shortcuts without needing a server-side mailer or third-party API. This article explains how mailto links work, how to build them correctly, how to encode content safely, how to suggest attachments, and best practices including accessibility and security considerations.
What is a mailto link?
A mailto link is a type of URL that uses the mailto: scheme to instruct the browser to open the user’s default email client and create a new message. The simplest form is:
When clicked, this opens a compose window addressed to [email protected].
Basic mailto components
- Recipient (to): mailto:[email protected]
- CC (carbon copy): [email protected]
- BCC (blind carbon copy): [email protected]
- Subject: subject=Your%20Subject%20Here
- Body: body=Your%20message%20here
Multiple query parameters are joined with &. Example:
mailto:[email protected]?subject=Hello&body=This%20is%20a%20test
URL encoding: why and how
Email clients read the mailto URL as plain text; spaces and special characters must be percent-encoded. Use encodeURIComponent in JavaScript or tools/online encoders when generating mailto links.
Common encodings:
- Space → %20 or +
- Newline → %0A or %0D%0A (carriage return + line feed)
- & → %26
- ? → %3F
- # → %23
Example with newline in body (HTML):
mailto:[email protected]?subject=Hi&body=Line%201%0ALine%202
Creating a mailto link in HTML
Simple example:
For multiple recipients:
Using JavaScript to build dynamic mailto links
When you need to include user-provided data (form values, selections), build the link with proper encoding:
<form id="contactForm"> <input id="name" placeholder="Your name"> <input id="email" placeholder="Your email"> <textarea id="message" placeholder="Message"></textarea> <button id="send">Open Email</button> </form> <script> document.getElementById('send').addEventListener('click', function (e) { e.preventDefault(); const name = encodeURIComponent(document.getElementById('name').value); const email = encodeURIComponent(document.getElementById('email').value); const message = encodeURIComponent(document.getElementById('message').value); const subject = encodeURIComponent('Question from ' + name); const body = encodeURIComponent('Name: ' + name + '%0AEmail: ' + email + '%0A%0A' + message); window.location.href = `mailto:[email protected]?subject=${subject}&body=${body}`; }); </script> Note: encodeURIComponent already encodes newlines as %0A; avoid double-encoding.
Adding attachments: the limitations
Standard mailto links do not support attaching files. The mailto URI scheme (RFC 2368) doesn’t include an attachments parameter, and most clients ignore non-standard parameters.
Workarounds:
- Use mailto to prefill text and instruct users to attach files manually.
- Build a downloadable file (e.g., a CSV or text file) via JavaScript, let users download it, and instruct them to attach it.
- Use a server-side mailer or an email-sending API (SendGrid, Mailgun, Amazon SES) to programmatically send emails with attachments.
- Use the native File System Access API or Web Share API (where supported) to generate shareable content — but these are not reliable across all clients for attaching to email compose windows.
Example message telling users to attach a file:
Cross-client inconsistencies
Different email clients parse mailto links differently. Common issues:
- Line break handling varies (use %0D%0A for best compatibility).
- Long bodies or subjects might be truncated.
- Some clients ignore or strip certain parameters.
- Attachments are unsupported.
Test mailto links across popular desktop clients (Outlook, Apple Mail, Thunderbird) and webmail (Gmail, Outlook.com). Webmail services often open a new compose tab/window rather than the desktop client.
Accessibility and UX considerations
- Provide clear link text (avoid “Click here”). Example: “Email support”.
- Include aria-label when link content is descriptive but not explicit about the action.
- Offer alternatives: a contact form or an email address in plain text for copy/paste.
- Warn users that mailto requires a configured email client — many public kiosk or mobile setups may not have one.
Example accessible link:
Security and privacy concerns
- Avoid putting sensitive data (passwords, API keys, personal identifiers) in mailto parameters — they may be stored in browser history or logged.
- Since mailto opens the user’s email client, any client-side data you include becomes visible to the user and potentially stored in their sent folder.
- Use server-side email for sending sensitive or automated messages.
When to use mailto vs. an email API
Use mailto when:
- You want a quick way for users to contact you without backend infrastructure.
- The message is user-initiated and not sensitive.
- You prefer letting users edit the email before sending.
Use an email API when:
- You need to attach files programmatically.
- You must send automated or transactional emails.
- You require reliable delivery tracking, templates, or rate control.
Examples and templates
Basic contact link:
Prepopulated support request:
Template with CC and BCC:
Troubleshooting common problems
- Link opens but fields are blank: check encoding and reserved characters.
- Newlines not appearing: use %0D%0A.
- Parameters ignored: client may not support certain parameters or has a bug.
- Mail client not installed: provide a fallback contact form or plain email address.
Summary (short)
mailto links are a lightweight way to open a prefilled email compose window. Use proper percent-encoding, be aware attachments aren’t supported, test across clients, and choose an email API when you need attachments or reliable delivery.
Leave a Reply