expresser

<!DOCTYPE html> <html> <head> <title>mailer.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="public/stylesheets/normalize.css" /> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div class="container"> <div class="page"> <div class="header"> <h1>mailer.coffee</h1> <div class="toc"> <h3>Table of Contents</h3> <ol> <li> <a class="source" href="index.html"> index.coffee </a> </li> <li> <a class="source" href="app.html"> app.coffee </a> </li> <li> <a class="source" href="cron.html"> cron.coffee </a> </li> <li> <a class="source" href="database.html"> database.coffee </a> </li> <li> <a class="source" href="downloader.html"> downloader.coffee </a> </li> <li> <a class="source" href="events.html"> events.coffee </a> </li> <li> <a class="source" href="firewall.html"> firewall.coffee </a> </li> <li> <a class="source" href="imaging.html"> imaging.coffee </a> </li> <li> <a class="source" href="logger.html"> logger.coffee </a> </li> <li> <a class="source" href="mailer.html"> mailer.coffee </a> </li> <li> <a class="source" href="settings.html"> settings.coffee </a> </li> <li> <a class="source" href="sockets.html"> sockets.coffee </a> </li> <li> <a class="source" href="utils.html"> utils.coffee </a> </li> </ol> </div> </div> <h2 id="expresser-mailer">EXPRESSER MAILER</h2> Sends and manages emails, supports templates. When parsing templates, the tags should be wrapped with normal brackets {}. Example: {contents} The base message template (which is loaded with every single sent message) must be saved as base.html, under the /emailtemplates folder (or whatever folder / base file name you have set on the settings).  <div class='highlight'><pre>class Mailer events = require "./events.coffee" fs = require "fs" lodash = require "lodash" logger = require "./logger.coffee" mailer = require "nodemailer" moment = require "moment" path = require "path" settings = require "./settings.coffee" utils = require "./utils.coffee"</pre></div> SMTP objects will be instantiated on <code>init</code>. <div class='highlight'><pre> smtp = null smtp2 = null</pre></div> Templates cache to avoid disk reads. <div class='highlight'><pre> templateCache = {}</pre></div> <h2 id="constructor-and-init">CONSTRUCTOR AND INIT</h2> Mailer constructor. <div class='highlight'><pre> constructor: -> @setEvents() if settings.events.enabled</pre></div> Bind event listeners. <div class='highlight'><pre> setEvents: => events.on "mailer.send", @send</pre></div> Init the Mailer module and create the SMTP objects. @param [Object] options Mailer init options. <div class='highlight'><pre> init: (options) => if settings.mailer.smtp.service? and settings.mailer.smtp.service isnt "" @setSmtp settings.mailer.smtp, false else if settings.mailer.smtp.host? and settings.mailer.smtp.host isnt "" and settings.mailer.smtp.port > 0 @setSmtp settings.mailer.smtp, false if settings.mailer.smtp2.service? and settings.mailer.smtp2.service isnt "" @setSmtp settings.mailer.smtp2, true else if settings.mailer.smtp2.host? and settings.mailer.smtp2.host isnt "" and settings.mailer.smtp2.port > 0 @setSmtp settings.mailer.smtp2, true</pre></div> Alert user if specified backup SMTP but not the main one. <div class='highlight'><pre> if not smtp? and smtp2? logger.warn "Mailer.init", "The secondary SMTP settings are defined but not the main one.", "Will still work, but you should set the main one instead."</pre></div> Warn if no SMTP is available for sending emails, but only when debug is enabled. <div class='highlight'><pre> if not smtp? and not smtp2? and settings.general.debug logger.warn "Mailer.init", "No main SMTP host/port specified.", "No emails will be sent out."</pre></div> Check if configuration for sending emails is properly set. @return [Boolean] Returns true if smtp server is active, otherwise false. <div class='highlight'><pre> checkConfig: => if smtp or smtp2? return true else return false</pre></div> <h2 id="outbound">OUTBOUND</h2> Sends an email to the specified address. A callback can be specified, having (err, result). @param [String] options The email message options @option options [String] body The email body in text or HTML. @option options [String] subject The email subject. @option options [String] to The “to” address. @option options [String] from The “from” address, optional, if blank use default from settings. @option options [String] template The template file to be loaded, optional. @param [Function] callback Callback (err, result) when message is sent or fails. <div class='highlight'><pre> send: (options, callback) => logger.debug "Mailer.send", options if not @checkConfig() errMsg = "SMTP transport wasn't initiated. Abort!" logger.warn "Mailer.send", errMsg, options callback errMsg, null if callback? return</pre></div> Make sure “to” address is valid. <div class='highlight'><pre> if not options.to? or options.to is false or options.to is "" errMsg = "Option 'to' is not valid. Abort!" logger.warn "Mailer.send", errMsg, options callback errMsg, null if callback? return</pre></div> Set from to default address if no <code>to</code> was set, and <code>logError</code> defaults to true. <div class='highlight'><pre> options.from = "#{settings.general.appTitle} <#{settings.mailer.from}>" if not options.from? options.logError = true if not options.logError?</pre></div> Set HTML to body, if passed. <div class='highlight'><pre> html = if options.body? then options.body.toString() else ""</pre></div> Get the name of recipient based on the <code>to</code> option. <div class='highlight'><pre> if options.to.indexOf("<") < 3 toName = options.to else toName = options.to.substring 0, options.to.indexOf("<") - 1</pre></div> Load template if a <code>template</code> was passed. <div class='highlight'><pre> if options.template? and options.template isnt "" template = @getTemplate options.template html = @parseTemplate template, {contents: html}</pre></div> Parse template keywords if a <code>keywords</code> was passed. <div class='highlight'><pre> if lodash.isObject options.keywords html = @parseTemplate html, options.keywords</pre></div> Parse final template and set it on the <code>options</code>. <div class='highlight'><pre> html = @parseTemplate html, {to: toName, appTitle: settings.general.appTitle, appUrl: settings.general.appUrl} options.html = html</pre></div> Check if <code>doNotSend</code> flag is set, and if so, do not send anything. <div class='highlight'><pre> if settings.mailer.doNotSend callback null, "The 'doNotSend' setting is true, will not send anything!" if callback? return</pre></div> Send using the main SMTP. If failed and a secondary is also set, try using the secondary. <div class='highlight'><pre> smtpSend smtp, options, (err, result) -> if err? if smtp2? smtpSend smtp2, options, (err2, result2) -> callback err2, result2 else callback err, result if callback? else callback err, result if callback?</pre></div> <h2 id="templates">TEMPLATES</h2> Load and return the specified template. Get from the cache or from the disk if it wasn’t loaded yet. Templates are stored inside the <code>/emailtemplates</code> folder by default and should have a .html extension. The base template, which is always loaded first, should be called base.html by default. The contents will be inserted on the {contents} tag. @param [String] name The template name, without .html. @return [String] The template HTML. <div class='highlight'><pre> getTemplate: (name) => name = name.replace(".html", "") if name.indexOf(".html") cached = templateCache[name]</pre></div> Is it already cached? If so do not hit the disk. <div class='highlight'><pre> if cached? and cached.expires > moment() logger.debug "Mailer.getTemplate", name, "Loaded from cache." return templateCache[name].template else logger.debug "Mailer.getTemplate", name</pre></div> Set file system reading options. <div class='highlight'><pre> readOptions = {encoding: settings.general.encoding} baseFile = utils.getFilePath path.join(settings.path.emailTemplatesDir, settings.mailer.baseTemplateFile) templateFile = utils.getFilePath path.join(settings.path.emailTemplatesDir, "#{name}.html")</pre></div> Read base and <code>name</code> template and merge them together. <div class='highlight'><pre> base = fs.readFileSync baseFile, readOptions template = fs.readFileSync templateFile, readOptions result = @parseTemplate base, {contents: template}</pre></div> Save to cache. <div class='highlight'><pre> templateCache[name] = {} templateCache[name].template = result templateCache[name].expires = moment().add "s", settings.general.ioCacheTimeout return result</pre></div> Parse the specified template to replace keywords. The <code>keywords</code> is a set of key-values to be replaced. For example if keywords is <code>{id: 1, friendlyUrl: "abc"}</code> then the tags <code>{id}</code> and <code>{friendlyUrl}</code> will be replaced with the values 1 and abc. @param [String] template The template (its value, not its name!) to be parsed. @param [Object] keywords Object with keys to be replaced with its values. @return [String] The parsed template, keywords replaced with values. <div class='highlight'><pre> parseTemplate: (template, keywords) => template = template.toString() for key, value of keywords template = template.replace new RegExp("\\{#{key}\\}", "gi"), value return template</pre></div> <h2 id="helper-methods">HELPER METHODS</h2> Helper to send emails using the specified transport and options. <div class='highlight'><pre> smtpSend = (transport, options, callback) -> try transport.sendMail options, (err, result) -> if err? if options.logError logger.error "Mailer.smtpSend", transport.host, "Could not send: #{options.subject} to #{options.to}.", err else logger.debug "Mailer.smtpSend", "OK", transport.host, options.subject, "to #{options.to}", "from #{options.from}." callback err, result catch ex callback ex</pre></div> Helper to create a SMTP object. <div class='highlight'><pre> createSmtp = (options) -> options.debug = settings.general.debug if not options.debug? options.secureConnection = options.secure if not options.secureConnection?</pre></div> Make sure auth is properly set. <div class='highlight'><pre> if not options.auth? and options.user? and options.password? options.auth = {user: options.user, pass: options.password} delete options["user"] delete options["password"]</pre></div> Check if <code>service</code> is set. If so, pass to the mailer, otheriwse use SMTP. <div class='highlight'><pre> if options.service? and options.service isnt "" logger.info "Mailer.createSmtp", "Service", options.service result = mailer.createTransport options.service, options else logger.info "Mailer.createSmtp", options.host, options.port, options.secureConnection result = mailer.createTransport "SMTP", options</pre></div> Sign using DKIM? <div class='highlight'><pre> result.useDKIM settings.mailer.dkim if settings.mailer.dkim.enabled</pre></div> Return SMTP object. <div class='highlight'><pre> return result</pre></div> Use the specified options and create a new SMTP server. @param [Object] options Options to be passed to SMTP creator. @param [Boolean] secondary If false set as the main SMTP server, if true set as secondary. <div class='highlight'><pre> setSmtp: (options, secondary) => if secondary or secondary > 0 smtp2 = createSmtp options else smtp = createSmtp options</pre></div> Force clear the templates cache. <div class='highlight'><pre> clearCache: => count = Object.keys(templateCache).length templateCache = {} logger.info "Mailer.clearCache", "Cleared #{count} templates."</pre></div> <h2 id="singleton-implementation">Singleton implementation</h2> <div class='highlight'><pre>Mailer.getInstance = -> @instance = new Mailer() if not @instance? return @instance module.exports = exports = Mailer.getInstance()</pre></div> <div class="fleur">h</div> </div> </div> </body> </html>