mailgun-inbound-email 1.0.0 → 2.1.0

package/index.js

@@ -1,36 +1,63 @@
-const express = require("express");
 const crypto = require("crypto");
-const multer = require("multer");
-
-const upload = multer({ storage: multer.memoryStorage() });
 
 /**
  * Verify Mailgun webhook signature
+ * @param {string} token - Mailgun token
+ * @param {string} timestamp - Request timestamp
+ * @param {string} signature - Mailgun signature
+ * @param {string} signingKey - Mailgun webhook signing key
+ * @returns {boolean} True if signature is valid
  */
 function verifyMailgunSignature(token, timestamp, signature, signingKey) {
   if (!signingKey) {
-    console.error("MAILGUN_WEBHOOK_SIGNING_KEY missing");
+    console.error("[MailgunInbound] MAILGUN_WEBHOOK_SIGNING_KEY missing");
+    return false;
+  }
+
+  if (!token || !timestamp || !signature) {
+    console.error("[MailgunInbound] Missing required signature parameters");
     return false;
   }
 
   const currentTime = Math.floor(Date.now() / 1000);
+  const requestTime = Number(timestamp);
 
-  // Prevent replay attack (15 min)
-  if (Math.abs(currentTime - Number(timestamp)) > 900) {
-    console.error("Expired timestamp");
+  // Validate timestamp is a number
+  if (isNaN(requestTime)) {
+    console.error("[MailgunInbound] Invalid timestamp format");
     return false;
   }
 
-  const hmac = crypto
-    .createHmac("sha256", signingKey)
-    .update(timestamp + token)
-    .digest("hex");
+  // Prevent replay attack (15 min window)
+  if (Math.abs(currentTime - requestTime) > 900) {
+    console.error("[MailgunInbound] Expired timestamp", { 
+      currentTime, 
+      requestTime, 
+      difference: Math.abs(currentTime - requestTime) 
+    });
+    return false;
+  }
 
-  return hmac === signature;
+  try {
+    const hmac = crypto
+      .createHmac("sha256", signingKey)
+      .update(timestamp + token)
+      .digest("hex");
+
+    return crypto.timingSafeEqual(
+      Buffer.from(hmac),
+      Buffer.from(signature)
+    );
+  } catch (error) {
+    console.error("[MailgunInbound] Signature verification error:", error.message);
+    return false;
+  }
 }
 
 /**
  * Parse headers safely
+ * @param {string|Array} headers - Email headers as string or array
+ * @returns {Array} Parsed headers array
  */
 function parseHeaders(headers) {
   if (Array.isArray(headers)) return headers;
@@ -44,6 +71,8 @@ function parseHeaders(headers) {
 
 /**
  * Extract email from "Name <email@domain.com>" or plain email
+ * @param {string} value - Email string
+ * @returns {string} Extracted email address
  */
 function extractEmail(value = "") {
   if (!value || typeof value !== 'string') return "";
@@ -53,6 +82,8 @@ function extractEmail(value = "") {
 
 /**
  * Extract multiple emails from comma-separated string
+ * @param {string} value - Comma-separated email string
+ * @returns {Array<string>} Array of email addresses
  */
 function extractEmails(value = "") {
   if (!value || typeof value !== 'string') return [];
@@ -61,6 +92,8 @@ function extractEmails(value = "") {
 
 /**
  * Remove angle brackets from message ID
+ * @param {string} value - Message ID string
+ * @returns {string|null} Cleaned message ID
  */
 function cleanMessageId(value) {
   if (!value || typeof value !== 'string') return null;
@@ -68,9 +101,60 @@ function cleanMessageId(value) {
 }
 
 /**
- * Process email data from Mailgun webhook
+ * Verify Mailgun webhook signature automatically from request
+ * 
+ * This function automatically extracts token, timestamp, and signature
+ * from the request body and verifies the signature. You only need to
+ * provide the signing key.
+ * 
+ * @param {Object} req - Express request object with body
+ * @param {Object} req.body - Request body containing token, timestamp, signature
+ * @param {string} signingKey - Mailgun webhook signing key (or use MAILGUN_WEBHOOK_SIGNING_KEY env var)
+ * @returns {boolean} True if signature is valid
+ * 
+ * @example
+ * const { verifyRequestSignature } = require('mailgun-inbound-email');
+ * const signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY;
+ * if (!verifyRequestSignature(req, signingKey)) {
+ *   return res.status(401).json({ error: 'Invalid signature' });
+ * }
+ */
+function verifyRequestSignature(req, signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY) {
+  if (!req || !req.body) {
+    console.error("[MailgunInbound] Invalid request: missing body");
+    return false;
+  }
+
+  const { token, timestamp, signature } = req.body;
+  return verifyMailgunSignature(token, timestamp, signature, signingKey);
+}
+
+/**
+ * Process email data from Mailgun webhook request
+ * 
+ * This function processes the raw Express request body and files
+ * to extract and structure email data for manual processing.
+ * 
+ * @param {Object} req - Express request object with body and files
+ * @param {Object} req.body - Request body containing email fields
+ * @param {Array} req.files - Array of uploaded files (attachments)
+ * @returns {Object} Processed email data with token, timestamp, signature
+ * @returns {Object} return.emailData - Structured email data
+ * @returns {string} return.token - Mailgun token
+ * @returns {string} return.timestamp - Request timestamp
+ * @returns {string} return.signature - Mailgun signature
+ * @throws {Error} If request body is invalid
+ * 
+ * @example
+ * const { processEmailData } = require('mailgun-inbound-email');
+ * const { emailData } = processEmailData(req);
+ * console.log(emailData.from, emailData.subject);
  */
 function processEmailData(req) {
+  if (!req || !req.body) {
+    throw new Error("Invalid request: missing body");
+  }
+
   const {
     token,
     timestamp,
@@ -88,18 +172,21 @@ function processEmailData(req) {
     "attachment-count": attachmentCount,
   } = req.body;
 
-  // Process attachments metadata (without buffer for clean JSON)
-  const processedAttachments = (req.files || []).map((file) => ({
-    filename: file.originalname || `attachment-${Date.now()}`,
+  // Process attachments metadata with buffers for manual processing
+  const processedAttachments = (req.files || []).map((file, index) => ({
+    filename: file.originalname || `attachment-${Date.now()}-${index}`,
     originalname: file.originalname || null,
-    mimetype: file.mimetype || null,
+    mimetype: file.mimetype || "application/octet-stream",
     size: file.size || 0,
-    extension: file.originalname ? file.originalname.split('.').pop() : null,
+    extension: file.originalname 
+      ? file.originalname.split('.').pop().toLowerCase() 
+      : null,
     encoding: file.encoding || null,
     fieldname: file.fieldname || null,
+    buffer: file.buffer || null, // Include buffer for manual processing
   }));
 
-  // Convert headers array to object for easier storage
+  // Convert headers array to object for easier access
   const headersObj = {};
   const parsedHeaders = parseHeaders(messageHeaders);
   if (parsedHeaders && parsedHeaders.length > 0) {
@@ -112,9 +199,9 @@ function processEmailData(req) {
   }
 
   // Extract CC from body or headers
-  const ccValue = cc || headersObj['Cc'] || headersObj['CC'] || ""
+  const ccValue = cc || headersObj['Cc'] || headersObj['CC'] || "";
   // Extract TO from body or headers (can be multiple recipients)
-  const toValue = recipient || headersObj['To'] || headersObj['TO'] || ""
+  const toValue = recipient || headersObj['To'] || headersObj['TO'] || "";
 
   const emailData = {
     messageId: cleanMessageId(headersObj['Message-ID'] || headersObj['Message-Id'] || null),
@@ -140,143 +227,256 @@ function processEmailData(req) {
 }
 
 /**
- * Create Express router for Mailgun inbound email webhook
+ * Production-ready Mailgun event webhook handler
+ * 
+ * Handles Mailgun event webhooks (delivered, opened, clicked, bounced, etc.)
+ * with proper error handling, validation, and logging. Returns event data
+ * for manual processing and saving to database.
  * 
- * @param {Object} options - Configuration options
- * @param {string} options.signingKey - Mailgun webhook signing key (or use MAILGUN_WEBHOOK_SIGNING_KEY env var)
- * @param {Function} options.onEmailReceived - Callback function called when email is received (emailData) => {}
- * @param {string} options.path - Route path (default: '/inbound')
- * @param {boolean} options.requireSignature - Whether to require signature verification (default: true)
- * @returns {express.Router} Express router
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {string} signingKey - Mailgun webhook signing key (optional, defaults to MAILGUN_WEBHOOK_SIGNING_KEY env var)
+ * @returns {Promise<Object|null>} Returns event data if successfully processed, null otherwise
+ * 
+ * @example
+ * const { mailgunWebhook } = require('mailgun-inbound-email');
+ * 
+ * app.post('/webhook/mailgun-events', express.json(), async (req, res) => {
+ *   const eventData = await mailgunWebhook(req, res);
+ *   // eventData contains the processed event data for manual saving
+ *   if (eventData && eventData.received && eventData.event) {
+ *     await db.events.create(eventData);
+ *   }
+ * });
  */
-function createMailgunInboundRouter(options = {}) {
-  const router = express.Router();
-  const {
-    signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY,
-    onEmailReceived,
-    path = '/inbound',
-    requireSignature = true,
-  } = options;
-
-  router.post(path, express.urlencoded({ extended: true }), upload.any(), (req, res) => {
-    try {
-      const { emailData, token, timestamp, signature } = processEmailData(req);
-
-      // 🔐 Verify Mailgun authenticity
-      if (requireSignature && !verifyMailgunSignature(token, timestamp, signature, signingKey)) {
-        return res.status(401).json({ error: "Invalid Mailgun signature" });
-      }
-
-      // Validate required fields
-      if (!emailData.from || !emailData.to || emailData.to.length === 0) {
-        console.error("Missing required email fields:", { from: emailData.from, to: emailData.to });
-        // Still return 200 to prevent Mailgun retries
-        return res.status(200).json({ received: true, error: "Missing required fields" });
-      }
-
-      // Call user-provided callback if provided
-      if (onEmailReceived && typeof onEmailReceived === 'function') {
-        try {
-          onEmailReceived(emailData);
-        } catch (callbackError) {
-          console.error("Error in onEmailReceived callback:", callbackError);
-        }
-      } else {
-        // Default: log clean JSON data ready to save
-        console.log(JSON.stringify(emailData, null, 2));
-      }
-
-      res.status(200).json({ received: true });
+async function mailgunWebhook(req, res, signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY) {
+  const startTime = Date.now();
+  const correlationId = req.headers['x-request-id'] || 
+                       req.headers['x-correlation-id'] || 
+                       `mg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 
-    } catch (error) {
-      console.error("Inbound email processing error:", {
-        error: error.message,
-        stack: error.stack,
-        timestamp: new Date().toISOString(),
+  try {
+    // Validate request body
+    if (!req || !req.body) {
+      console.error(`[MailgunWebhook:${correlationId}] Invalid request: missing body`, {
+        ip: req.ip || req.connection?.remoteAddress,
+        userAgent: req.headers['user-agent'],
+      });
+      res.status(400).json({ 
+        received: false, 
+        error: 'Invalid request',
+        correlationId 
       });
+      return null;
+    }
 
-      // Mailgun MUST receive 200 or it will retry
-      res.status(200).json({ received: true });
+    // 🔐 Verify Mailgun request signature
+    const isValid = verifyRequestSignature(req, signingKey);
+    if (!isValid) {
+      console.warn(`[MailgunWebhook:${correlationId}] Invalid Mailgun webhook signature`, {
+        ip: req.ip || req.connection?.remoteAddress,
+        userAgent: req.headers['user-agent'],
+        hasBody: !!req.body,
+        hasToken: !!req.body.token,
+        hasTimestamp: !!req.body.timestamp,
+        hasSignature: !!req.body.signature,
+      });
+      res.status(401).json({ 
+        received: false, 
+        error: 'Invalid signature',
+        correlationId 
+      });
+      return null;
     }
-  });
 
-  return router;
-}
+    // Extract event data from request body
+    const eventData = req.body['event-data'] || {};
+    const event = eventData.event;
+    const eventId = eventData.id || eventData['event-id'] || null;
+    const recipient = eventData.recipient;
+    const messageId = eventData.message?.headers?.['message-id'] || 
+                     eventData['message-id'] || 
+                     eventData.messageId || 
+                     null;
+    const url = eventData.url;
+    const timestamp = eventData.timestamp || Date.now() / 1000;
+    const domain = eventData.domain?.name || eventData.domain;
+    const reason = eventData['delivery-status']?.description || 
+                  eventData.reason || 
+                  eventData['failure-reason'] || 
+                  null;
+
+    // Validate required fields
+    if (!event) {
+      console.warn(`[MailgunWebhook:${correlationId}] Missing event type`, { 
+        body: req.body 
+      });
+      const errorResponse = { 
+        received: true, 
+        error: 'Missing event type',
+        correlationId 
+      };
+      res.status(200).json(errorResponse);
+      return null;
+    }
 
-/**
- * Create Express middleware for Mailgun inbound email webhook
- * 
- * @param {Object} options - Configuration options
- * @param {string} options.signingKey - Mailgun webhook signing key (or use MAILGUN_WEBHOOK_SIGNING_KEY env var)
- * @param {Function} options.onEmailReceived - Callback function called when email is received (emailData) => {}
- * @param {boolean} options.requireSignature - Whether to require signature verification (default: true)
- * @returns {Array} Express middleware array
- */
-function createMailgunInboundMiddleware(options = {}) {
-  const {
-    signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY,
-    onEmailReceived,
-    requireSignature = true,
-  } = options;
-
-  return [
-    express.urlencoded({ extended: true }),
-    upload.any(),
-    (req, res, next) => {
-      try {
-        const { emailData, token, timestamp, signature } = processEmailData(req);
-
-        // 🔐 Verify Mailgun authenticity
-        if (requireSignature && !verifyMailgunSignature(token, timestamp, signature, signingKey)) {
-          return res.status(401).json({ error: "Invalid Mailgun signature" });
+    // Prepare response data with correlation ID for tracking
+    let responseData = {
+      received: true,
+      event,
+      eventId,
+      recipient,
+      messageId,
+      timestamp: typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp,
+      domain,
+      correlationId,
+      processedAt: new Date().toISOString(),
+    };
+
+    // Handle different event types and add event-specific data
+    switch (event) {
+      case "delivered":
+        console.log(`[MailgunWebhook:${correlationId}] ✅ Email delivered to:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "delivered";
+        responseData.deliveredAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        if (eventData['delivery-status']) {
+          responseData.deliveryStatus = {
+            code: eventData['delivery-status'].code,
+            message: eventData['delivery-status'].message,
+            description: eventData['delivery-status'].description,
+            tls: eventData['delivery-status'].tls,
+            certificateVerified: eventData['delivery-status']['certificate-verified'],
+          };
         }
-
-        // Validate required fields
-        if (!emailData.from || !emailData.to || emailData.to.length === 0) {
-          console.error("Missing required email fields:", { from: emailData.from, to: emailData.to });
-          return res.status(200).json({ received: true, error: "Missing required fields" });
+        break;
+
+      case "opened":
+        console.log(`[MailgunWebhook:${correlationId}] 👀 Email opened by:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "opened";
+        responseData.openedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        responseData.clientInfo = eventData['client-info'] || null;
+        responseData.geolocation = eventData.geolocation || null;
+        responseData.userAgent = eventData['client-info']?.clientName || null;
+        break;
+
+      case "clicked":
+        console.log(`[MailgunWebhook:${correlationId}] 🔗 Link clicked:`, url);
+        console.log(`[MailgunWebhook:${correlationId}]    Recipient:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "clicked";
+        responseData.url = url;
+        responseData.clickedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        responseData.clientInfo = eventData['client-info'] || null;
+        responseData.geolocation = eventData.geolocation || null;
+        break;
+
+      case "bounced":
+        console.log(`[MailgunWebhook:${correlationId}] ❌ Email bounced:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "bounced";
+        responseData.reason = reason;
+        responseData.bouncedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        if (eventData['delivery-status']) {
+          responseData.deliveryStatus = {
+            code: eventData['delivery-status'].code,
+            message: eventData['delivery-status'].message,
+            description: eventData['delivery-status'].description,
+            attemptNo: eventData['delivery-status']['attempt-no'],
+            sessionSeconds: eventData['delivery-status']['session-seconds'],
+          };
         }
-
-        // Attach emailData to request object
-        req.emailData = emailData;
-
-        // Call user-provided callback if provided
-        if (onEmailReceived && typeof onEmailReceived === 'function') {
-          try {
-            onEmailReceived(emailData);
-          } catch (callbackError) {
-            console.error("Error in onEmailReceived callback:", callbackError);
-          }
-        } else {
-          // Default: log clean JSON data ready to save
-          console.log(JSON.stringify(emailData, null, 2));
+        responseData.severity = eventData.severity || 'permanent';
+        break;
+
+      case "complained":
+        console.log(`[MailgunWebhook:${correlationId}] 🚨 Spam complaint:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "complained";
+        responseData.complainedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        break;
+
+      case "failed":
+        console.log(`[MailgunWebhook:${correlationId}] ⚠️ Email failed:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "failed";
+        responseData.reason = reason;
+        responseData.failedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        if (eventData['delivery-status']) {
+          responseData.deliveryStatus = {
+            code: eventData['delivery-status'].code,
+            message: eventData['delivery-status'].message,
+            description: eventData['delivery-status'].description,
+            attemptNo: eventData['delivery-status']['attempt-no'],
+            sessionSeconds: eventData['delivery-status']['session-seconds'],
+          };
         }
+        break;
+
+      case "unsubscribed":
+        console.log(`[MailgunWebhook:${correlationId}] 📤 User unsubscribed:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "unsubscribed";
+        responseData.unsubscribedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        break;
+
+      case "stored":
+        console.log(`[MailgunWebhook:${correlationId}] 💾 Email stored:`, recipient);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "stored";
+        responseData.storedAt = typeof timestamp === 'number' ? new Date(timestamp * 1000).toISOString() : timestamp;
+        break;
+
+      default:
+        console.log(`[MailgunWebhook:${correlationId}] ℹ️ Other event:`, event);
+        console.log(`[MailgunWebhook:${correlationId}]    Message ID:`, messageId);
+        responseData.status = "unknown";
+        responseData.fullEventData = eventData;
+    }
 
-        res.status(200).json({ received: true });
+    // Log successful processing
+    const duration = Date.now() - startTime;
+    console.log(`[MailgunWebhook:${correlationId}] ✅ Webhook processed successfully`, {
+      event,
+      eventId,
+      duration: `${duration}ms`,
+    });
 
-      } catch (error) {
-        console.error("Inbound email processing error:", {
-          error: error.message,
-          stack: error.stack,
-          timestamp: new Date().toISOString(),
-        });
+    // ✅ MUST return 200 OK with event data for manual saving
+    res.status(200).json(responseData);
+    
+    // Return event data so caller can save it manually
+    return responseData;
+
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    console.error(`[MailgunWebhook:${correlationId}] ❌ Webhook Error:`, {
+      error: error.message,
+      stack: error.stack,
+      duration: `${duration}ms`,
+    });
 
-        // Mailgun MUST receive 200 or it will retry
-        res.status(200).json({ received: true });
-      }
-    }
-  ];
+    // ⚠️ Still return 200 so Mailgun doesn't retry forever
+    const errorResponse = { 
+      received: true, 
+      error: 'Processing failed but webhook acknowledged',
+      correlationId,
+      timestamp: new Date().toISOString(),
+    };
+    res.status(200).json(errorResponse);
+    return null;
+  }
 }
 
-// Export utilities and main functions
+// Export utility functions for manual processing
 module.exports = {
-  createMailgunInboundRouter,
-  createMailgunInboundMiddleware,
   processEmailData,
-  verifyMailgunSignature,
+  verifyRequestSignature, // Automatic signature verification (recommended)
+  verifyMailgunSignature, // Manual signature verification (advanced)
+  mailgunWebhook, // Production-ready event webhook handler
   extractEmail,
   extractEmails,
   cleanMessageId,
   parseHeaders,
 };
-

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "mailgun-inbound-email",
-  "version": "1.0.0",
-  "description": "A reusable npm package for handling Mailgun inbound email webhooks with Express.js",
+  "version": "2.1.0",
+  "description": "Production-ready utility functions for manual processing of Mailgun inbound email webhooks. Full manual control - you handle everything.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "echo \"Linting not configured\"",
+    "prepublishOnly": "echo \"Ready to publish\""
   },
   "keywords": [
     "mailgun",
@@ -12,19 +14,17 @@
     "email",
     "webhook",
     "express",
-    "middleware"
+    "middleware",
+    "email-processing",
+    "mailgun-webhook",
+    "inbound-email",
+    "email-handler"
   ],
   "author": "",
   "license": "MIT",
-  "dependencies": {
-    "express": "^4.16.1",
-    "multer": "^2.0.2"
-  },
-  "peerDependencies": {
-    "express": "^4.0.0"
-  },
+  "dependencies": {},
   "engines": {
-    "node": ">=14"
+    "node": ">=14.0.0"
   },
   "devDependencies": {},
   "repository": {
@@ -35,5 +35,10 @@
   "bugs": {
     "url": "https://github.com/RitikKumarSahoo/mailgun-inbound/issues"
   },
-  "homepage": "https://github.com/RitikKumarSahoo/mailgun-inbound#readme"
+  "homepage": "https://github.com/RitikKumarSahoo/mailgun-inbound#readme",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ]
 }