{"id":22930172,"url":"https://github.com/jhuckaby/pixl-mail","last_synced_at":"2025-08-12T15:30:58.943Z","repository":{"id":57325206,"uuid":"36574932","full_name":"jhuckaby/pixl-mail","owner":"jhuckaby","description":"A very simple class for sending e-mail via SMTP or local sendmail.","archived":false,"fork":false,"pushed_at":"2024-09-27T05:08:53.000Z","size":20,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-03T07:08:01.723Z","etag":null,"topics":["email","nodemailer","sendmail","smtp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhuckaby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-30T20:43:32.000Z","updated_at":"2024-09-27T05:08:41.000Z","dependencies_parsed_at":"2024-06-19T00:25:31.762Z","dependency_job_id":"67028a0c-f9d2-4c43-8f20-9018f264dc75","html_url":"https://github.com/jhuckaby/pixl-mail","commit_stats":{"total_commits":20,"total_committers":1,"mean_commits":20.0,"dds":0.0,"last_synced_commit":"fe18790da94af7201b55d403b168d023fc55771c"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhuckaby%2Fpixl-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhuckaby%2Fpixl-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhuckaby%2Fpixl-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhuckaby%2Fpixl-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhuckaby","download_url":"https://codeload.github.com/jhuckaby/pixl-mail/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229636800,"owners_count":18102351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","nodemailer","sendmail","smtp"],"created_at":"2024-12-14T10:26:47.262Z","updated_at":"2024-12-14T10:26:56.432Z","avatar_url":"https://github.com/jhuckaby.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdetails\u003e\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n\u003c!-- toc --\u003e\n- [Overview](#overview)\n- [Usage](#usage)\n\t* [Placeholder Substitution](#placeholder-substitution)\n\t* [Loading From Files](#loading-from-files)\n\t* [Attachments](#attachments)\n\t* [HTML Emails](#html-emails)\n\t* [Options](#options)\n\t* [Logging](#logging)\n\t* [Debugging](#debugging)\n- [License](#license)\n\n\u003c/details\u003e\n\n# Overview\n\nThis module provides a very simple e-mail sender, which leans heavily on the awesome [nodemailer](https://nodemailer.com/) package.  It layers on the ability to pass in a complete e-mail message with headers and body in one string (or file), and optionally perform placeholder substitution using [sub()](https://www.npmjs.com/package/pixl-tools#sub) from the [pixl-tools](https://www.npmjs.com/package/pixl-tools) package.  Auto-detects HTML or plain text e-mail body, and supports custom headers and attachments as well.\n\n# Usage\n\nUse [npm](https://www.npmjs.com/) to install the module:\n\n```sh\nnpm install pixl-mail\n```\n\nThen use `require()` to load it in your code:\n\n```js\nconst PixlMail = require('pixl-mail');\n```\n\nInstantiate a mailer object and pass in the SMTP hostname (defaults to `127.0.0.1`) and the port number (defaults to `25`):\n\n```js\nlet mail = new PixlMail( 'smtp.myserver.com', 25 );\nlet mail = new PixlMail( '127.0.0.1' );\nlet mail = new PixlMail();\n```\n\nSend mail using the `send()` method.  Pass in the complete e-mail message as a multi-line string including `To`, `From` and `Subject` headers, and a callback:\n\n```js\nlet message = \n\t\"To: president@whitehouse.gov\\n\" + \n\t\"From: citizen@email.com\\n\" + \n\t\"Subject: State Budget\\n\" +\n\t\"\\n\" +  \n\t\"Dear Mr. President,\\nOur state needs more money.\\n\";\n\nmail.send( message, function(err) {\n\tif (err) console.error( \"Mail Error: \" + err );\n} );\n```\n\nFor multiple recipients, simply separate them by commas on the `To` line.  You can also specify `Cc` and/or `Bcc` headers, as well as any custom MIME headers.\n\n## Placeholder Substitution\n\nThe library supports a simple e-mail templating system, where you can insert `[bracket_placeholders]` in your e-mail message, and have the library fill them with appropriate content from a separate object.  This feature uses the [sub()](https://github.com/jhuckaby/pixl-tools#sub) function from the [pixl-tools](https://github.com/jhuckaby/pixl-tools) package.\n\nAs an example, imagine a welcome e-mail for a new user who has signed up for your app.  You have the welcome e-mail \"template\" stored separately, and want to fill in the user's e-mail address, full name and username at sending time.  Here is how to do this:\n\n```js\n// email template\nlet message = \n\t\"To: [email]\\n\" + \n\t\"From: support@myapp.com\\n\" + \n\t\"Subject: Welcome to My App, [full_name]!\\n\" +\n\t\"\\n\" +  \n\t\"Dear [full_name],\\nWelcome to My App!  Your username is '[username]'.\\n\";\n\n// placeholder args\nlet user = {\n\tusername: \"jhuckaby\",\n\tfull_name: \"Joseph Huckaby\",\n\temail: \"jhuckaby@email.com\"\n};\n\nmail.send( message, user, function(err) {\n\tif (err) console.log(err);\n} );\n```\n\nSo in this case our e-mail template has several placeholders, including `[email]`, `[full_name]` and `[username]`.  These are pulled from the `user` object which is passed to `send()` as the 2nd argument.  So the final e-mail that would be sent is:\n\n```\nTo: jhuckaby@email.com\nFrom: support@myapp.com\nSubject: Welcome to My App, Joseph Huckaby!\n\nDear Joseph Huckaby,\nWelcome to My App!  Your username is 'jhuckaby'.\n```\n\nYou can actually use a complex hash / array tree of arguments, and then specify `[filesystem/style/paths]` or `[dot.style.paths]` in your placeholders.  See the [sub()](https://github.com/jhuckaby/pixl-tools#sub) docs for details.\n\n## Loading From Files\n\nYou can specify a file path instead of the raw message, like this:\n\n```js\nlet user = {\n\tusername: \"jhuckaby\",\n\tfull_name: \"Joseph Huckaby\",\n\temail: \"jhuckaby@email.com\"\n};\n\nmail.send( \"conf/emails/new_user_welcome.txt\", user, function(err) {\n\tif (err) console.log(err);\n} );\n```\n\n## Attachments\n\nTo attach files, include an `attachments` array in your `args` object, and specify a `filename` and `path` for each one.  This is passed directly to [nodemailer](https://nodemailer.com/), so you can use all of their attachment features.  Example:\n\n```js\nlet args = {\n\tattachments: [\n\t\t{ filename: \"contract.pdf\", path: \"files/contracts/4573D.PDF\" },\n\t\t{ filename: \"policy.pdf\", path: \"files/misc/POLICY-2015.PDF\" }\n\t]\n};\n\nmail.send( message, args, function(err) {\n\tif (err) console.error( \"Mail Error: \" + err );\n} );\n```\n\nFor details, see the [Attachments](https://nodemailer.com/message/attachments/) section in the [nodemailer](https://nodemailer.com/) docs.\n\n## HTML Emails\n\nIf you want to send HTML formatted e-mails, the library will automatically detect this.  Just provide the headers in plain text, two end-of-lines, then start your HTML markup.  Example:\n\n```js\nlet message = \n\t\"To: president@whitehouse.gov\\n\" + \n\t\"From: citizen@email.com\\n\" + \n\t\"Subject: State Budget\\n\" + \n\t\"\\n\" + \n\t\"\u003ch1\u003eDear Mr. President,\u003c/h1\u003e\\n\u003cp\u003e\u003cb\u003ePlease\u003c/b\u003e give our state more \u003ci\u003emoney\u003c/i\u003e.\u003c/p\u003e\\n\";\n\nmail.send( message, function(err) {\n\tif (err) console.error( \"Mail Error: \" + err );\n} );\n```\n\n**Note:** Your e-mail body must begin with an HTML tag for it to be recognized.\n\n## Options\n\nYou can set a number of options using the `setOption()` or `setOptions()` methods.  These are passed directly to the underlying [nodemailer](https://nodemailer.com/) module, so please check out their documentation for details.  Examples include setting timeouts, SSL, and authentication.\n\nThe `setOption()` method takes one single key/value to set or replace, while `setOptions()` accepts an object containing multiple keys/values.\n\n```js\nmail.setOption( 'secure', true ); // use ssl\nmail.setOption( 'auth', { user: 'fsmith', pass: '12345' } );\n\nmail.setOptions({\n\tconnectionTimeout: 10000, // milliseconds\n\tgreetingTimeout: 10000, // milliseconds\n\tsocketTimeout: 10000 // milliseconds\n});\n```\n\nYou can also use local [sendmail](https://nodemailer.com/transports/sendmail/), if you have that configured on your server.  To do this, set the following options, and tune as needed:\n\n```js\nmail.setOptions({\n\t\"sendmail\": true,\n\t\"newline\": \"unix\",\n\t\"path\": \"/usr/sbin/sendmail\"\n});\n```\n\n## Logging\n\nYou can optionally attach a [pixl-logger](https://github.com/jhuckaby/pixl-logger) compatible log agent, which will log all the [nodemailer](https://nodemailer.com/) debug messages at level 9, with the component column set to `Mailer`.  To use this feature, call the `attachLogAgent()` method on your class instance, and pass in your pixl-logger instance:\n\n```js\nmail.attachLogAgent( logger );\n```\n\n## Debugging\n\nThe `send()` method actually returns three arguments: the error (if any), the final composed mail body with headers (after all macro expansion), and a full debug log capture from [nodemailer](https://nodemailer.com/).  Here is how to use them:\n\n```js\nmail.send( message, function(err, message, log) {\n\tif (err) console.error( \"Mail Error: \" + err );\n\t\n\tconsole.log( \"Full composed message: \" + message );\n\t\n\tlog.forEach( function(row) {\n\t\tconsole.log( ...row );\n\t} );\n} );\n```\n\nEach log row will contain two elements: the log message itself, and an object containing additional metadata.  These come directly from [nodemailer](https://nodemailer.com/).  Here is an example excerpt:\n\n```\nCreating transport: nodemailer (6.4.11; +https://nodemailer.com/; SMTP/6.4.11[client:6.4.11])\n{\"component\":\"mail\",\"tnx\":\"create\"}\n\nSending mail using SMTP/6.4.11[client:6.4.11]\n{\"component\":\"mail\",\"tnx\":\"transport\",\"name\":\"SMTP\",\"version\":\"6.4.11[client:6.4.11]\",\"action\":\"send\"}\n\nResolved localhost as ::1 [cache miss]\n{\"component\":\"smtp-connection\",\"sid\":\"N5uAYhHPKsY\",\"tnx\":\"dns\",\"source\":\"localhost\",\"resolved\":\"::1\",\"cached\":false}\n\nConnection established to ::1:25\n{\"component\":\"smtp-connection\",\"sid\":\"N5uAYhHPKsY\",\"tnx\":\"network\",\"localAddress\":\"::1\",\"localPort\":53068,\"remoteAddress\":\"::1\",\"remotePort\":25}\n\n220 joemax.local ESMTP Postfix\n{\"component\":\"smtp-connection\",\"sid\":\"N5uAYhHPKsY\",\"tnx\":\"server\"}\n\nEHLO joemax.local\n{\"component\":\"smtp-connection\",\"sid\":\"N5uAYhHPKsY\",\"tnx\":\"client\"}\n```\n\n# License\n\n**The MIT License (MIT)**\n\n*Copyright (c) 2015 - 2024 Joseph Huckaby.*\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhuckaby%2Fpixl-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhuckaby%2Fpixl-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhuckaby%2Fpixl-mail/lists"}