Skip to content
Tutorials Center
My learning

Topics

Lesson 51 of 73 ยท Platform integration

Launching URLs, Email, SMS and Phone Calls

Use url_launcher to open web pages, compose email with mailto, start SMS and phone calls with sms and tel, handle failures, and configure Android and iOS.

Many apps need to hand something off to the phone: "Visit our website", "Email support", "Call the restaurant", "Text me the receipt". Flutter does not do these itself; the operating system has apps for them. The official url_launcher package asks the OS to open a URI and lets the matching app (browser, mail client, dialer, messages) take over. The only skill involved is building the right URI and handling the case where nothing can open it.

Real vs stand-in. The Dart and platform snippets are real and read-only, because the site cannot start a dialer or a mail app from Flutter. The live examples are JavaScript stand-ins that build the same URIs and show the encoding pitfall that breaks email subjects.

Opening a web page

DART
import 'package:url_launcher/url_launcher.dart';

Future<void> openSite() async {
  final uri = Uri.parse('https://example.com/pricing');
  final ok = await launchUrl(uri, mode: LaunchMode.externalApplication);
  if (!ok) {
    debugPrint('Could not open $uri');
  }
}

launchUrl returns true if the OS accepted the request. The mode chooses where it opens:

LaunchMode Behavior
platformDefault The platform decides: browser on mobile, new tab on web.
externalApplication Leaves your app for the browser or the app registered for the link.
inAppBrowserView A Chrome Custom Tab or Safari view inside your app (mobile).
inAppWebView A WebView in your app.
externalNonBrowserApplication Only a native app, never a browser.

For documents the user should read and then return from, inAppBrowserView keeps them in context. Use Uri.parse only with strings you trust. If the URL comes from user input or a server, check that the scheme is one you expect (https) before launching it (security).

Email with mailto

A mailto: URI has the address as its path and optional subject, body, cc and bcc as query parameters.

DART
Future<void> emailSupport() async {
  final uri = Uri(
    scheme: 'mailto',
    path: '[email protected]',
    query: _encodeQuery({
      'subject': 'Order #1234 question',
      'body': 'Hello,\n\nMy order has not arrived.',
    }),
  );
  await launchUrl(uri);
}

// Uri's own queryParameters encode a space as "+", which many mail apps show literally.
// Encode spaces as %20 yourself:
String _encodeQuery(Map<String, String> params) => params.entries
    .map((e) => '${Uri.encodeComponent(e.key)}=${Uri.encodeComponent(e.value)}')
    .join('&');

This is the one trap with email. Passing queryParameters: to the Uri constructor percent-encodes with + for spaces (the form-encoding rule), but the mailto standard expects %20, so a subject arrives as "Order+%231234+question" in some clients. Building the query with Uri.encodeComponent produces %20.

JS Why mailto subjects show plus signs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Phone calls and SMS

DART
Future<void> call() => launchUrl(Uri(scheme: 'tel', path: '+15551234567'));

Future<void> text() => launchUrl(
  Uri(
    scheme: 'sms',
    path: '+15551234567',
    queryParameters: {'body': 'Running late, see you soon'},
  ),
);

tel: opens the dialer with the number filled in; the user still presses the call button, which is the platform's safeguard. Keep the number in international format with no spaces. sms: opens the messaging app, and body pre-fills the text. Platforms differ in how they separate the body (?body= versus &body= on some iOS versions), and spaces in the body can again appear as +, so test on real devices and prefer Uri.encodeComponent here too. Simulators and tablets without telephony cannot place calls, which is why you handle failure.

Check before you launch

canLaunchUrl asks whether anything on the device can handle the URI, so you can hide a button or show a fallback.

DART
Future<void> callOrCopy(String number) async {
  final uri = Uri(scheme: 'tel', path: number);
  if (await canLaunchUrl(uri)) {
    await launchUrl(uri);
  } else {
    await Clipboard.setData(ClipboardData(text: number));
    if (!mounted) return;
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('Number copied. Paste it into your phone app.')),
    );
  }
}

Note the mounted check after await (navigator and routes explains why). A SnackBar is covered in Material 3 widgets.

JS Build safe URIs and decide a fallback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Platform setup

Android 11 and later hides other apps from yours (package visibility), so canLaunchUrl returns false unless you declare what you intend to open. Add a <queries> block to android/app/src/main/AndroidManifest.xml:

XML
<queries>
  <intent><action android:name="android.intent.action.VIEW" /><data android:scheme="https" /></intent>
  <intent><action android:name="android.intent.action.DIAL" /><data android:scheme="tel" /></intent>
  <intent><action android:name="android.intent.action.SENDTO" /><data android:scheme="mailto" /></intent>
  <intent><action android:name="android.intent.action.SENDTO" /><data android:scheme="sms" /></intent>
</queries>

iOS needs the same declaration for schemes you query with canLaunchUrl, in ios/Runner/Info.plist:

XML
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>https</string>
  <string>tel</string>
  <string>sms</string>
  <string>mailto</string>
</array>

Launching without checking canLaunchUrl does not need these entries, but the check is how you build a graceful fallback. On the web, launchUrl opens a tab (webOnlyWindowName: '_self' reuses the current one), and tel: or mailto: depend on the browser having a handler.

Common mistakes

  • Using queryParameters for mailto and sms. Spaces turn into +. Encode the query yourself.
  • Launching an untrusted string. Validate the scheme first.
  • Calling canLaunchUrl on Android 11+ without <queries>. It answers false for everything.
  • Ignoring the return value. Tell the user when nothing could open the link.
  • Expecting a call to start automatically. tel: only fills the dialer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can a mailto subject appear with plus signs instead of spaces?

    Build the query with Uri.encodeComponent so spaces become %20, which mail apps decode correctly.
  2. 2. What does launchUrl return?

    Use the boolean to show a message or fallback when nothing could handle the URI.
  3. 3. On Android 11 and later, canLaunchUrl always returns false for tel: links. What is missing?

    Package visibility rules hide other apps unless you declare the intents you query.
  4. 4. What does launching a tel: URI do on a phone?

    The platform keeps the final call action with the user.

Summary

  • launchUrl(Uri, mode: ...) hands a URI to the OS; check the returned bool.
  • Use mailto:, tel: and sms: URIs, and encode query text with Uri.encodeComponent so spaces become %20.
  • canLaunchUrl builds fallbacks but needs <queries> on Android and LSApplicationQueriesSchemes on iOS.
  • Allow-list schemes before launching strings that came from users or servers.

Next: Wakelock, Orientation Lock and System UI