mailto 0.2.0+3

Simple Dart package for creating mailto links in your Flutter apps

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. Use the url_launcher 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: ['[e-mail]'],
    cc: ['[e-mail]', '[e-mail]'],
    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');
}

Skip validation

By default, the package validates the input via assertions upon object creation. If you wish to skip this validation step, set the validate argument to MailtoValidate.never.

// We don't know why you'd want to do this, but just in case, we made the validation optional.
final mailtoLink = Mailto(
    // Who you are sending this email to? 
    to: null,
    // What does this even mean?
    cc: ['\n\n\n', null, ''],
    // New lines are not supported in subject lines
    subject: 'new lines in subject \n FTW',
    // Skip validation and hope for the best 🤞💣
    validate: MailtoValidate.never,
  );

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 🎸🤘🎉.

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 might be a quick and easy way to let your users get in touch with you with little development efforts. 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, 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.

/example

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

Flutter example app

0. Clone the repository
1. Change directory to cd example/flutter
2. flutter run and wait for the app to start
3. 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: [
      '[e-mail]',
      '[e-mail]',
    ],
    cc: [
      '[e-mail]',
      'QuestionMark?[e-mail]',
    ],
    bcc: [
      'Mike&[e-mail]',
    ],
    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();
  }
}

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