@kandleconsultinggroup/email-blaster 0.1.0

package/adapters/index.js

@@ -0,0 +1,9 @@
+const sendgrid = require("./sendgrid");
+const ses = require("./ses");
+const nodemailer = require("./nodemailer");
+
+module.exports = {
+  sendgrid,
+  ses,
+  nodemailer,
+};

package/adapters/nodemailer.js

@@ -0,0 +1,45 @@
+const nodemailer = require("nodemailer");
+const config = require("../config");
+
+let transporter;
+
+function getTransporter() {
+  if (transporter) return transporter;
+
+  // Allow fully custom transporter (best for advanced users)
+  if (config.nodemailer?.transporter) {
+    transporter = config.nodemailer.transporter;
+    return transporter;
+  }
+
+  // Default SMTP setup (Heroku-compatible)
+  transporter = nodemailer.createTransport({
+    host: config.nodemailer.host,
+    port: config.nodemailer.port || 587,
+    secure: config.nodemailer.secure || false,
+    auth: {
+      user: config.nodemailer.user,
+      pass: config.nodemailer.pass,
+    },
+  });
+
+  return transporter;
+}
+
+module.exports = async function sendWithNodemailer({
+  to,
+  subject,
+  html,
+  from,
+  cc,
+}) {
+  const mailer = getTransporter();
+
+  await mailer.sendMail({
+    from,
+    to,
+    cc,
+    subject,
+    html,
+  });
+};

package/adapters/sendgrid.js

@@ -0,0 +1,4 @@
+module.exports = async function sendWithSendgrid({ to, subject, html, from }) {
+  // Plug in SendGrid SDK here
+  console.log("[SendGrid]", { to, subject });
+};

package/adapters/ses.js

@@ -0,0 +1,4 @@
+module.exports = async function sendWithSES({ to, subject, html, from }) {
+  // Plug in AWS SES here
+  console.log("[SES]", { to, subject });
+};

package/config.js

@@ -0,0 +1,24 @@
+module.exports = {
+  provider: null,
+
+  rateLimit: {
+    perMinute: 30,
+    perDay: null, // optional, recommended later
+  },
+
+  redis: null,
+
+  unsubscribe: {
+    enabled: true,
+    baseUrl: null,
+  },
+
+  nodemailer: {
+    host: null,
+    port: null,
+    secure: false,
+    user: null,
+    pass: null,
+    transporter: null,
+  },
+};

package/index.js

@@ -0,0 +1,8 @@
+module.exports = {
+  initMailBlaster: require("./initMailBlaster"),
+  routes: {
+    blasts: require("./routes/blasts.routes"),
+    templates: require("./routes/templates.routes"),
+    unsubscribe: require("./routes/unsubscribe.routes"),
+  },
+};

package/initMailBlaster.js

@@ -0,0 +1,34 @@
+const mongoose = require("mongoose");
+const config = require("./config");
+
+function initMailBlaster(options = {}) {
+  Object.assign(config, options);
+
+  if (!config.provider) {
+    throw new Error("Mail provider is required");
+  }
+
+  if (!config.rateLimit || !config.rateLimit.perMinute) {
+    throw new Error("rateLimit.perMinute is required");
+  }
+
+  if (!config.redis) {
+    console.warn(
+      "[mail-blaster] Redis not configured. Falling back to synchronous sending.",
+    );
+  }
+
+  if (config.unsubscribe.enabled && !config.unsubscribe.baseUrl) {
+    throw new Error(
+      "unsubscribe.baseUrl is required when unsubscribe is enabled",
+    );
+  }
+
+  if (options.mongoUri) {
+    mongoose.connect(options.mongoUri);
+  }
+
+  return config;
+}
+
+module.exports = initMailBlaster;

package/models/EmailBlast.js

@@ -0,0 +1,19 @@
+const mongoose = require("mongoose");
+
+module.exports = mongoose.model(
+  "EmailBlast",
+  new mongoose.Schema(
+    {
+      subject: String,
+      bodyHtml: String,
+      sender: Object,
+      cc: [String],
+      recipients: [Object],
+      status: { type: String, default: "draft" },
+      scheduledAt: Date,
+      followUpAt: Date,
+      createdBy: mongoose.Schema.Types.ObjectId,
+    },
+    { timestamps: true },
+  ),
+);

package/models/EmailSendLog.js

@@ -0,0 +1,19 @@
+const mongoose = require("mongoose");
+
+module.exports = mongoose.model(
+  "EmailSendLog",
+  new mongoose.Schema(
+    {
+      blastId: mongoose.Schema.Types.ObjectId,
+      to: String,
+      status: {
+        type: String,
+        enum: ["pending", "sent", "failed", "unsubscribed"],
+        default: "pending",
+      },
+      error: String,
+      sentAt: Date,
+    },
+    { timestamps: true },
+  ),
+);

package/models/EmalTemplate.js

@@ -0,0 +1,15 @@
+const mongoose = require("mongoose");
+
+module.exports = mongoose.model(
+  "EmailTemplate",
+  new mongoose.Schema(
+    {
+      name: String,
+      subject: String,
+      bodyHtml: String,
+      createdBy: mongoose.Schema.Types.ObjectId,
+      isShared: Boolean,
+    },
+    { timestamps: true },
+  ),
+);

package/models/Unsubscribe.js

@@ -0,0 +1,11 @@
+const mongoose = require("mongoose");
+
+module.exports = mongoose.model(
+  "Unsubscribe",
+  new mongoose.Schema(
+    {
+      email: { type: String, unique: true },
+    },
+    { timestamps: true },
+  ),
+);

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@kandleconsultinggroup/email-blaster",
+  "version": "0.1.0",
+  "main": "index.js",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mongoose": "^8.0.0",
+    "express": "^4.19.0",
+    "bullmq": "^5.1.0",
+    "ioredis": "^5.3.0",
+    "nodemailer": "^6.9.8"
+  }
+}

package/queue/dispatch.js

@@ -0,0 +1,11 @@
+const enqueue = require("./enqueue");
+const sendImmediate = require("./sendImmediate");
+const config = require("../config");
+
+module.exports = async function dispatch(job) {
+  if (config.redis) {
+    return enqueue(job);
+  }
+
+  return sendImmediate(job);
+};

package/queue/enqueue.js

@@ -0,0 +1,26 @@
+const { Queue } = require("bullmq");
+const config = require("../config");
+
+let queue;
+
+function getQueue() {
+  if (!config.redis) {
+    throw new Error("Redis not configured");
+  }
+
+  if (!queue) {
+    queue = new Queue("mail-blaster", {
+      connection: config.redis,
+      limiter: {
+        max: config.rateLimit.perMinute,
+        duration: 60 * 1000,
+      },
+    });
+  }
+
+  return queue;
+}
+
+module.exports = async function enqueue(job) {
+  return getQueue().add("send-email", job);
+};

package/queue/sendImmediate.js

@@ -0,0 +1,50 @@
+const adapters = require("../adapters");
+const applyTokens = require("../tokens/applyTokens");
+const config = require("../config");
+const EmailSendLog = require("../models/EmailSendLog");
+
+let lastSend = 0;
+
+module.exports = async function sendImmediate({ blast, recipient }) {
+  const send = adapters[config.provider];
+  if (!send) {
+    throw new Error(`Unsupported mail provider: ${config.provider}`);
+  }
+
+  // Soft rate limit (per-minute)
+  const interval = Math.ceil(60000 / (config.rateLimit?.perMinute || 30));
+
+  const now = Date.now();
+  const wait = Math.max(0, interval - (now - lastSend));
+  if (wait) {
+    await new Promise((r) => setTimeout(r, wait));
+  }
+  lastSend = Date.now();
+
+  const html = applyTokens(blast.bodyHtml, recipient, blast.sender, {
+    includeUnsubscribe: config.unsubscribe.enabled,
+    unsubscribeBaseUrl: config.unsubscribe.baseUrl,
+  });
+
+  try {
+    await send({
+      to: recipient.email,
+      cc: blast.cc,
+      subject: blast.subject,
+      html,
+      from: blast.sender.email,
+    });
+
+    await EmailSendLog.updateOne(
+      { blastId: blast._id, to: recipient.email },
+      { status: "sent", sentAt: new Date() },
+    );
+  } catch (err) {
+    await EmailSendLog.updateOne(
+      { blastId: blast._id, to: recipient.email },
+      { status: "failed", error: err.message },
+    );
+
+    throw err;
+  }
+};

package/queue/worker.js

@@ -0,0 +1,48 @@
+const { Worker } = require("bullmq");
+const config = require("../config");
+const adapters = require("../adapters");
+const applyTokens = require("../tokens/applyTokens");
+const EmailSendLog = require("../models/EmailSendLog");
+
+new Worker(
+  "mail-blaster",
+  async (job) => {
+    const { blast, recipient } = job.data;
+
+    const send = adapters[config.provider];
+    if (!send) {
+      throw new Error(`Unsupported mail provider: ${config.provider}`);
+    }
+
+    const html = applyTokens(blast.bodyHtml, recipient, blast.sender, {
+      includeUnsubscribe: config.unsubscribe.enabled,
+      unsubscribeBaseUrl: config.unsubscribe.baseUrl,
+    });
+
+    try {
+      await send({
+        to: recipient.email,
+        cc: blast.cc,
+        subject: blast.subject,
+        html,
+        from: blast.sender.email,
+      });
+
+      await EmailSendLog.updateOne(
+        { blastId: blast._id, to: recipient.email },
+        { status: "sent", sentAt: new Date() },
+      );
+    } catch (err) {
+      await EmailSendLog.updateOne(
+        { blastId: blast._id, to: recipient.email },
+        { status: "failed", error: err.message },
+      );
+
+      throw err;
+    }
+  },
+  {
+    connection: config.redis,
+    concurrency: 1, // safest default; raise later if needed
+  },
+);

package/routes/blasts.routes.js

@@ -0,0 +1,42 @@
+const router = require("express").Router();
+const EmailBlast = require("../models/EmailBlast");
+const EmailSendLog = require("../models/EmailSendLog");
+const Unsubscribe = require("../models/Unsubscribe");
+const dispatch = require("../queue/dispatch");
+
+router.post("/:id/send", async (req, res) => {
+  const blast = await EmailBlast.findById(req.params.id);
+
+  let queued = 0;
+  let skipped = 0;
+
+  for (const recipient of blast.recipients) {
+    const isUnsubscribed = await Unsubscribe.findOne({
+      email: recipient.email,
+    });
+
+    if (isUnsubscribed) {
+      skipped++;
+
+      await EmailSendLog.create({
+        blastId: blast._id,
+        to: recipient.email,
+        status: "unsubscribed",
+      });
+
+      continue;
+    }
+
+    await EmailSendLog.create({
+      blastId: blast._id,
+      to: recipient.email,
+    });
+
+    await dispatch({ blast, recipient });
+    queued++;
+  }
+
+  res.json({ queued, skipped });
+});
+
+module.exports = router;

package/routes/templates.routes.js

@@ -0,0 +1,12 @@
+const router = require("express").Router();
+const EmailTemplate = require("../models/EmailTemplate");
+
+router.post("/", async (req, res) => {
+  res.json(await EmailTemplate.create(req.body));
+});
+
+router.get("/", async (req, res) => {
+  res.json(await EmailTemplate.find());
+});
+
+module.exports = router;

package/routes/unsubscribe.routes.js

@@ -0,0 +1,13 @@
+const router = require("express").Router();
+const Unsubscribe = require("../models/Unsubscribe");
+
+router.get("/", async (req, res) => {
+  await Unsubscribe.updateOne(
+    { email: req.query.email },
+    { email: req.query.email },
+    { upsert: true },
+  );
+  res.send("Unsubscribed");
+});
+
+module.exports = router;

package/tokens/applyTokens.js

@@ -0,0 +1,24 @@
+const unsubscribeFooter = require("./unsubscribeFooter");
+
+module.exports = function applyTokens(
+  html,
+  recipient = {},
+  sender = {},
+  options = {},
+) {
+  let output = html
+    .replace(/{{firstName}}/g, recipient.firstName || "")
+    .replace(/{{company}}/g, recipient.company || "")
+    .replace(/{{city}}/g, recipient.city || "")
+    .replace(/{{senderName}}/g, sender.name || "");
+
+  if (options.includeUnsubscribe !== false) {
+    output += unsubscribeFooter({
+      email: recipient.email,
+      unsubscribeBaseUrl: options.unsubscribeBaseUrl,
+      senderName: sender.name,
+    });
+  }
+
+  return output;
+};

package/tokens/unsubscribeFooter.js

@@ -0,0 +1,20 @@
+module.exports = function unsubscribeFooter({
+  email,
+  unsubscribeBaseUrl,
+  senderName,
+}) {
+  if (!unsubscribeBaseUrl) {
+    throw new Error("unsubscribeBaseUrl is required");
+  }
+
+  const url = `${unsubscribeBaseUrl}?email=${encodeURIComponent(email)}`;
+
+  return `
+    <hr style="margin-top:24px;" />
+    <p style="font-size:12px;color:#777;">
+      You’re receiving this email because you were contacted by ${senderName || "us"}.
+      <br />
+      <a href="${url}" style="color:#777;">Unsubscribe</a>
+    </p>
+  `;
+};