Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smaho-engineering/mailto
Simple Dart package for creating mailto links in your Flutter apps or web pages
https://github.com/smaho-engineering/mailto
dart dart-lang flutter flutter-package mailto open-emails package packages pub pubdev web-package
Last synced: 28 days ago
JSON representation
Simple Dart package for creating mailto links in your Flutter apps or web pages
- Host: GitHub
- URL: https://github.com/smaho-engineering/mailto
- Owner: smaho-engineering
- License: bsd-3-clause
- Created: 2019-12-21T19:50:50.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-04-13T19:22:03.000Z (over 3 years ago)
- Last Synced: 2024-09-29T16:04:47.100Z (about 1 month ago)
- Topics: dart, dart-lang, flutter, flutter-package, mailto, open-emails, package, packages, pub, pubdev, web-package
- Language: Dart
- Homepage: https://pub.dev/packages/mailto
- Size: 334 KB
- Stars: 20
- Watchers: 2
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `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 ⚡️😜
[](https://github.com/smaho-engineering)
[](https://travis-ci.org/smaho-engineering/mailto 'Check build status on TravisCI') [](https://codecov.io/gh/smaho-engineering/mailto 'Check coverage info')
[](https://pub.dev/packages/mailto 'See mailto package info on pub.dev')
[](https://github.com/smaho-engineering/mailto 'Star our repository on GitHub!')
## Important links
* [Read the source code and **star the repo!**](https://github.com/smaho-engineering/mailto)
* [Check package info on `pub.dev`](https://pub.dev/packages/mailto)
* [Open an issue](https://github.com/smaho-engineering/mailto/issues)
* [Read the docs](https://pub.dev/documentation/mailto/latest/)
* This Dart package is created by the [SMAHO development team](https://github.com/smaho-engineering)
## 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`](https://pub.dev/packages/url_launcher) package for launching the links you create with the `mailto` package.
```dart
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');
}
```
### 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.
```dart
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](https://tools.ietf.org/html/rfc6068) 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**](https://github.com/smaho-engineering/mailto/tree/master/example).
### Flutter example app
1. Clone the repository
1. Change directory to `cd example/flutter`
1. `flutter run` and wait for the app to start
1. 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.
```dart
import 'dart:io';
import 'package:mailto/mailto.dart';
Future 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) => '''mailto exampleOpen mail client''';
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
1. Change directory to `cd example/http_server`
1. Start HTTP server `dart main.dart`
1. Open your browser and visit `localhost:3000`
1. Click on the link
1. 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
