quick-mail 0.0.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chetan Khulage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# Quick Mail
+
+A simple and quick email sending package for Node.js. Built on top of Nodemailer with sensible defaults for Gmail.
+
+## Installation
+
+```bash
+npm install quick-mail
+```
+
+## Quick Start
+
+```typescript
+import { QuickMail } from "quick-mail";
+
+// Initialize with your Gmail credentials
+QuickMail.init({
+  email: "your-email@gmail.com",
+  password: "your-gmail-app-password",
+});
+
+// Send an email
+const result = await QuickMail.send({
+  to: "recipient@example.com",
+  subject: "Hello from QuickMail!",
+  html: "<h1>Welcome!</h1><p>This is a test email.</p>",
+});
+
+if (result.success) {
+  console.log("Email sent!", result.messageId);
+} else {
+  console.error("Failed:", result.error);
+}
+```
+
+## Configuration Options
+
+### `QuickMail.init(config)`
+
+| Option       | Type    | Default          | Description                                                        |
+| ------------ | ------- | ---------------- | ------------------------------------------------------------------ |
+| `email`      | string  | **required**     | Your email address used for sending (SMTP username)                |
+| `password`   | string  | **required**     | SMTP password. For Gmail, use App Password from Google Account     |
+| `smtpHost`   | string  | `smtp.gmail.com` | SMTP server hostname                                               |
+| `smtpPort`   | number  | `587`            | SMTP server port (587 for TLS, 465 for SSL)                        |
+| `smtpSecure` | boolean | auto             | Use SSL/TLS connection (auto-detects: false for 587, true for 465) |
+| `senderName` | string  | -                | Display name shown in recipient's inbox                            |
+
+### `QuickMail.send(options)`
+
+| Option        | Type            | Required | Description                         |
+| ------------- | --------------- | -------- | ----------------------------------- |
+| `to`          | string \| array | yes      | Recipient email(s)                  |
+| `subject`     | string          | yes      | Email subject                       |
+| `html`        | string          | yes\*    | HTML content (\*or `text` required) |
+| `text`        | string          | yes\*    | Plain text (\*or `html` required)   |
+| `from`        | string          | -        | Sender (defaults to `email`)        |
+| `cc`          | string \| array | -        | CC recipients                       |
+| `bcc`         | string \| array | -        | BCC recipients                      |
+| `replyTo`     | string          | -        | Reply-to address                    |
+| `attachments` | Attachment[]    | -        | File attachments                    |
+
+## Examples
+
+### Basic Email
+
+```typescript
+await QuickMail.send({
+  to: "friend@example.com",
+  subject: "Hello!",
+  html: "<p>How are you?</p>",
+});
+```
+
+### Multiple Recipients
+
+```typescript
+await QuickMail.send({
+  to: ["user1@example.com", "user2@example.com"],
+  cc: "manager@example.com",
+  subject: "Team Update",
+  html: "<p>Here's the weekly update...</p>",
+});
+```
+
+### With Attachments
+
+```typescript
+await QuickMail.send({
+  to: "client@example.com",
+  subject: "Invoice",
+  html: "<p>Please find the invoice attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", path: "./invoice.pdf" },
+    { filename: "readme.txt", content: "Hello World!" },
+  ],
+});
+```
+
+### Custom SMTP Server
+
+```typescript
+QuickMail.init({
+  email: "your-email@outlook.com",
+  password: "your-password",
+  smtpHost: "smtp.office365.com",
+  smtpPort: 587,
+});
+```
+
+### With Display Name
+
+```typescript
+QuickMail.init({
+  email: "noreply@company.com",
+  password: "password",
+  senderName: "Company Name",
+});
+
+// Emails will show: "Company Name" <noreply@company.com>
+```
+
+## Utility Methods
+
+```typescript
+// Verify SMTP connection
+const isConnected = await QuickMail.verify();
+
+// Check if initialized
+const ready = QuickMail.isInitialized();
+
+// Reset/disconnect
+QuickMail.reset();
+```
+
+## Gmail App Password
+
+To use with Gmail, you need an App Password:
+
+1. Go to [Google Account Security](https://myaccount.google.com/security)
+2. Enable 2-Step Verification
+3. Go to App Passwords
+4. Generate a new app password for "Mail"
+5. Use that 16-character password in the `password` field
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+/**
+ * Configuration options for initializing QuickMail
+ */
+interface QuickMailConfig {
+    /** Your email address used for sending emails (SMTP username) */
+    email: string;
+    /** SMTP password for authentication. For Gmail, use an App Password generated from Google Account settings */
+    password: string;
+    /** SMTP server hostname. Default: smtp.gmail.com */
+    smtpHost?: string;
+    /** SMTP server port. Default: 587 (TLS) */
+    smtpPort?: number;
+    /** Enable SSL/TLS secure connection. Default: auto-detects (false for port 587, true for port 465) */
+    smtpSecure?: boolean;
+    /** Display name shown in recipient's inbox. If not provided, only email address is shown */
+    senderName?: string;
+}
+/**
+ * Options for sending an email
+ */
+interface SendMailOptions {
+    /** Recipient email address(es). Can be a single email string or array of emails */
+    to: string | string[];
+    /** Email subject line shown in recipient's inbox */
+    subject: string;
+    /** HTML formatted email content. Recommended for rich formatting */
+    html?: string;
+    /** Plain text email content. Used as fallback if HTML is not supported by recipient's email client */
+    text?: string;
+    /** Sender email address. If not provided, uses the email from init() configuration */
+    from?: string;
+    /** CC (Carbon Copy) recipients - visible to all recipients */
+    cc?: string | string[];
+    /** BCC (Blind Carbon Copy) recipients - hidden from other recipients */
+    bcc?: string | string[];
+    /** Reply-To email address. Responses will be sent to this address instead of the 'from' address */
+    replyTo?: string;
+    /** File attachments to include in the email */
+    attachments?: Attachment[];
+}
+/**
+ * Email attachment configuration
+ */
+interface Attachment {
+    /** Name of the file as it will appear to the recipient */
+    filename: string;
+    /** Local file path or URL to the file. Example: './document.pdf' or 'https://example.com/file.pdf' */
+    path?: string;
+    /** Raw file content as string or Buffer. Use this instead of 'path' for in-memory files */
+    content?: string | Buffer;
+    /** MIME type of the file. Example: 'application/pdf', 'image/png'. Auto-detected if not provided */
+    contentType?: string;
+}
+/**
+ * Result returned after attempting to send an email
+ */
+interface SendMailResult {
+    /** Whether the email was sent successfully */
+    success: boolean;
+    /** Unique message ID assigned by the email server. Only present if success is true */
+    messageId?: string;
+    /** Error message describing what went wrong. Only present if success is false */
+    error?: string;
+}
+
+/**
+ * QuickMail - Simple and quick email sending package
+ */
+declare class QuickMailClass {
+    private transporter;
+    private config;
+    private initialized;
+    /**
+     * Initialize QuickMail with your SMTP credentials
+     * @param config - SMTP configuration options including email and password
+     * @example
+     * ```ts
+     * QuickMail.init({
+     *   email: 'your-email@gmail.com',
+     *   password: 'your-app-password'
+     * });
+     * ```
+     */
+    init(config: QuickMailConfig): void;
+    /**
+     * Send an email
+     * @param options - Email options
+     * @returns Promise with send result
+     * @example
+     * ```ts
+     * const result = await QuickMail.send({
+     *   to: 'recipient@example.com',
+     *   subject: 'Hello!',
+     *   html: '<h1>Welcome!</h1>'
+     * });
+     * ```
+     */
+    send(options: SendMailOptions): Promise<SendMailResult>;
+    /**
+     * Verify the SMTP connection
+     * @returns Promise<boolean> - true if connection is valid
+     */
+    verify(): Promise<boolean>;
+    /**
+     * Check if QuickMail is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Reset the QuickMail instance
+     */
+    reset(): void;
+}
+declare const QuickMail: QuickMailClass;
+
+export { type Attachment, QuickMail, type QuickMailConfig, type SendMailOptions, type SendMailResult };

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Configuration options for initializing QuickMail
+ */
+interface QuickMailConfig {
+    /** Your email address used for sending emails (SMTP username) */
+    email: string;
+    /** SMTP password for authentication. For Gmail, use an App Password generated from Google Account settings */
+    password: string;
+    /** SMTP server hostname. Default: smtp.gmail.com */
+    smtpHost?: string;
+    /** SMTP server port. Default: 587 (TLS) */
+    smtpPort?: number;
+    /** Enable SSL/TLS secure connection. Default: auto-detects (false for port 587, true for port 465) */
+    smtpSecure?: boolean;
+    /** Display name shown in recipient's inbox. If not provided, only email address is shown */
+    senderName?: string;
+}
+/**
+ * Options for sending an email
+ */
+interface SendMailOptions {
+    /** Recipient email address(es). Can be a single email string or array of emails */
+    to: string | string[];
+    /** Email subject line shown in recipient's inbox */
+    subject: string;
+    /** HTML formatted email content. Recommended for rich formatting */
+    html?: string;
+    /** Plain text email content. Used as fallback if HTML is not supported by recipient's email client */
+    text?: string;
+    /** Sender email address. If not provided, uses the email from init() configuration */
+    from?: string;
+    /** CC (Carbon Copy) recipients - visible to all recipients */
+    cc?: string | string[];
+    /** BCC (Blind Carbon Copy) recipients - hidden from other recipients */
+    bcc?: string | string[];
+    /** Reply-To email address. Responses will be sent to this address instead of the 'from' address */
+    replyTo?: string;
+    /** File attachments to include in the email */
+    attachments?: Attachment[];
+}
+/**
+ * Email attachment configuration
+ */
+interface Attachment {
+    /** Name of the file as it will appear to the recipient */
+    filename: string;
+    /** Local file path or URL to the file. Example: './document.pdf' or 'https://example.com/file.pdf' */
+    path?: string;
+    /** Raw file content as string or Buffer. Use this instead of 'path' for in-memory files */
+    content?: string | Buffer;
+    /** MIME type of the file. Example: 'application/pdf', 'image/png'. Auto-detected if not provided */
+    contentType?: string;
+}
+/**
+ * Result returned after attempting to send an email
+ */
+interface SendMailResult {
+    /** Whether the email was sent successfully */
+    success: boolean;
+    /** Unique message ID assigned by the email server. Only present if success is true */
+    messageId?: string;
+    /** Error message describing what went wrong. Only present if success is false */
+    error?: string;
+}
+
+/**
+ * QuickMail - Simple and quick email sending package
+ */
+declare class QuickMailClass {
+    private transporter;
+    private config;
+    private initialized;
+    /**
+     * Initialize QuickMail with your SMTP credentials
+     * @param config - SMTP configuration options including email and password
+     * @example
+     * ```ts
+     * QuickMail.init({
+     *   email: 'your-email@gmail.com',
+     *   password: 'your-app-password'
+     * });
+     * ```
+     */
+    init(config: QuickMailConfig): void;
+    /**
+     * Send an email
+     * @param options - Email options
+     * @returns Promise with send result
+     * @example
+     * ```ts
+     * const result = await QuickMail.send({
+     *   to: 'recipient@example.com',
+     *   subject: 'Hello!',
+     *   html: '<h1>Welcome!</h1>'
+     * });
+     * ```
+     */
+    send(options: SendMailOptions): Promise<SendMailResult>;
+    /**
+     * Verify the SMTP connection
+     * @returns Promise<boolean> - true if connection is valid
+     */
+    verify(): Promise<boolean>;
+    /**
+     * Check if QuickMail is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Reset the QuickMail instance
+     */
+    reset(): void;
+}
+declare const QuickMail: QuickMailClass;
+
+export { type Attachment, QuickMail, type QuickMailConfig, type SendMailOptions, type SendMailResult };

package/dist/index.js

@@ -0,0 +1,180 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  QuickMail: () => QuickMail
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/functions.ts
+var import_nodemailer = __toESM(require("nodemailer"));
+var QuickMailClass = class {
+  transporter = null;
+  config = null;
+  initialized = false;
+  /**
+   * Initialize QuickMail with your SMTP credentials
+   * @param config - SMTP configuration options including email and password
+   * @example
+   * ```ts
+   * QuickMail.init({
+   *   email: 'your-email@gmail.com',
+   *   password: 'your-app-password'
+   * });
+   * ```
+   */
+  init(config) {
+    const {
+      email,
+      password,
+      smtpHost = "smtp.gmail.com",
+      smtpPort = 587,
+      smtpSecure,
+      senderName
+    } = config;
+    if (!email || !password) {
+      throw new Error("QuickMail: email and password are required");
+    }
+    const isSecure = smtpSecure ?? smtpPort === 465;
+    this.config = {
+      email,
+      password,
+      smtpHost,
+      smtpPort,
+      smtpSecure: isSecure,
+      senderName
+    };
+    this.transporter = import_nodemailer.default.createTransport({
+      host: smtpHost,
+      port: smtpPort,
+      secure: isSecure,
+      auth: {
+        user: email,
+        pass: password
+      }
+    });
+    this.initialized = true;
+  }
+  /**
+   * Send an email
+   * @param options - Email options
+   * @returns Promise with send result
+   * @example
+   * ```ts
+   * const result = await QuickMail.send({
+   *   to: 'recipient@example.com',
+   *   subject: 'Hello!',
+   *   html: '<h1>Welcome!</h1>'
+   * });
+   * ```
+   */
+  async send(options) {
+    if (!this.initialized || !this.transporter || !this.config) {
+      throw new Error(
+        "QuickMail: Not initialized. Call QuickMail.init() first."
+      );
+    }
+    const { to, subject, html, text, from, cc, bcc, replyTo, attachments } = options;
+    if (!to) {
+      throw new Error("QuickMail: 'to' is required");
+    }
+    if (!subject) {
+      throw new Error("QuickMail: 'subject' is required");
+    }
+    if (!html && !text) {
+      throw new Error("QuickMail: Either 'html' or 'text' is required");
+    }
+    const fromAddress = from || this.config.email;
+    const fromField = this.config.senderName ? `"${this.config.senderName}" <${fromAddress}>` : fromAddress;
+    try {
+      const info = await this.transporter.sendMail({
+        from: fromField,
+        to: Array.isArray(to) ? to.join(", ") : to,
+        cc: cc ? Array.isArray(cc) ? cc.join(", ") : cc : void 0,
+        bcc: bcc ? Array.isArray(bcc) ? bcc.join(", ") : bcc : void 0,
+        replyTo,
+        subject,
+        html: html || void 0,
+        text: text || void 0,
+        attachments
+      });
+      return {
+        success: true,
+        messageId: info.messageId
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+      return {
+        success: false,
+        error: errorMessage
+      };
+    }
+  }
+  /**
+   * Verify the SMTP connection
+   * @returns Promise<boolean> - true if connection is valid
+   */
+  async verify() {
+    if (!this.initialized || !this.transporter) {
+      throw new Error(
+        "QuickMail: Not initialized. Call QuickMail.init() first."
+      );
+    }
+    try {
+      await this.transporter.verify();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if QuickMail is initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+  /**
+   * Reset the QuickMail instance
+   */
+  reset() {
+    if (this.transporter) {
+      this.transporter.close();
+    }
+    this.transporter = null;
+    this.config = null;
+    this.initialized = false;
+  }
+};
+var QuickMail = new QuickMailClass();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  QuickMail
+});

package/dist/index.mjs

@@ -0,0 +1,143 @@
+// src/functions.ts
+import nodemailer from "nodemailer";
+var QuickMailClass = class {
+  transporter = null;
+  config = null;
+  initialized = false;
+  /**
+   * Initialize QuickMail with your SMTP credentials
+   * @param config - SMTP configuration options including email and password
+   * @example
+   * ```ts
+   * QuickMail.init({
+   *   email: 'your-email@gmail.com',
+   *   password: 'your-app-password'
+   * });
+   * ```
+   */
+  init(config) {
+    const {
+      email,
+      password,
+      smtpHost = "smtp.gmail.com",
+      smtpPort = 587,
+      smtpSecure,
+      senderName
+    } = config;
+    if (!email || !password) {
+      throw new Error("QuickMail: email and password are required");
+    }
+    const isSecure = smtpSecure ?? smtpPort === 465;
+    this.config = {
+      email,
+      password,
+      smtpHost,
+      smtpPort,
+      smtpSecure: isSecure,
+      senderName
+    };
+    this.transporter = nodemailer.createTransport({
+      host: smtpHost,
+      port: smtpPort,
+      secure: isSecure,
+      auth: {
+        user: email,
+        pass: password
+      }
+    });
+    this.initialized = true;
+  }
+  /**
+   * Send an email
+   * @param options - Email options
+   * @returns Promise with send result
+   * @example
+   * ```ts
+   * const result = await QuickMail.send({
+   *   to: 'recipient@example.com',
+   *   subject: 'Hello!',
+   *   html: '<h1>Welcome!</h1>'
+   * });
+   * ```
+   */
+  async send(options) {
+    if (!this.initialized || !this.transporter || !this.config) {
+      throw new Error(
+        "QuickMail: Not initialized. Call QuickMail.init() first."
+      );
+    }
+    const { to, subject, html, text, from, cc, bcc, replyTo, attachments } = options;
+    if (!to) {
+      throw new Error("QuickMail: 'to' is required");
+    }
+    if (!subject) {
+      throw new Error("QuickMail: 'subject' is required");
+    }
+    if (!html && !text) {
+      throw new Error("QuickMail: Either 'html' or 'text' is required");
+    }
+    const fromAddress = from || this.config.email;
+    const fromField = this.config.senderName ? `"${this.config.senderName}" <${fromAddress}>` : fromAddress;
+    try {
+      const info = await this.transporter.sendMail({
+        from: fromField,
+        to: Array.isArray(to) ? to.join(", ") : to,
+        cc: cc ? Array.isArray(cc) ? cc.join(", ") : cc : void 0,
+        bcc: bcc ? Array.isArray(bcc) ? bcc.join(", ") : bcc : void 0,
+        replyTo,
+        subject,
+        html: html || void 0,
+        text: text || void 0,
+        attachments
+      });
+      return {
+        success: true,
+        messageId: info.messageId
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+      return {
+        success: false,
+        error: errorMessage
+      };
+    }
+  }
+  /**
+   * Verify the SMTP connection
+   * @returns Promise<boolean> - true if connection is valid
+   */
+  async verify() {
+    if (!this.initialized || !this.transporter) {
+      throw new Error(
+        "QuickMail: Not initialized. Call QuickMail.init() first."
+      );
+    }
+    try {
+      await this.transporter.verify();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if QuickMail is initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+  /**
+   * Reset the QuickMail instance
+   */
+  reset() {
+    if (this.transporter) {
+      this.transporter.close();
+    }
+    this.transporter = null;
+    this.config = null;
+    this.initialized = false;
+  }
+};
+var QuickMail = new QuickMailClass();
+export {
+  QuickMail
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "quick-mail",
+  "version": "0.0.1",
+  "description": "quick mail sending package",
+  "keywords": [
+    "mail",
+    "gmail",
+    "quick"
+  ],
+  "homepage": "https://github.com/Chetan-KK/quick-mail#readme",
+  "bugs": {
+    "url": "https://github.com/Chetan-KK/quick-mail/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chetan-KK/quick-mail.git"
+  },
+  "license": "MIT",
+  "author": "Chetan-KK",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "nodemailer": "^7.0.12"
+  }
+}