npm - mailgun-inbound-email - Versions diffs - 1.0.0 - Mend

mailgun-inbound-email 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,161 @@
+# mailgun-inbound-email
+A reusable npm package for handling Mailgun inbound email webhooks with Express.js. This package provides a clean, tested solution for receiving and processing inbound emails from Mailgun without rewriting the same code in every project.
+## Features
+- ✅ Mailgun webhook signature verification
+- ✅ Replay attack prevention (15-minute window)
+- ✅ Automatic email parsing (from, to, cc, subject, body, attachments)
+- ✅ Header extraction and normalization
+- ✅ Attachment metadata processing
+- ✅ Express.js router and middleware support
+- ✅ Customizable callback functions
+- ✅ Error handling that prevents Mailgun retries
+## Installation
+```bash
+npm install mailgun-inbound-email
+```
+## Quick Start
+### Option 1: Using Router (Recommended)
+```javascript
+const express = require('express');
+const { createMailgunInboundRouter } = require('mailgun-inbound-email');
+const app = express();
+// Create router with callback
+const mailgunRouter = createMailgunInboundRouter({
+  signingKey: process.env.MAILGUN_WEBHOOK_SIGNING_KEY, // or use env var
+  onEmailReceived: (emailData) => {
+    // Handle the email data
+    console.log('Received email:', emailData);
+    // Save to database, send notifications, etc.
+  },
+  path: '/inbound', // optional, defaults to '/inbound'
+  requireSignature: true, // optional, defaults to true
+});
+app.use('/email', mailgunRouter);
+```
+### Option 2: Using Middleware
+```javascript
+const express = require('express');
+const { createMailgunInboundMiddleware } = require('mailgun-inbound-email');
+const app = express();
+const mailgunMiddleware = createMailgunInboundMiddleware({
+  signingKey: process.env.MAILGUN_WEBHOOK_SIGNING_KEY,
+  onEmailReceived: (emailData) => {
+    // Handle the email data
+    console.log('Received email:', emailData);
+  },
+});
+app.post('/email/inbound', ...mailgunMiddleware);
+```
+### Option 3: Manual Processing
+```javascript
+const express = require('express');
+const { processEmailData, verifyMailgunSignature } = require('mailgun-inbound-email');
+const multer = require('multer');
+const upload = multer({ storage: multer.memoryStorage() });
+const app = express();
+app.post('/email/inbound', express.urlencoded({ extended: true }), upload.any(), (req, res) => {
+  const { emailData, token, timestamp, signature } = processEmailData(req);
+  if (!verifyMailgunSignature(token, timestamp, signature, process.env.MAILGUN_WEBHOOK_SIGNING_KEY)) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+  // Your custom logic here
+  console.log(emailData);
+  res.status(200).json({ received: true });
+});
+```
+## Email Data Structure
+The `emailData` object contains:
+```javascript
+{
+  messageId: "string",           // Cleaned message ID
+  from: "sender@example.com",     // Sender email address
+  to: ["recipient@example.com"],  // Array of recipient emails
+  cc: ["cc@example.com"],         // Array of CC emails
+  subject: "Email Subject",       // Email subject
+  text: "Plain text body",        // Plain text body
+  html: "<html>...</html>",       // HTML body
+  headers: {                      // Parsed headers object
+    "Message-ID": "...",
+    "From": "...",
+    // ... other headers
+  },
+  attachments: [                 // Attachment metadata
+    {
+      filename: "document.pdf",
+      originalname: "document.pdf",
+      mimetype: "application/pdf",
+      size: 12345,
+      extension: "pdf",
+      encoding: "base64",
+      fieldname: "attachment-1"
+    }
+  ],
+  attachmentCount: 1,
+  receivedAt: "2024-01-01T00:00:00.000Z",
+  timestamp: "2024-01-01T00:00:00.000Z"
+}
+```
+## Configuration Options
+### `createMailgunInboundRouter(options)`
+- `signingKey` (string, optional): Mailgun webhook signing key. Defaults to `process.env.MAILGUN_WEBHOOK_SIGNING_KEY`
+- `onEmailReceived` (function, optional): Callback function called when email is received. Receives `emailData` as parameter
+- `path` (string, optional): Route path. Defaults to `'/inbound'`
+- `requireSignature` (boolean, optional): Whether to require signature verification. Defaults to `true`
+### `createMailgunInboundMiddleware(options)`
+- `signingKey` (string, optional): Mailgun webhook signing key. Defaults to `process.env.MAILGUN_WEBHOOK_SIGNING_KEY`
+- `onEmailReceived` (function, optional): Callback function called when email is received. Receives `emailData` as parameter
+- `requireSignature` (boolean, optional): Whether to require signature verification. Defaults to `true`
+## Environment Variables
+- `MAILGUN_WEBHOOK_SIGNING_KEY`: Your Mailgun webhook signing key (if not provided in options)
+## Utilities
+The package also exports utility functions:
+- `processEmailData(req)`: Process raw request and return email data
+- `verifyMailgunSignature(token, timestamp, signature, signingKey)`: Verify webhook signature
+- `extractEmail(value)`: Extract email from "Name <email@domain.com>" format
+- `extractEmails(value)`: Extract multiple emails from comma-separated string
+- `cleanMessageId(value)`: Remove angle brackets from message ID
+- `parseHeaders(headers)`: Safely parse email headers
+## Error Handling
+The package automatically handles errors and always returns `200` status to Mailgun to prevent retries. Errors are logged to the console.
+## License
+MIT

package/SETUP.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Setup Instructions
+## For Local Development
+To use this package in your project before publishing to npm:
+### Option 1: npm link (Recommended for development)
+1. In the `mailgun-inbound-email` directory:
+```bash
+cd /home/ritik-ls/Desktop/mailgun-inbound-email
+npm link
+```
+2. In your project directory:
+```bash
+cd /home/ritik-ls/Desktop/node_skeleton
+npm link mailgun-inbound-email
+```
+### Option 2: Install from local path
+In your project's `package.json`, add:
+```json
+{
+  "dependencies": {
+    "mailgun-inbound-email": "file:../mailgun-inbound-email"
+  }
+}
+```
+Then run:
+```bash
+npm install
+```
+### Option 3: Publish to npm (for production use)
+1. Update `package.json` with your details (name, author, etc.)
+2. Login to npm:
+```bash
+npm login
+```
+3. Publish:
+```bash
+npm publish
+```
+4. Then install in your project:
+```bash
+npm install mailgun-inbound-email
+```
+## After Setup
+Make sure to install dependencies in the package directory:
+```bash
+cd /home/ritik-ls/Desktop/mailgun-inbound-email
+npm install
+```

package/index.js ADDED Viewed

@@ -0,0 +1,282 @@
+const express = require("express");
+const crypto = require("crypto");
+const multer = require("multer");
+const upload = multer({ storage: multer.memoryStorage() });
+/**
+ * Verify Mailgun webhook signature
+ */
+function verifyMailgunSignature(token, timestamp, signature, signingKey) {
+  if (!signingKey) {
+    console.error("MAILGUN_WEBHOOK_SIGNING_KEY missing");
+    return false;
+  }
+  const currentTime = Math.floor(Date.now() / 1000);
+  // Prevent replay attack (15 min)
+  if (Math.abs(currentTime - Number(timestamp)) > 900) {
+    console.error("Expired timestamp");
+    return false;
+  }
+  const hmac = crypto
+    .createHmac("sha256", signingKey)
+    .update(timestamp + token)
+    .digest("hex");
+  return hmac === signature;
+}
+/**
+ * Parse headers safely
+ */
+function parseHeaders(headers) {
+  if (Array.isArray(headers)) return headers;
+  try {
+    return JSON.parse(headers || "[]");
+  } catch {
+    return [];
+  }
+}
+/**
+ * Extract email from "Name <email@domain.com>" or plain email
+ */
+function extractEmail(value = "") {
+  if (!value || typeof value !== 'string') return "";
+  const match = value.match(/<(.+?)>/);
+  return match ? match[1].trim() : value.trim();
+}
+/**
+ * Extract multiple emails from comma-separated string
+ */
+function extractEmails(value = "") {
+  if (!value || typeof value !== 'string') return [];
+  return value.split(',').map(email => extractEmail(email.trim())).filter(Boolean);
+}
+/**
+ * Remove angle brackets from message ID
+ */
+function cleanMessageId(value) {
+  if (!value || typeof value !== 'string') return null;
+  return value.replace(/^<|>$/g, '').trim() || null;
+}
+/**
+ * Process email data from Mailgun webhook
+ */
+function processEmailData(req) {
+  const {
+    token,
+    timestamp,
+    signature,
+    sender,
+    from,
+    subject,
+    recipient,
+    cc,
+    "body-plain": bodyPlain,
+    "body-html": bodyHtml,
+    "stripped-text": strippedText,
+    "stripped-html": strippedHtml,
+    "message-headers": messageHeaders,
+    "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()}`,
+    originalname: file.originalname || null,
+    mimetype: file.mimetype || null,
+    size: file.size || 0,
+    extension: file.originalname ? file.originalname.split('.').pop() : null,
+    encoding: file.encoding || null,
+    fieldname: file.fieldname || null,
+  }));
+  // Convert headers array to object for easier storage
+  const headersObj = {};
+  const parsedHeaders = parseHeaders(messageHeaders);
+  if (parsedHeaders && parsedHeaders.length > 0) {
+    parsedHeaders.forEach(header => {
+      if (Array.isArray(header) && header.length >= 2) {
+        const [key, value] = header;
+        headersObj[key] = value;
+      }
+    });
+  }
+  // Extract CC from body or headers
+  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 emailData = {
+    messageId: cleanMessageId(headersObj['Message-ID'] || headersObj['Message-Id'] || null),
+    from: extractEmail(sender || from),
+    to: extractEmails(toValue),
+    cc: extractEmails(ccValue),
+    subject: subject || "",
+    text: bodyPlain || strippedText || "",
+    html: bodyHtml || strippedHtml || "",
+    headers: headersObj,
+    attachments: processedAttachments,
+    attachmentCount: Number(attachmentCount || 0),
+    receivedAt: new Date().toISOString(),
+    timestamp: new Date().toISOString(),
+  };
+  return {
+    emailData,
+    token,
+    timestamp,
+    signature,
+  };
+}
+/**
+ * Create Express router 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 {string} options.path - Route path (default: '/inbound')
+ * @param {boolean} options.requireSignature - Whether to require signature verification (default: true)
+ * @returns {express.Router} Express router
+ */
+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 });
+    } catch (error) {
+      console.error("Inbound email processing error:", {
+        error: error.message,
+        stack: error.stack,
+        timestamp: new Date().toISOString(),
+      });
+      // Mailgun MUST receive 200 or it will retry
+      res.status(200).json({ received: true });
+    }
+  });
+  return router;
+}
+/**
+ * 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" });
+        }
+        // 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" });
+        }
+        // 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));
+        }
+        res.status(200).json({ received: true });
+      } catch (error) {
+        console.error("Inbound email processing error:", {
+          error: error.message,
+          stack: error.stack,
+          timestamp: new Date().toISOString(),
+        });
+        // Mailgun MUST receive 200 or it will retry
+        res.status(200).json({ received: true });
+      }
+    }
+  ];
+}
+// Export utilities and main functions
+module.exports = {
+  createMailgunInboundRouter,
+  createMailgunInboundMiddleware,
+  processEmailData,
+  verifyMailgunSignature,
+  extractEmail,
+  extractEmails,
+  cleanMessageId,
+  parseHeaders,
+};

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "mailgun-inbound-email",
+  "version": "1.0.0",
+  "description": "A reusable npm package for handling Mailgun inbound email webhooks with Express.js",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mailgun",
+    "inbound",
+    "email",
+    "webhook",
+    "express",
+    "middleware"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.16.1",
+    "multer": "^2.0.2"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RitikKumarSahoo/mailgun-inbound.git"
+  },
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/RitikKumarSahoo/mailgun-inbound/issues"
+  },
+  "homepage": "https://github.com/RitikKumarSahoo/mailgun-inbound#readme"
+}