Step 1 · Read the result

One click narrows the failure to the page or the device

A mailto link does not send a message itself. It asks the browser to hand an email address to a registered handler. That can be a desktop app, a webmail service, or nothing useful. The browser and operating system make that choice, not the link.

Step 2 · Check the HTML

Reduce your real link to one address

Replace your current anchor temporarily with the minimal version below. Keepmailto: lowercase, put the email address immediately after it, and do not add a space between the scheme and address. This syntax follows the mailto URI format defined in RFC 6068.

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

If the minimal version works, the handler is available and the original link needs attention. Add each recipient or parameter back separately. If the minimal version still fails, use the four-check troubleshooting guide to inspect page scripts, the browser, and the default mail app.

Step 3 · Test parameters

Add subject and body only after the basic link passes

The first parameter starts with ?. Later parameters start with&. Encode spaces as %20, line breaks as%0A, and any literal ampersand inside a value as%26. Otherwise one field can be cut short or parsed as another parameter.

<a href="mailto:hello@example.com?subject=Website%20question&body=Hi%20there%2C%0A%0AI%20am%20testing%20this%20mailto%20link.">Email us</a>

Open the draft and compare the visible address, subject, and body with the values you intended. For a longer message, use the mailto link generator instead of encoding the URL by hand.

Step 4 · Automated test

Test the href without launching an external app

End-to-end tests become unreliable when they depend on whichever mail app happens to be installed on the test runner. Verify the anchor, parse the URI, and assert the decoded fields on the page instead.

const link = page.getByRole('link', { name: 'Email support' });

await expect(link).toHaveAttribute('href', /^mailto:/);

const href = await link.getAttribute('href');
const mailto = new URL(href!);

expect(mailto.pathname).toBe('support@example.com');
expect(mailto.searchParams.get('subject')).toBe('Website question');

This proves that your rendered page exposes the expected address and parameters. It does not prove that every visitor has a working mail handler, because that behavior lives outside your page.

Step 5 · Cross-device check

Test the outcome, not every possible email client

Run the minimal link on one desktop browser and one mobile device. Record whether a draft opens, which destination appears, and whether the address and subject survive. That small matrix catches the important difference between valid page markup and a visitor-side configuration problem.

Step 6 · Visitor fallback

Keep the valid link and add a way around local setup

When the link is correct but the visitor has no suitable handler, show the address, offer a copy action, or let them choose a webmail service. smart-mailto keeps your existing anchor and adds provider, native-mail, and copy choices on top.

One link, several exits

Let the visitor choose what works on their device

Use native mail when it is configured, open a selected webmail compose page, or copy the address without abandoning the contact attempt.

npm install @smart-mailto/core@0.3.0Copy install command

Install smart-mailto →

Gmail

Outlook

Native mail

Copy address

Questions

Mailto link testing FAQ