Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kaisellgren/mailer

Compose and send emails from Dart. Supports file attachments, HTML emails and multiple transport methods.
https://github.com/kaisellgren/mailer

Last synced: 18 days ago
JSON representation

Compose and send emails from Dart. Supports file attachments, HTML emails and multiple transport methods.

Awesome Lists containing this project

README 

        
# mailer



**mailer** is an easy-to-use library for composing and sending emails in Dart.



Mailer supports file attachments and HTML emails.



## FLUTTER developers



**This library does not work with flutter web.**  Sending mails using the SMTP is technically not possible over HTTP.



Please do NOT use mailer together with your credentials.  Extracting them is very easy and anybody could then send

mails using your account.  If you use your gmail credentials it's even worse as an attacker could read your mails as

well.



[Johannes Milke](https://github.com/JohannesMilke) has created an excellent tutorial on how to use `mailer` without

needing to embed your credentials in the flutter app.



[Flutter Tutorial - How To Send Email In Background \[2021\] Without Backend](https://www.youtube.com/watch?v=RDwst9icjAY)



The tutorial will use firebase and ask for the credentials of the android user: ![flutter-screenshot](doc/flutter_user.png)

By using the account of the android user it avoids storing your credentials in the app.



## Server developers



[Suragch](https://suragch.medium.com/) has written an excellent tutorial on

[How to send yourself email notifications from a Dart server](https://suragch.medium.com/how-to-send-yourself-email-notifications-from-a-dart-server-a7c16a1900d6)



Thanks to Suragch for bringing those tutorials to my attention.  

If you have created a tutorial yourself (or know of one) please open an issue, so that I can add it to this "list".



Note that those tutorial don't need to be in English!



## SMTP definitions



Mailer provides configurations for a few common SMTP servers.



Please create merge requests for missing configurations.



* Copy `lib/smtp_server/gmail.dart` to `lib/smtp_server/xxx.dart`

* Adapt the code.  (See `lib/smtp_server.dart` for possible arguments)

* Export the newly created SMTP server in `lib/smtp_server.dart`

* Create a pull request.



In a lot of cases you will find a configuration

in [legacy.dart](https://github.com/kaisellgren/mailer/blob/v2/lib/legacy.dart)



## Features



* Plaintext and HTML emails

* Unicode support

* Attachments

* Secure (filters and sanitizes all fields context-wise)

* Use any SMTP server like Gmail, Live, SendGrid, Amazon SES

* SSL/TLS support

* Pre-configured services (Gmail, Yahoo, Hotmail, etc.). Just fill in your username and password.



## TODO *HELP WANTED*



* Correct encoding of non ASCII mail addresses.

* Reintegrate address validation from version 1.*

* Improve Header types.  (see [ir_header.dart](lib/src/smtp/internal_representation/ir_header.dart))  

  We should choose the correct header based on the header name.  

  Known headers (`list-unsubscribe`,...) should have their own subclass.

* Improve documentation.



## Examples



### Sending an email with SMTP



See [gmail example](example/send_gmail.dart).



We also have an example which uses [gmail oauth](example/gmail_xoauth2/).



```dart

import 'package:mailer/mailer.dart';

import 'package:mailer/smtp_server.dart';



main() async {

  // Note that using a username and password for gmail only works if

  // you have two-factor authentication enabled and created an App password.

  // Search for "gmail app password 2fa"

  // The alternative is to use oauth.

  String username = '[email protected]';

  String password = 'password';



  final smtpServer = gmail(username, password);

  // Use the SmtpServer class to configure an SMTP server:

  // final smtpServer = SmtpServer('smtp.domain.com');

  // See the named arguments of SmtpServer for further configuration

  // options.  



  // Create our message.

  final message = Message()

    ..from = Address(username, 'Your name')

    ..recipients.add('[email protected]')

    ..ccRecipients.addAll(['[email protected]', '[email protected]'])

    ..bccRecipients.add(Address('[email protected]'))

    ..subject = 'Test Dart Mailer library :: 😀 :: ${DateTime.now()}'

    ..text = 'This is the plain text.\nThis is line 2 of the text part.'

    ..html = "
Test
\n
Hey! Here's some HTML content
";



  try {

    final sendReport = await send(message, smtpServer);

    print('Message sent: ' + sendReport.toString());

  } on MailerException catch (e) {

    print('Message not sent.');

    for (var p in e.problems) {

      print('Problem: ${p.code}: ${p.msg}');

    }

  }

  // DONE



  // Let's send another message using a slightly different syntax:

  //

  // Addresses without a name part can be set directly.

  // For instance `..recipients.add('[email protected]')`

  // If you want to display a name part you have to create an

  // Address object: `new Address('[email protected]', 'Display name part')`

  // Creating and adding an Address object without a name part

  // `new Address('[email protected]')` is equivalent to

  // adding the mail address as `String`.

  final equivalentMessage = Message()

    ..from = Address(username, 'Your name 😀')

    ..recipients.add(Address('[email protected]'))

    ..ccRecipients.addAll([Address('[email protected]'), '[email protected]'])

    ..bccRecipients.add('[email protected]')

    ..subject = 'Test Dart Mailer library :: 😀 :: ${DateTime.now()}'

    ..text = 'This is the plain text.\nThis is line 2 of the text part.'

    ..html = '
Test
\n
Hey! Here is some HTML content
'

    ..attachments = [

      FileAttachment(File('exploits_of_a_mom.png'))

        ..location = Location.inline

        ..cid = ''

    ];



  final sendReport2 = await send(equivalentMessage, smtpServer);



  // Sending multiple messages with the same connection

  //

  // Create a smtp client that will persist the connection

  var connection = PersistentConnection(smtpServer);



  // Send the first message

  await connection.send(message);



  // send the equivalent message

  await connection.send(equivalentMessage);



  // close the connection

  await connection.close();

}

```



## License



This library is licensed under MIT.