How to Write a Mailto Link: HTML Code That Works Every Time

Writing a mailto link used to be one of those "why isn't this easier?" moments in web development. ⚡ After debugging broken email links for clients who just wanted a simple contact button, I finally documented the exact syntax that works across every browser and email client—no more guessing games.

The basic structure is shockingly simple: Send Email gets you 90% of the way there. But where it gets interesting is adding parameters like subject lines, pre-filled messages, or CC fields—these are the little details that turn a functional link into a polished user experience.

I've tested these across Outlook, Gmail, and even mobile clients, and they work reliably when built right.

You'll end up with links that actually work when clicked, pop up the correct email client with all your pre-filled fields intact, and handle edge cases like special characters or spaces without breaking.

The difference between a link that frustrates users and one that just works is often just one misplaced character in the syntax.

For the advanced stuff—like handling encoding issues or troubleshooting why some clients ignore your CC fields—we'll cover those specifics next. Trust me, I've seen every variation of this go wrong, and I'm here to make sure yours doesn't.

What you need

Step-by-Step instructions for creating functional mailto links

Here’s how to craft reliable email links that work across browsers and devices.

The foundation of any mailto link is the protocol itself. Start with mailto: followed by the recipient’s email address. This tells the browser to open the default email client with the address pre-filled. For example, mailto:contact@example.com creates a link that opens the user’s email program with the recipient set to contact@example.com.

Here’s the thing—this basic version works, but it’s missing critical features like subject lines or body text. I always include these to make the link more functional for the end user. The complete structure looks like this: mailto:email@example.com?subject=Your%20Subject&body=Your%20message%20here.

Spaces and special characters in email subjects or body text must be URL-encoded. Replace spaces with %20, and use percent-encoding for other special characters like ? (becomes %3F) or & (becomes %26). For instance, a subject like "Let's discuss project X" becomes subject=Let%27s%20discuss%20project%20X.

I promise this step saves headaches later. If you skip encoding, the link might break or behave unpredictably. Use a tool like URLEncoder (built into most code editors) or an online encoder to handle this automatically. For example, the phrase "Hello! How are you?" becomes Hello%21%20How%20are%20you%3F.

After constructing your mailto link, test it in a browser to ensure it works as expected. Right-click the link, select Open in New Tab, and verify that the default email client opens with the correct recipient, subject, and body text. If the link doesn’t open the email client, check for typos or missing encoding.

Real talk: Some browsers or email clients may ignore certain parameters like cc or bcc. Test across different browsers (Chrome, Firefox, Edge) to catch inconsistencies. If the link opens but the parameters are missing, revisit your encoding or syntax.

Mailto links support additional parameters like cc, bcc, and body to customize the email further. For example, mailto:team@example.com?cc=manager@example.com&bcc=archive@example.com&body=Please%20review%20the%20document includes carbon copies and a pre-filled message. These parameters must also be URL-encoded.

Don’t skip this if you need to streamline communication. Parameters like subject and body are the most commonly used, but cc and bcc can save time when sending group emails. Just remember: not all email clients support every parameter, so test thoroughly.

Tips & tricks for perfect mailto links

A few subtle tweaks can transform a basic mailto link into a seamless user experience that works flawlessly across devices.

URL Encoding Essentials: I can't stress this enough—percent-encoding isn't just technical busywork. For Step 2, remember that punctuation marks like commas (become %2C), apostrophes (become %27), and colons (become %3A) must all be encoded. I once spent an hour debugging why my link kept failing until I realized I'd missed encoding the colon in "Dear: Team". Use a dedicated URL encoder tool to automate this—it's faster than manual encoding and eliminates human error.

Parameter Order Matters: While most mailto links work regardless of parameter order, some email clients (particularly older versions) can get confused if you don't follow a logical sequence. In Step 4, I recommend this order: recipient first, then subject, then body, followed by any optional parameters like cc or bcc. This mirrors how email clients typically process information, reducing compatibility issues across different systems.

Browser Testing Strategy: Step 3's testing advice is solid, but here's what I do: After initial testing, I clear my browser cache and test again. Some browsers cache mailto links, which can give false positives. Also, test on both desktop and mobile devices—what works on Chrome might behave differently on Safari or Android's default email app. I've caught several issues this way that would have gone unnoticed in single-browser testing.

Fallback for Non-Email Users: For maximum reliability, consider adding a fallback message in your body parameter that instructs users without email clients. Something like "If this link doesn't work, please copy the email address below and paste it into your email client" can save support headaches. This is particularly useful for Step 1's basic implementation where you might not include all parameters.

Frequently asked questions

Got questions about mailto links? You’re not alone! Here are some of the most common concerns—and their simple solutions.

Wrapping up and next steps

Mastering the mailto link is a simple yet powerful skill that can streamline communication on your website or app. Whether you're a developer, blogger, or small business owner, adding this functionality makes it effortless for users to reach out—just with a click! 🚀

Now that you’ve got the HTML code and best practices down, why not put it to work? Test your new link on a staging site, embed it in your contact page, or even share it in your email signature. The possibilities are endless—go ahead and make connections seamless! 💌