mailto

Description:

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: ['[email protected]'],
cc: ['[email protected]', '[email protected]'],
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');
}
copied to clipboard
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', ''],
);
copied to clipboard
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 #

Clone the repository
Change directory to cd example/flutter
flutter run and wait for the app to start
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: [
'[email protected]',
'[email protected]',
],
cc: [
'percentage%[email protected]',
'[email protected]',
],
bcc: [
'Mike&[email protected]',
],
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();
}
}
copied to clipboard

Clone the repository
Change directory to cd example/http_server
Start HTTP server dart main.dart
Open your browser and visit localhost:3000
Click on the link
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