{"id":13433850,"url":"https://github.com/bahdcoder/friendly-mail","last_synced_at":"2025-10-07T00:58:58.125Z","repository":{"id":57146998,"uuid":"185098149","full_name":"bahdcoder/friendly-mail","owner":"bahdcoder","description":"📩 Mail provider for elegantly sending emails in node js.","archived":false,"fork":false,"pushed_at":"2019-11-03T15:54:29.000Z","size":30,"stargazers_count":42,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-28T16:13:46.067Z","etag":null,"topics":["javascript","mailer","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bahdcoder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-06T00:31:23.000Z","updated_at":"2024-05-19T11:38:07.000Z","dependencies_parsed_at":"2022-09-06T13:02:24.840Z","dependency_job_id":null,"html_url":"https://github.com/bahdcoder/friendly-mail","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdcoder%2Ffriendly-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdcoder%2Ffriendly-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdcoder%2Ffriendly-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahdcoder%2Ffriendly-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bahdcoder","download_url":"https://codeload.github.com/bahdcoder/friendly-mail/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223688671,"owners_count":17186298,"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":["javascript","mailer","nodejs"],"created_at":"2024-07-31T02:01:38.003Z","updated_at":"2025-10-07T00:58:53.087Z","avatar_url":"https://github.com/bahdcoder.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Friendly Mail 📩\n\n[![Build Status](https://travis-ci.org/fullstack-js-online/mail.svg?branch=master)](https://travis-ci.org/fullstack-js-online/mail)\n\n#### Elegant mail sender for node js.\n\nFriendly Mail is simple, clean, and modern and easy to use email sending package for Nodejs built on top of [nodemailer](https://github.com/nodemailer/nodemailer) and uses driver implementations from [Adonis Mail](https://github.com/adonisjs/adonis-mail).\n\nSupported mail drivers: smtp, mailgun, amazon-ses, sparkpost, ethereal\n\n\u003c!-- \u003cimg src=\"https://badge.fury.io/js/%40fullstackjs%2Fmail.png\" alt=\"\"\u003e\n\u003cimg src=\"https://travis-ci.org/fullstack-js-online/mail.svg?branch=master\" alt=\"\"\u003e\n\u003cimg src=\"https://img.shields.io/github/issues/fullstack-js-online/mail.svg\" alt=\"\"\u003e --\u003e\n\n### Installation\n\nYou can install the package using npm or yarn\n\n```bash\nnpm install --save friendly-mail\n# Using yarn\nyarn add friendly-mail\n```\n\n### Create a mail configuration file\n\nTo configure what drivers you'll be using to send emails, view engines and more, you need to generate a `mail.config.js` file in your project's root.\n\n```bash\n# Using npm\nnpx friendlymail init\n\n# Using yarn\nyarn friendlymail init\n```\n\n### Setting it up\n\nHere's an example of the configuration:\n\n```js\nmodule.exports = {\n    /*\n    |--------------------------------------------------------------------------\n    | Connection\n    |--------------------------------------------------------------------------\n    |\n    | Connection to be used for sending emails. Each connection needs to\n    | define a driver too.\n    |\n    */\n    connection: process.env.MAIL_CONNECTION || 'smtp',\n\n    /*\n    |--------------------------------------------------------------------------\n    | Views\n    |--------------------------------------------------------------------------\n    |\n    | This configuration defines the folder in which all emails are stored.\n    | If it is not defined, /mails is used as default.\n    |\n    */\n    views: '/mails',\n\n    /*\n    |--------------------------------------------------------------------------\n    | View engine\n    |--------------------------------------------------------------------------\n    |\n    | This is the view engine that should be used. The currently supported are:\n    | handlebars, edge\n    |\n    */\n    viewEngine: 'handlebars',\n\n    /*\n    |--------------------------------------------------------------------------\n    | SMTP\n    |--------------------------------------------------------------------------\n    |\n    | Here we define configuration for sending emails via SMTP.\n    |\n    */\n    smtp: {\n        driver: 'smtp',\n            pool: true,\n            port: process.env.SMTP_PORT || 2525,\n            host: process.env.SMTP_HOST || 'smtp.mailtrap.io',\n            secure: false,\n            auth: {\n            user: process.env.MAIL_USERNAME,\n            pass: process.env.MAIL_PASSWORD\n        },\n        maxConnections: 5,\n        maxMessages: 100,\n        rateLimit: 10\n    },\n\n    /*\n    |--------------------------------------------------------------------------\n    | SparkPost\n    |--------------------------------------------------------------------------\n    |\n    | Here we define configuration for spark post. Extra options can be defined\n    | inside the `extra` object.\n    |\n    | https://developer.sparkpost.com/api/transmissions.html#header-options-attributes\n    |\n    | extras: {\n    |   campaign_id: 'sparkpost campaign id',\n    |   options: { // sparkpost options }\n    | }\n    |\n    */\n    sparkpost: {\n        driver: 'sparkpost',\n        // endpoint: 'https://api.eu.sparkpost.com/api/v1',\n        apiKey: process.env.SPARKPOST_API_KEY,\n        extras: {}\n    },\n\n    /*\n    |--------------------------------------------------------------------------\n    | Mailgun\n    |--------------------------------------------------------------------------\n    |\n    | Here we define configuration for mailgun. Extra options can be defined\n    | inside the `extra` object.\n    |\n    | https://mailgun-documentation.readthedocs.io/en/latest/api-sending.html#sending\n    |\n    | extras: {\n    |   'o:tag': '',\n    |   'o:campaign': '',,\n    |   . . .\n    | }\n    |\n    */\n    mailgun: {\n        driver: 'mailgun',\n        domain: process.env.MAILGUN_DOMAIN,\n        apiKey: process.env.MAILGUN_API_KEY,\n        extras: {}\n    },\n\n    /*\n    |--------------------------------------------------------------------------\n    | Ethereal\n    |--------------------------------------------------------------------------\n    |\n    | Ethereal driver to quickly test emails in your browser. A disposable\n    | account is created automatically for you.\n    |\n    | https://ethereal.email\n    |\n    */\n    ethereal: {\n        driver: 'ethereal'\n    }\n}\n```\n\nThe `mail.config.js` file exports an object. The following configuration variables are required:\n\n- `connection`: This represents the name of the driver to use.\n- `views`: This is the folder in which all your emails are stored. It defaults to `/mails`\n- `viewsEngine`: This defines what templating engine you are using for emails. For now, only [handlebars](http://handlebarsjs.com/) and [edge](https://edge.adonisjs.com) are supported\n\nThe last configuration required is a configuration object specific to the driver. Here's an example configuration for `smtp`:\n```js\n    smtp: {\n        driver: 'smtp',\n        pool: true,\n        port: process.env.SMTP_PORT || 2525,\n        host: process.env.SMTP_HOST || 'smtp.mailtrap.io',\n        secure: false,\n        auth: {\n            user: process.env.MAIL_USERNAME,\n            pass: process.env.MAIL_PASSWORD\n        },\n        maxConnections: 5,\n        maxMessages: 100,\n        rateLimit: 10\n    },\n```\n\n### Usage\n\nHere's a sample piece of code to send an email:\n\n```js\nconst Mail = require('friendly-mail')\n\nconst nameOfEmail = 'confirm-email'\n\nconst recipientName = 'John Doe'\nconst recipientEmail = 'john.doe@friendly.mail.ru'\n\nconst subject = 'Please confirm your email address.'\n\n// Send the mail using async/await\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .send()\n```\n\nNote: All publicly exposed methods on the `Mail` class are chainable, except the `send` and `sendRaw` which return `Promises`.\n\n### Common use cases\n\n#### Generating emails\nThe package ships with a command to generate help you scaffold emails.\n\n```bash\n# Using npm\nnpx friendlymail generate activate-account\n# Using yarn\nyarn friendlymail generate activate-account\n```\n\n#### Passing data to templates\nThe `data` method can be used to set data that will be passed to the email template.\n\n```js\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .data({\n        name: 'John Doe',\n        url: 'https://google.com'\n    })\n    .send()\n```\n\n#### Setting cc and bcc for a mail\n\n```js\nawait new Mail(nameOfEmail)\n    .inReplyTo('jane@doe.com', 'Jane Doe')\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .cc('eren.stales@yahoomail.com', 'Eren Stales')\n    .bcc('steve.dickson@gmail.com', 'Steve Dickson')\n    .send()\n```\n\n#### Sending emails to multiple recipients\n\nThe `to` method can recieve an array of address objects to send emails to multiple users. This also works for all other methods that set user addresses like `from cc bcc inReplyTo replyTo` and `sender`\n\n```js\nawait new Mail(nameOfEmail)\n    .inReplyTo([{ address: 'jane@doe.com', email: 'Jane Doe' }])\n    .to([{ address: 'foo@bar.com', name: 'Foo' }])\n    .subject('Monthly Newsletter')\n    .cc([{ address: 'eren.stales@yahoomail.com', name: 'Eren Stales' }])\n    .bcc([{ address: 'steve.dickson@gmail.com', name: 'Steve Dickson' }])\n    .send()\n```\n\n#### Sending mails with attachments\nThe `attach` and `attachData` methods can be used to send attachments\n\n```js\n// Attaching an existing file\n\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .attach('/absolute/path/to/file')\n    .send()\n\n// Attaching buffer as attachment with a custom file name\nconst filename = 'hello.txt'\nconst rawData = new Buffer('hello')\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .attachData(rawData, filename)\n    .send()\n\n// Attaching readstream as attachment with a custom file name\nconst filename = 'hello.txt'\nconst rawData = fs.createReadStream('hello.txt')\n\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .attachData(rawData, filename)\n    .send()\n\n// Attaching string as attachment with a custom file name\nconst filename = 'hello.txt'\nconst rawData = 'hello'\n\nawait new Mail(nameOfEmail)\n    .to(recipientEmail, recipientName)\n    .subject(subject)\n    .attachData(rawData, filename)\n    .send()\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahdcoder%2Ffriendly-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbahdcoder%2Ffriendly-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahdcoder%2Ffriendly-mail/lists"}