✉️ MailerJS-CLI

A modern command-line tool for sending emails through SMTP.

Configure your SMTP account once, then send emails with attachments to one or multiple recipients directly from your terminal.

---

About

MailerJS-CLI is a lightweight command-line tool for sending emails through SMTP. It provides a simple, interactive way to configure an email provider, compose plain text emails, HTML emails, or reusable HTML templates, attach files, and send emails to one or multiple recipients directly from your terminal.

Whether you're sending job applications, notifications, newsletters, or bulk emails, MailerJS-CLI streamlines the process with recipient validation, TXT file imports, HTML email support, reusable HTML templates, SMTP connection testing, and persistent configuration.

---

✨ Features

• 📧 Interactive email sending
• 📝 Plain text email support
• 🌐 HTML email support
• 📄 Reusable HTML template support
• 📂 Browse available HTML templates
• 🏷️ Dynamic placeholder replacement
• 👥 Send to multiple recipients
• 👥 CC & BCC recipient support
• 📄 Import recipients from TXT files
• 📎 Multiple attachment support
• ⚙️ One-time SMTP configuration
• ✏️ Interactive configuration editor
• 👀 View current SMTP configuration
• 🗑 Remove saved SMTP configuration
• ⚡ SMTP connection testing
• 🌐 Built-in SMTP provider presets
• 🛠 Custom SMTP server support
• ✅ Automatic email validation
• 🔄 Automatic duplicate removal
• 🎨 Beautiful interactive CLI
• ⏳ Progress spinners
• 📋 Sending summary
• 🔒 Secure SMTP authentication
• 💾 Persistent local configuration

---

Supported Providers

• Gmail
• Outlook
• Yahoo
• Zoho Mail
• iCloud
• Custom SMTP

---

Installation

npm install -g mailerjs-cli

---

Requirements

• Node.js 18+
• npm

Verify your installation:

node -v
npm -v

---

Quick Start

Configure your SMTP account:

mailer config

View the current configuration:

mailer config --current

Edit an existing configuration:

mailer config --edit

Reset the saved configuration:

mailer config --remove

Test your configuration:

mailer test

View available email templates:

mailer templates

Start MailerJS:

mailer

During the interactive session you can:

• Compose plain text emails.
• Send HTML emails from files.
• Use reusable HTML templates.
• Enter recipients manually.
• Import recipients from a TXT file.
• Add CC and BCC recipients.
• Attach one or multiple files.
• Review everything before sending.

---

Commands

Command	Description
mailer	Start the interactive email sender
mailer config	Configure SMTP settings
mailer config --edit	Edit an existing SMTP configuration
mailer config --current	Display the current SMTP configuration
mailer config --remove	Delete the saved SMTP configuration
mailer templates	List all available HTML templates
mailer test	Verify SMTP connection
mailer help	Show available commands
mailer version	Display installed version

---

Importing Recipients

MailerJS can import recipients directly from a plain text file.

Example:

john@example.com
jane@example.com
alex@example.com
support@example.com

Rules:

• One email address per line
• Blank lines are ignored
• Invalid email addresses are skipped automatically
• Duplicate email addresses are removed automatically
• Email addresses are normalized before validation

After importing, MailerJS displays a summary including:

• Total recipients
• Valid email addresses
• Invalid email addresses
• Duplicates removed

---

CC & BCC Support

MailerJS supports optional CC (Carbon Copy) and BCC (Blind Carbon Copy) recipients.

During the sending process you can choose whether to add CC and/or BCC recipients.

Features:

• Optional CC recipients
• Optional BCC recipients
• Multiple CC recipients
• Multiple BCC recipients
• Email validation for all recipient types

Example:

To:
john@example.com

CC:
manager@example.com
team@example.com

BCC:
archive@example.com

Recipients in CC are visible to everyone receiving the email.

Recipients in BCC remain hidden from all other recipients.

---

HTML Emails

MailerJS-CLI supports sending HTML emails directly from an HTML file.

Choose HTML File as the message format, provide the path to your HTML document, and MailerJS-CLI will load and send it as the email body.

Example:

<!DOCTYPE html>
<html>
  <body style="font-family: Arial, sans-serif;">
    <h2>Welcome!</h2>
    <p>This email was sent using <strong>MailerJS-CLI</strong>.</p>

    <a href="https://github.com/MkhalFadel/MailerJS-CLI">
      View the Project
    </a>
  </body>
</html>

---

HTML Templates

MailerJS-CLI supports reusable HTML templates with dynamic placeholders.

Templates are stored inside:

~/.mailerjs/templates

To view all available templates:

mailer templates

Example template:

Hello {{name}}

Thank you for applying to {{company}}.

Position: {{position}}

When sending an email, MailerJS-CLI automatically detects every placeholder and prompts you to provide a value.

Example:

name > John

company > OpenAI

position > Backend Developer

The placeholders are replaced before the email is sent, allowing you to reuse the same template with different content.

---

Example Workflow

$ mailer

████╗   ████╗ █████╗ ██╗██╗     ███████╗██████╗      ██╗███████╗
████╗ ████║██╔══██╗██║██║     ██╔════╝██╔══██╗     ██║██╔════╝
██╔████╔██║███████║██║██║     █████╗  ██████╔╝     ██║███████╗
██║╚██╔╝██║██╔══██║██║██║     ██╔══╝  ██╔══██╗██   ██║╚════██║
██║ ╚═╝ ██║██║  ██║██║███████╗███████╗██║  ██║╚█████╔╝███████║
╚═╝     ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚═╝  ╚═╝ ╚════╝ ╚══════╝

Modern SMTP Email CLI

Email Subject
─────────────
? > Project Update

Email Message
─────────────
? Choose format type: Plain text

Type "END" on a new line when finished.

 1 │ Hello team,
 2 │
 3 │ The latest build has been deployed successfully.
 4 │ END

Attachments
───────────
? Include attachments? Yes

? Enter file path:
~/Documents/report.pdf

? Add another attachment? Yes

? Enter file path:
~/Documents/changelog.pdf

? Add another attachment? No

Recipients
──────────
? How would you like to add recipients?
❯ Enter manually

When you finish adding recipients press Enter...

Recipient #1
────────────
? > john@example.com

Recipient #2
────────────
? > jane@example.com

Recipient #3
────────────
? >

───────────────
Email Review

Subject:
Project Update

Message:
Hello team,

The latest build has been deployed successfully.

Attachments:
~/Documents/report.pdf
~/Documents/changelog.pdf

Recipients:
john@example.com
jane@example.com

? Send emails? Yes

✔ Email sent to john@example.com
✔ Email sent to jane@example.com

Summary
───────
ℹ Total Emails: 2
✔ Sent: 2
✖ Failed: 0

---

Gmail Users

Google no longer allows SMTP login using your normal account password.

To use Gmail:

1. Enable Two-Factor Authentication.
2. Create an App Password.
3. Run:

mailer config

4. Use your Gmail address and the generated App Password.

---

Configuration

MailerJS stores its configuration locally inside your home directory.

A new configuration can be created with:

mailer config

View the current configuration:

mailer config --current

An existing configuration can be modified at any time without recreating it:

mailer config --edit

Delete the current configuration:

mailer config --remove

The interactive editor allows you to update:

• Provider
• SMTP Host (Custom SMTP only)
• SMTP Port (Custom SMTP only)
• Secure connection (Custom SMTP only)
• Email address
• Password
• Sender name

The current configuration viewer displays:

• Provider
• SMTP settings
• Account information
• Sender information

Passwords are always hidden when displayed.

Example configuration:

{
  "provider": "Gmail",
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "username": "example@gmail.com",
    "password": "****************"
  },
  "sender": {
    "name": "John Doe",
    "email": "example@gmail.com"
  }
}

---

Built With

• Node.js
• Nodemailer
• Inquirer
• Chalk
• Ora
• Figlet
• Validator.js

---

Roadmap

• CSV recipient import
• Default attachment directory
• Scheduled emails
• Verbose mode
• Rate limiting

---

Development

Clone the repository:

git clone https://github.com/MkhalFadel/MailerJS-CLI.git

Install dependencies:

npm install

link locally:

npm link

---

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a Pull Request.

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

Author

Mkhal Fadel

GitHub: https://github.com/MkhalFadel

---

Support

If you find MailerJS-CLI useful, consider giving the repository a ⭐ on GitHub. It helps others discover the project and supports future development.