Practical guide · Vanilla JavaScript

Keep your mailto link. Give visitors a better way to open it.

Add one package and one initializer. Your existing contact link opens a webmail picker when smart-mailto is available and stays a normal mailto link when it isn't.

Try the upgraded link Jump to the code

Step 1

Keep the HTML you already have

smart-mailto listens for clicks on valid mailto anchors across the document. You don't need to replace the anchor with a custom component or remove its subject and body.

Your existing HTML

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

Step 2

Install the core package

The core package is framework-agnostic and has no runtime dependencies.

Terminal

npm install @smart-mailto/core

Step 3

Initialize smart-mailto once

Put this in your browser entry file. One capture-phase listener handles current and future mailto links on the page.

main.js

import { initSmartMailto } from '@smart-mailto/core';

initSmartMailto({
  theme: 'auto',
  autoDetectGeo: true,
});

That's the full migration.

You can keep adding normal mailto anchors. The same initializer handles them.

What visitors get

A picker that adapts without an IP lookup

A valid mailto click opens the provider picker with the recipient, subject, and body preserved. Provider order can reflect the recipient's email domain, a saved choice, and regional signals from the browser's timezone and language. Geo detection makes no network request.

Gmail

Outlook

Proton Mail

Yahoo Mail

Fallback behavior

The original link remains the safety net

JavaScript is unavailable

The browser still sees the original mailto anchor and can open its configured mail app.

The picker cannot load

smart-mailto redirects back to the original mailto URL so native behavior can continue.

The recipient is empty or invalid

smart-mailto does not intercept the click. The browser handles the link normally.

Ready to ship

Test the picker, then add the initializer to your site.

Try the upgraded link

Need configuration options? Read the config reference.