mailto

mailto

Simple Dart package for creating mailto links in your Flutter and Dart apps

The mailto package helps you build mailto links and provides you with an idiomatic Dart interface that:

• supports one or many to, cc, and bcc fields
• supports custom body and subject for the emails
• encodes every value for your correctly
• is blazingly fast ⚡️😜

Important links

• Read the source code and star the repo!
• Check package info on pub.dev
• Open an issue
• Read the docs
• This Dart package is created by the SMAHO development team

Usage

You may want to launch the email client on your user's phone with certain fields pre-filled. For Flutter apps, it's recommended to use the url_launcher package for launching the links you create with the mailto package.

import 'package:mailto/mailto.dart';
// For Flutter applications, you'll most likely want to use
// the url_launcher package.
import 'package:url_launcher/url_launcher.dart';

// ...somewhere in your Flutter app...
launchMailto() async {
  final mailtoLink = Mailto(
    to: ['to@example.com'],
    cc: ['cc1@example.com', 'cc2@example.com'],
    subject: 'mailto example subject',
    body: 'mailto example body',
  );
  // Convert the Mailto instance into a string.
  // Use either Dart's string interpolation
  // or the toString() method.
  await launch('$mailtoLink');
}

Validation

The package provides a simple validation function. You could use this function in an assert to catch issues in development mode.

The package doesn't validate automatically, so either use the validation function or make sure that the parameters you use are correct.

Mailto.validateParameters(
  // New lines are NOT supported in subject lines
  subject: 'new lines in subject \n FTW',
  // What does this even mean?
  cc: ['\n\n\n', ''],
);

Known limitations of mailto URIs

I tested the package manually in Flutter apps on iOS and Android (Gmail, FastMail, Yahoo email client), and in the browser on macOS, and the package has an extensive test suite that incorporates many examples from the RFC 6068 - The 'mailto' URI Scheme document.

Unfortunately, each client handle mailto links differently: Gmail does not add line-breaks in the message body, FastMail skips the bcc, Yahoo is not able to handle encoded values in subject and body, and these are only the three clients I tested. The iOS email client seems to handle everything well, so 🎸🤘🎉.

The package might also not work if the resulting mailto links are extremely long. I don't know the exact character count where the links fail, but I'd try to keep things under 1000 characters.

Important: Make sure you understand these limitations before you decide to incorporate mailto links in your app: letting users open their email clients with pre-filled values is a quick and easy way to let your users get in touch with you with extremely little development effort. At the same time, you need to keep in mind that it's very unlikely that these links are going to work consistently for all of your users.

If you need something bullet-proof, this package is not the right tool for solving your problem, so please consider alternative solutions (e.g. Flutter forms and a working backend).

In case you find potential improvements to the package, please create a pull request or let's discuss it in an issue. I might not merge all pull requests, especially changes that improve things for one client, but makes it worse for others. We consider the iOS mail app and Gmail on Android the two most important mail clients.

Examples

You'll find runnable, great examples on the project's GitHub repository in the /example folder.

Flutter example app

1. Clone the repository
2. Change directory to cd example/flutter
3. flutter run and wait for the app to start
4. You can fill out the forms with your own input or click the "Surprise me" button to see how your mail client handles tricky input

HTTP server serving an HTML web page with a mailto link

The mailto package works in any Dart program: be it Flutter, AngularDart, or on the server.

import 'dart:io';

import 'package:mailto/mailto.dart';

Future<void> main() async { 
  final mailto = Mailto(
    to: [
      'example@example.com',
      'ejemplo@ejemplo.com',
    ],
    cc: [
      'percentage%100@example.com',
      'QuestionMark?address@example.com',
    ],
    bcc: [
      'Mike&family@example.org',
    ],
    subject: 'Let\'s drink a "café"! ☕️ 2+2=4 #coffeeAndMath',
    body:
        'Hello this if the first line!\n\nNew line with some special characters őúóüűáéèßáñ\nEmoji: 🤪💙👍',
  );

  final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 3000);
  String renderHtml(Mailto mailto) => '''<html><head><title>mailto example</title></head><body><a href="$mailto">Open mail client</a></body></html>''';
  await for (HttpRequest request in server) {
    request.response
      ..statusCode = HttpStatus.ok
      ..headers.contentType = ContentType.html
      ..write(renderHtml(mailto));
    await request.response.close();
  }
}

1. Clone the repository
2. Change directory to cd example/http_server
3. Start HTTP server dart main.dart
4. Open your browser and visit localhost:3000
5. Click on the link
6. If you have an email client installed on your computer, this client will be opened when you click the link on the HTML page.

Screenshots