Skip to content
webtoapkfree

How do I handle mailto and tel links in a WebView app?

Handle WebView mailto and tel links in shouldOverrideUrlLoading: send mailto to ACTION_SENDTO, tel to ACTION_DIAL, return true and catch the exception.

GuidesNookesh Karri

Light cover card with the title 'How do I handle mailto and tel links in a WebView app?' in dark text and a green accent bar

To handle WebView mailto and tel links, catch them in shouldOverrideUrlLoading. Send mailto: to an ACTION_SENDTO Intent and tel: to an ACTION_DIAL Intent, wrap startActivity in a try/catch, and return true so the WebView stops loading the URL. No phone permission is needed.

A WebView only knows how to load web pages, so a mailto: or tel: link has nowhere to go. When your app sets a WebViewClient, every tap stays inside the WebView, and the WebView tries to load the address as a page.

The result is a grey error page with net::ERR_UNKNOWN_URL_SCHEME, the symptom in this Stack Overflow question about a mailto link. The WebViewClient reference warns that the callback can fire with non-HTTP(S) schemes, and that calling loadUrl with such a URL will fail.

Leave the HTML alone. The fix goes in native code.

Each non-web scheme maps to one Android Intent action. That choice decides which apps appear and whether you need a permission.

Link in your HTML Intent action What the user sees
mailto:[email protected] ACTION_SENDTO Mail apps only, with a draft open
tel:+1-201-555-0123 ACTION_DIAL Dialer with the number filled in
sms:+1-201-555-0123 ACTION_SENDTO Messaging app with a new message
geo:47.6,-122.3 ACTION_VIEW A maps app at that point
intent://...#Intent;...;end Parsed, then ACTION_VIEW The target app, or a fallback page

The common intents guide says to use ACTION_SENDTO with the mailto: scheme when you want only email apps to answer. Plain ACTION_VIEW works too, but it can offer chat and social apps.

For calls, the Intent reference is blunt: there are restrictions on which apps can start a call, and most apps should use ACTION_DIAL. ACTION_CALL can’t dial emergency numbers, and it throws a SecurityException if you declare CALL_PHONE without it being granted. ACTION_DIAL needs no permission. The user makes the final tap.

The same guide documents geo: forms such as geo:47.6,-122.3 for a point and geo:0,0?q= plus an address for a search.

The shouldOverrideUrlLoading code for mailto, tel and sms

Override the WebResourceRequest version of shouldOverrideUrlLoading, check the scheme, and build the matching Intent. The reference lists that version as added in API level 24, with the String version deprecated in the same release.

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
        val uri = request.url
        val intent = when (uri.scheme) {
            "http", "https" -> return false // normal pages: let the WebView load them
            "mailto", "sms", "smsto" -> Intent(Intent.ACTION_SENDTO, uri)
            "tel" -> Intent(Intent.ACTION_DIAL, uri)
            else -> Intent(Intent.ACTION_VIEW, uri) // geo:, market: and others
        }
        try {
            view.context.startActivity(intent)
        } catch (e: ActivityNotFoundException) {
            Toast.makeText(view.context, "No app can open this link", Toast.LENGTH_SHORT).show()
        }
        return true
    }
}

Four details matter:

  1. Return true for every non-web link. The reference says true aborts the load, while false lets the WebView carry on and show the error page.
  2. Pass the whole URI as Intent data. Mail apps read ?subject= and ?body= straight from the mailto: address.
  3. Keep the try/catch. The common intents guide warns that an app crashes on startActivity when no app can receive the Intent. A Wi-Fi tablet with no dialer is the usual case.
  4. Don’t call loadUrl here. Your own https pages return false and load on their own.

If you need the parts of an email address yourself, for example to prefill a native contact form, MailTo.parse() returns the To, CC, subject and body. Its getTo() can return several addresses separated by a comma and a space.

Why the tap does nothing on Android 11 and newer

On apps that target Android 11 (API level 30) or higher, a resolveActivity() check can return null even when Gmail is installed. Android hides other apps from yours unless the manifest declares them, so the “is there an app?” check fails and your code never calls startActivity.

It’s an easy trap to copy. The email sample in the common intents guide wraps startActivity in exactly that resolveActivity() check. The package visibility guide recommends the other way round: start the Intent and handle ActivityNotFoundException if no app is available.

That guide also says startActivity doesn’t need package visibility. You only need a <queries> entry when your UI must know in advance, for instance to hide a “Call us” button on tablets. Its SMS example declares a SENDTO intent with the smsto scheme.

My take: drop the pre-check. A toast when nothing opens is honest, and you skip a manifest entry you’d have to keep in sync.

Half of the bugs blamed on WebView come from the link itself. A badly encoded mailto: or tel: address fails in Chrome too, so check the HTML first.

For email links, the mailto URI standard sets the rules:

  • Separate several recipients with commas: mailto:[email protected],[email protected].
  • Spaces become %20, never a raw space. Line breaks in the body become %0D%0A.
  • Treat ?, = and & as delimiters. Encode them if they appear inside a subject.

Example: mailto:[email protected]?subject=Late%20order&body=Hi%2C%0D%0AMy%20order%20is%20late.

The standard also notes that mailto: addresses on public pages expose addresses to harvesting. If spam is already a problem, use a contact form.

For phone links, the tel URI standard says global numbers start with +. Hyphens, dots and brackets are allowed as visual separators, but spaces are not. Local numbers must carry a phone-context parameter, so the full + form is the safer choice: tel:+1-201-555-0123.

An intent:// link is a packed Android Intent that a page uses to open a specific app. Chrome understands it, but a WebView doesn’t, so the generic ACTION_VIEW branch above won’t open it.

The Chrome intents guide shows the format: intent://scan/#Intent;scheme=zxing;package=...;end. An optional S.browser_fallback_url names a page to open when no app launches.

To support these links, add an "intent" branch that calls Intent.parseUri(uri.toString(), Intent.URI_INTENT_SCHEME). Then follow Chrome’s own guard rails:

  • Add CATEGORY_BROWSABLE and clear any component, so only apps that opted into browser launches can answer.
  • If startActivity throws, read the browser_fallback_url extra and load that address in the WebView instead.

These links show up most on payment and banking pages, so run one checkout flow end to end before you ship.

Test each scheme on a real phone and on a device without a SIM. Emulators often lack a mail app, which hides the crash path you most need to see.

Check that:

  • mailto: opens a mail app with the subject and body filled in.
  • Tapping tel: opens the dialer without asking for a permission.
  • The same tel: link on a Wi-Fi tablet shows your toast instead of crashing.
  • Pressing back from the mail app or dialer returns to the same page.
  • Normal https links on your domain still load inside the WebView.

The guide on testing an APK on your phone covers installing a debug build for this. Outside web links follow similar rules, explained in opening external links in the browser.

A limit worth knowing about no-code builders

Link handling lives in native code, so a no-code WebView builder makes these choices for you. Web2Apk’s own guides say it doesn’t promise every website behaves in a WebView the way it does in Chrome, and external links are one of the named differences.

If your site depends on intent:// payment links or custom schemes, test them in the generated APK before you rely on them. A hand-written wrapper gives you full control of the code above. For a plain contact page with a mailto: and a tel: link, the website to APK guide walks through building and testing the app.

Broken contact links also hurt at review. A reviewer who taps “Email us” and gets an error page sees an unfinished app, one of the patterns behind minimum functionality rejections.

FAQ

WebView loads web pages, not mail or phone addresses. When a tap reaches a mailto: or tel: URL, the WebView tries to load it as a page and fails. Catch the scheme in shouldOverrideUrlLoading and start an Intent instead.

No. Use ACTION_DIAL, which opens the dialer with the number filled in and lets the user press call. ACTION_CALL places the call directly and is the action that needs CALL_PHONE.

A resolveActivity() check can return null on apps that target API level 30 or higher, because other apps are hidden unless the manifest declares them. Call startActivity() and catch ActivityNotFoundException instead of checking first.

Pass the whole mailto: URI to an ACTION_SENDTO Intent as its data. Mail apps read the subject and body from the URI. If you need the parts yourself, MailTo.parse() returns the To, CC, subject and body.

Should shouldOverrideUrlLoading return true or false for mailto?

Return true. True tells the WebView to stop loading that URL, which is what you want once you have handed it to another app. False would let the WebView try to load it and show the error page.

Sources