Troubleshooting guide · For website owners

Mailto link not working? Find where the click breaks.

If a click does nothing, opens the wrong app, or flashes a blank tab, the failure sits in one of four places: the link, page scripts, browser handler, or default mail app. Work through them in order, then add a fallback visitors can control.

Run the checks Skip to the fallback

Check 1 · Your page

Test one known-good link, then check page scripts

Start without a subject, body, CC, or BCC. A basic anchor separates invalid markup from a device that has no useful mail handler. If it still fails, confirm that page JavaScript does not cancel the click without opening a destination.

Prefer a guided check? Run the live mailto link test to compare a known-good link with your own markup.

Minimal HTML

<a href="mailto:hello@example.com">Email us</a>

If this link works

Reintroduce the subject and body one field at a time. Encode spaces, line breaks, ampersands, and other reserved characters.

Build a valid mailto link →

If this link still does nothing

Test it on another device. If the same page works there, the original browser or operating-system handler is the likely difference.

Check 2 · The browser

Look for a blocked or missing protocol handler

Browsers treat mailto: as an external protocol. A webmail service may be registered to handle it, the browser may pass it to the operating system, or a prior choice may leave no useful result.

If the click fails in Chrome, follow the Chrome-specific troubleshooting guide for handler and default-app checks.

01
Try a private window
This helps separate the page from an extension or a saved site setting. It does not reset the operating-system mail app.
02
Check protocol-handler settings
Look for mailto handling in the browser’s site or handler settings. The exact menu varies by browser and version.
03
Watch for blocked pop-ups or navigation
If custom JavaScript handles the click, confirm that it does not cancel the event without opening a destination.

Check 3 · The device

Confirm there is a default mail app

When the browser delegates the link, the operating system needs an application for email links. Installing a mail app is not always enough. It may also need to be set as the default handler.

This is where a site owner's control ends

You can fix your link and avoid cancelling the click. You cannot configure every visitor's browser or default mail app. A public site needs a fallback the visitor can choose on the page.

Check 4 · Your fallback

Give the visitor another way to continue

The right fallback depends on what the contact action needs to accomplish. Do not hide the address behind a click that may fail.

Show the address

Copy fallback

Display the email address as text or add an explicit copy action.

Offer a choice

Webmail picker

Let the visitor choose a webmail provider, native mail, or copy address.

Guarantee receipt

Contact form

Use a form when your system must validate and record the submission.

Keep the same anchor

Add webmail and copy choices without removing mailto

smart-mailto intercepts valid links when available. The original mailto URL remains the safety net when the picker cannot load or should not handle the click.

Try the upgraded link

Gmail

Outlook

Proton Mail

Yahoo Mail

Native mail

Copy address

Questions

Mailto troubleshooting FAQ

Why does clicking a mailto link do nothing?

The href may be malformed, a script may be cancelling the click, or the browser and operating system may have no useful mail handler configured. Test a minimal link first to separate link markup from device setup.

Can a website choose the visitor’s default email app?

No. A plain mailto link asks the browser and operating system to open their configured handler. The site cannot repair every visitor’s device setting.

How can I open Gmail from a mailto link?

The visitor can configure Gmail as a protocol handler in a supported browser. A site can also offer a webmail picker that opens a Gmail compose URL when the visitor chooses it.

Should I replace the mailto link with a form?

Use a form when you must validate fields, route submissions, or confirm that a request reached your system. Keep mailto when the visitor should send from their own email account.

Does smart-mailto remove the original mailto fallback?

No. It intercepts valid mailto clicks when available. If the picker cannot load or the link should not be intercepted, the original mailto URL remains the fallback.

Fix what you control

Keep the mailto link and give visitors an exit route.