Mailing

A lightweight Node.js + TypeScript client for sending and scheduling emails via a remote mailing API, using SMTP credentials and optional webhooks.

Designed for backend services, queues, and microservices.

Features

• SMTP-based email sending
• Scheduled email delivery
• Email existence verification
• Job cancellation for scheduled emails
• Webhook support
• Fully typed (TypeScript-first)
• Axios-powered HTTP client
• Works with Node.js, Bun, Docker, PM2

Installation

npm install mailing-service

or

pnpm add mailing-service

or

bun add mailing-service

Quick Start

import { Mailing } from "mailing-service";

const mailer = new Mailing({
  host: "https://api.example.com",
  apiKey: "your-api-key",
  credential: {
    host: "smtp.gmail.com",
    port: 587,
    secure: false,
    auth: {
      user: "[email protected]",
      pass: "smtp-password",
    },
  },
});

Send Email

await mailer.send({
  from: "My App <[email protected]>",
  to: "[email protected]",
  subject: "Welcome",
  text: "Hello from Mailing",
});

Schedule Email

const scheduled = await mailer.schedule(
  new Date(Date.now() + 60 * 60 * 1000) // 1 hour later
);

const result = await scheduled.send({
  from: "My App <[email protected]>",
  to: "[email protected]",
  subject: "Scheduled Mail",
  html: "<b>This email was scheduled</b>",
});

// Save the job ID for cancellation if needed
const jobId = result.data.id;

Check Email Existence

const response = await mailer.isEmailExistence("[email protected]");

console.log(response.data.exists); // true or false
console.log(response.data.email); // "[email protected]"

Cancel Scheduled Email

// Cancel a scheduled email job using its job ID
const response = await mailer.cancelMail("job-id-456");

console.log(response.data.status); // true if successful
console.log(response.data.result); // true if job was removed

Configuration

T_Sender

type T_Sender = {
  host: string;
  apiKey?: string;
  credential: {
    host: string;
    port: number;
    secure: boolean;
    auth: {
      user: string;
      pass: string;
    };
  };
  webhook?: string;
};

Fields

| Field | Description | | ------------ | ---------------------------------------- | | host | Base URL of the mailing API | | apiKey | Optional API authentication key | | credential | SMTP server configuration | | webhook | Optional webhook URL for delivery status |

API Reference

new Mailing(config)

Creates a new mailing client instance.

send(email)

Sends an email immediately.

send(data: Omit<Mail.Options, "attachments">): Promise<any>

schedule(date).send(email)

Schedules an email for future delivery.

schedule(date: Date): {
  send(data: Omit<Mail.Options, "attachments">): Promise<any>
}

isEmailExistence(email)

Checks if an email address exists by verifying SMTP response.

isEmailExistence<T>(email: string): Promise<AxiosResponse<T>>

Response:

{
  status: true,
  email: string,
  exists: boolean,
  date: string
}

cancelMail(jobId)

Cancels a scheduled email job by its job ID.

cancelMail<T>(id: string): Promise<AxiosResponse<T>>

Response:

{
  status: true,
  jobId: string,
  result: boolean,
  date: string
}

Notes

• Attachments are not supported in this client
• Ensure your SMTP credentials are valid
• API must expose /mail/send, /mail/schedule, /mail/existence, and /mail/cancel/:jobId
• Save the jobId from schedule response if you need to cancel the email later
• Email existence check may return false for valid emails due to SMTP server restrictions

Node.js Support

• Node.js ≥ 18
• TypeScript ≥ 5

License

MIT

Author

Sourav

Contributing

Issues and pull requests are welcome.