Skip to content

Latest commit

 

History

History
92 lines (57 loc) · 3.52 KB

README.md

File metadata and controls

92 lines (57 loc) · 3.52 KB
Raw

Ringo Mail

  • This package provides a simple interface to javax.mail for sending email via RingoJS.
  • Its xUnit tests cover/show API usage (well, mail#send... ;) ).
  • Main module's equipped with JsDoc and some further documentation's below.
  • TODOs and bugs go up on corresponding GitHub issue tracker.

Usage Examples

Sending an email is as simple as:

var mail = require('ringo/mail');
mail.send({from: 'John Doe <[email protected]>', to: '[email protected]'});

Note the two supported mail address syntaxes above (so incl. "personal name").

To send to multiple recipients simply use an array:

mail.send({to: ['[email protected]', '[email protected]']});

BTW, if from's omitted javax.mail's fallback mechanism is used.

Setting the subject (defaults to being empty if omitted):

mail.send({to: '[email protected]', subject: '[FTW] Ohai'});

So, to actually send some text:

mail.send({from: '[email protected]', to: '[email protected]', text: 'Hi'});

By default an email with empty string text is created if omitted.
Now, in case you want to send HTML content instead:

mail.send({from: '[email protected]', to: '[email protected]',
        html: '<strong>Hi</strong>'});

Apart from that, here's how to set cc, bcc and replyTo:

mail.send({to: '[email protected]', cc: 'Hugo <[email protected]>',
        bcc: ['[email protected]', 'Bob <[email protected]>'],
        replyTo: '[email protected]'});

So, as with to, arrays are used to specify multiple addresses.

Of course, you can define host (defaults to "localhost") and port (defaults to 25) as well:

mail.send({host: 'smtp.example.com', port: 465, encrypt: true,
        to: 'Hugo <[email protected]>'});

Note how above the port was set to SSL's 465.
In combination with encrypt set to true this enables SSL encryption.
If you want to use TLS encryption instead, simply set encrypt to true and leave port definition out:

mail.send({host: 'smtp.example.com', encrypt: true,
        to: '[email protected]'});

Naturally, if you like to be more specific, you can additionally provide TLS' port 587 info there too.

Here's how to setup SMTP auth usage:

mail.send({username: 'jdoe', password: 'secret', to: '[email protected]'});

Furthermore, you can also set arbitrary mail headers:

mail.send({to: '[email protected]', headers:
        {'Content-Language': 'en', Keywords: 'ringojs, javax.mail'}});

Attachments can be added by simply specifying respective path info of files:

mail.send({to: '[email protected]', attachments:
        module.resolve('foo.jpg')});

So e.g., you can use module#resolve for easily getting relative paths.
Adding multiple file attachments again works with arrays as expected:

mail.send({to: '[email protected]', attachments:
        [module.resolve('foo.jpg'), module.resolve('bar.pdf')]});

Now, if you'd like to have some global mail configuration within an app,
you can simply add something along the following inside its config.js:

exports.mail = {from: 'Foo <[email protected]>', host: 'smtp.example.com',
        username: 'jdoe', password: 'secret'};

You can override such global config settings in any app mail#send call.

Well, that's basically it. :)