mailgun-inbound-email 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+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

@@ -1,110 +1,215 @@
 # 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.
+A **production-ready** utility package for manual processing of Mailgun inbound email webhooks. Full manual control - you handle everything from webhook setup to email processing.
 
-## 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
+## 🚀 Quick Start
 
 ```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 multer = require('multer');
+const { processEmailData, verifyRequestSignature } = require('mailgun-inbound-email');
 
 const app = express();
+const upload = multer({ storage: multer.memoryStorage() });
 
-// 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.post('/webhook/inbound', 
+  express.urlencoded({ extended: true }), 
+  upload.any(), 
+  (req, res) => {
+    try {
+      // Verify signature automatically (only need signing key)
+      if (!verifyRequestSignature(req, process.env.MAILGUN_WEBHOOK_SIGNING_KEY)) {
+        return res.status(401).json({ error: 'Invalid signature' });
+      }
+      
+      // Process email data
+      const { emailData } = processEmailData(req);
+      
+      // Manual processing - you have full control
+      console.log('Email from:', emailData.from);
+      console.log('Subject:', emailData.subject);
+      
+      // Your custom logic here
+      // - Save to database
+      // - Process attachments
+      // - Send notifications
+      // - etc.
+      
+      res.status(200).json({ received: true });
+    } catch (error) {
+      console.error('Error:', error);
+      res.status(200).json({ received: true }); // Always return 200 to Mailgun
+    }
+  }
+);
 
-app.use('/email', mailgunRouter);
+app.listen(3000);
 ```
 
-### Option 2: Using Middleware
+**That's it!** Just configure your Mailgun webhook URL to point to `https://yourdomain.com/webhook/inbound`
 
-```javascript
-const express = require('express');
-const { createMailgunInboundMiddleware } = require('mailgun-inbound-email');
+> 📖 **Need help setting up the webhook?** See the detailed guide: [Setting Up Mailgun Inbound Webhook](#-setting-up-mailgun-inbound-webhook)
 
-const app = express();
+## ✨ Features
 
-const mailgunMiddleware = createMailgunInboundMiddleware({
-  signingKey: process.env.MAILGUN_WEBHOOK_SIGNING_KEY,
-  onEmailReceived: (emailData) => {
-    // Handle the email data
-    console.log('Received email:', emailData);
-  },
-});
+- ✅ **Full Manual Control** - You handle everything, no magic
+- ✅ **Automatic Signature Verification** - Just provide signing key, package handles the rest
+- ✅ **Production-ready utilities** - Battle-tested functions
+- ✅ **Mailgun signature verification** - Secure by default
+- ✅ **Replay attack prevention** - 15-minute timestamp window
+- ✅ **Automatic email parsing** - Clean, structured email data
+- ✅ **Attachment support** - Metadata + buffers for manual handling
+- ✅ **Zero dependencies** - Only Node.js built-ins
+- ✅ **Simple & lightweight** - Just utility functions
 
-app.post('/email/inbound', ...mailgunMiddleware);
+## 📦 Installation
+
+```bash
+npm install mailgun-inbound-email
 ```
 
-### Option 3: Manual Processing
+## 🎯 Usage
+
+### Basic Example
 
 ```javascript
 const express = require('express');
-const { processEmailData, verifyMailgunSignature } = require('mailgun-inbound-email');
 const multer = require('multer');
+const { processEmailData, verifyRequestSignature } = require('mailgun-inbound-email');
 
-const upload = multer({ storage: multer.memoryStorage() });
 const app = express();
+const upload = multer({ storage: multer.memoryStorage() });
 
-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' });
+app.post('/webhook/inbound', 
+  express.urlencoded({ extended: true }), 
+  upload.any(), 
+  (req, res) => {
+    try {
+      // Verify signature automatically - only need signing key!
+      const signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY;
+      if (!verifyRequestSignature(req, signingKey)) {
+        return res.status(401).json({ error: 'Invalid Mailgun signature' });
+      }
+      
+      // Process the email data
+      const { emailData } = processEmailData(req);
+      
+      // Validate required fields
+      if (!emailData.from || !emailData.to || emailData.to.length === 0) {
+        return res.status(200).json({ 
+          received: true, 
+          error: 'Missing required fields' 
+        });
+      }
+      
+      // Manual processing - you control everything
+      console.log('Processing email:', emailData.messageId);
+      console.log('From:', emailData.from);
+      console.log('To:', emailData.to);
+      console.log('Subject:', emailData.subject);
+      console.log('Attachments:', emailData.attachmentCount);
+      
+      // Your custom processing logic here
+      // Example: Save to database
+      // await db.emails.create(emailData);
+      
+      // Example: Process attachments
+      // emailData.attachments.forEach(attachment => {
+      //   if (attachment.buffer) {
+      //     fs.writeFileSync(`./uploads/${attachment.filename}`, attachment.buffer);
+      //   }
+      // });
+      
+      // Always return 200 to Mailgun
+      res.status(200).json({ 
+        received: true,
+        messageId: emailData.messageId 
+      });
+      
+    } catch (error) {
+      console.error('Error processing email:', error);
+      // Always return 200 to prevent Mailgun retries
+      res.status(200).json({ received: true });
+    }
   }
+);
+
+app.listen(3000);
+```
+
+### Processing Attachments
+
+```javascript
+const { processEmailData } = require('mailgun-inbound-email');
+const fs = require('fs');
+
+app.post('/webhook/inbound', express.urlencoded({ extended: true }), upload.any(), (req, res) => {
+  const { emailData } = processEmailData(req);
+  
+  // Process attachments manually
+  emailData.attachments.forEach(attachment => {
+    if (attachment.buffer) {
+      // Save to file system
+      fs.writeFileSync(`./uploads/${attachment.filename}`, attachment.buffer);
+      
+      // Or upload to S3, process image, etc.
+      // await s3.upload({
+      //   Key: attachment.filename,
+      //   Body: attachment.buffer,
+      //   ContentType: attachment.mimetype,
+      // }).promise();
+    }
+  });
   
-  // Your custom logic here
-  console.log(emailData);
   res.status(200).json({ received: true });
 });
 ```
 
-## Email Data Structure
+### Async Processing
 
-The `emailData` object contains:
+```javascript
+app.post('/webhook/inbound', express.urlencoded({ extended: true }), upload.any(), async (req, res) => {
+  try {
+    const { emailData } = processEmailData(req);
+    
+    // Async operations
+    await db.emails.create(emailData);
+    await notifyTeam(emailData);
+    await processAttachments(emailData);
+    
+    res.status(200).json({ received: true });
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(200).json({ received: true });
+  }
+});
+```
+
+## 📧 Email Data Structure
+
+The `emailData` object contains all parsed email information:
 
 ```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
+  messageId: "string",                    // Cleaned message ID (without angle brackets)
+  from: "sender@example.com",              // Sender email address (extracted from "Name <email>")
+  to: ["recipient@example.com"],          // Array of recipient emails
+  cc: ["cc@example.com"],                  // Array of CC emails
+  subject: "Email Subject",                // Email subject line
+  text: "Plain text body",                 // Plain text body content
+  html: "<html>...</html>",                // HTML body content
+  headers: {                               // Parsed headers object
     "Message-ID": "...",
     "From": "...",
-    // ... other headers
+    "To": "...",
+    "Subject": "...",
+    // ... all other email headers
   },
-  attachments: [                 // Attachment metadata
+  attachments: [                           // Attachment metadata + buffers
     {
       filename: "document.pdf",
       originalname: "document.pdf",
@@ -112,50 +217,315 @@ The `emailData` object contains:
       size: 12345,
       extension: "pdf",
       encoding: "base64",
-      fieldname: "attachment-1"
+      fieldname: "attachment-1",
+      buffer: Buffer,                      // File buffer for manual processing
     }
   ],
-  attachmentCount: 1,
-  receivedAt: "2024-01-01T00:00:00.000Z",
-  timestamp: "2024-01-01T00:00:00.000Z"
+  attachmentCount: 1,                     // Number of attachments
+  receivedAt: "2024-01-01T00:00:00.000Z", // ISO timestamp when received
+  timestamp: "2024-01-01T00:00:00.000Z"    // ISO timestamp (same as receivedAt)
 }
 ```
 
-## Configuration Options
+## 🛠️ API Reference
 
-### `createMailgunInboundRouter(options)`
+### `processEmailData(req)`
 
-- `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`
+Process raw Express request and return structured email data.
+
+**Parameters:**
+- `req` (Object): Express request object with `body` and `files` properties
 
-### `createMailgunInboundMiddleware(options)`
+**Returns:**
+- `Object`: `{ emailData, token, timestamp, signature }`
 
+**Throws:**
+- `Error`: If request body is invalid
+
+**Example:**
+```javascript
+const { emailData, token, timestamp, signature } = processEmailData(req);
+```
+
+### `verifyRequestSignature(req, signingKey)`
+
+Verify Mailgun webhook signature automatically from request. This is the **recommended** method as it automatically extracts token, timestamp, and signature from the request.
+
+**Parameters:**
+- `req` (Object): Express request object with body
 - `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
+**Returns:**
+- `boolean`: `true` if signature is valid
 
-- `MAILGUN_WEBHOOK_SIGNING_KEY`: Your Mailgun webhook signing key (if not provided in options)
+**Example:**
+```javascript
+const { verifyRequestSignature } = require('mailgun-inbound-email');
 
-## Utilities
+// Simple usage - automatically extracts token, timestamp, signature from req.body
+// Uses MAILGUN_WEBHOOK_SIGNING_KEY from environment automatically
+if (!verifyRequestSignature(req)) {
+  return res.status(401).json({ error: 'Invalid signature' });
+}
 
-The package also exports utility functions:
+// Or explicitly pass signing key
+if (!verifyRequestSignature(req, process.env.MAILGUN_WEBHOOK_SIGNING_KEY)) {
+  return res.status(401).json({ error: 'Invalid signature' });
+}
+```
 
-- `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
+### `verifyMailgunSignature(token, timestamp, signature, signingKey)`
 
-## Error Handling
+Verify Mailgun webhook signature manually (advanced usage). Use `verifyRequestSignature()` instead for simpler usage.
 
-The package automatically handles errors and always returns `200` status to Mailgun to prevent retries. Errors are logged to the console.
+**Parameters:**
+- `token` (string): Mailgun token from request
+- `timestamp` (string): Request timestamp
+- `signature` (string): Mailgun signature
+- `signingKey` (string): Your Mailgun webhook signing key
 
-## License
+**Returns:**
+- `boolean`: `true` if signature is valid
+
+**Example:**
+```javascript
+// Advanced usage - manually extract and verify
+const { token, timestamp, signature } = req.body;
+const isValid = verifyMailgunSignature(token, timestamp, signature, signingKey);
+if (!isValid) {
+  return res.status(401).json({ error: 'Invalid signature' });
+}
+```
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `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 array to object |
+
+## 🔐 Security
+
+### Required Environment Variable
+
+- `MAILGUN_WEBHOOK_SIGNING_KEY`: Your Mailgun webhook signing key (found in Mailgun dashboard → Settings → Webhooks)
+
+### Security Features
+
+- ✅ **Signature Verification**: Validates all webhook requests using HMAC SHA-256
+- ✅ **Replay Attack Prevention**: Rejects requests older than 15 minutes
+- ✅ **Timing-Safe Comparison**: Uses `crypto.timingSafeEqual` to prevent timing attacks
+- ✅ **Input Validation**: Validates all required fields before processing
+
+### Getting Your Signing Key
+
+1. Log in to [Mailgun Dashboard](https://app.mailgun.com)
+2. Go to **Settings** → **Webhooks**
+3. Copy your **Webhook Signing Key**
+4. Set it as environment variable: `export MAILGUN_WEBHOOK_SIGNING_KEY=your-key-here`
+
+## 📝 Setting Up Mailgun Inbound Webhook
+
+### Step 1: Install Package and Dependencies
+
+```bash
+# Install the package
+npm install mailgun-inbound-email
+
+# Install required dependencies
+npm install express multer
+```
+
+### Step 2: Set Up Your Express Server
+
+Set up your Express server with the webhook endpoint (see examples above).
+
+### Step 3: Configure Mailgun Inbound Route (Dashboard Method)
+
+Follow these steps to configure the inbound webhook URL in Mailgun Dashboard:
+
+#### Option A: Using Mailgun Dashboard (Recommended for beginners)
+
+1. **Log in to Mailgun Dashboard**
+   - Go to [https://app.mailgun.com](https://app.mailgun.com)
+   - Log in with your Mailgun account
+
+2. **Navigate to Your Domain**
+   - Click on **Sending** in the left sidebar
+   - Click on **Domains**
+   - Select your verified domain (or add a new domain if needed)
+
+3. **Go to Receiving Settings**
+   - In your domain settings, click on the **Receiving** tab
+   - You'll see options for handling inbound emails
+
+4. **Create Inbound Route**
+   - Click on **Routes** (or **Add Route**)
+   - Click **Create Route** button
+
+5. **Configure Route Settings**
+   - **Route Description**: Give it a name like "Inbound Email Webhook"
+   - **Filter Expression**: 
+     - For all emails: Select `catch_all()` or leave default
+     - For specific emails: Use `match_recipient("your-email@yourdomain.com")`
+   - **Actions**: 
+     - Select **Forward** or **Store and notify**
+     - Enter your webhook URL: `https://yourdomain.com/webhook/inbound`
+     - **Important**: Must use HTTPS (Mailgun requires it)
+
+6. **Save the Route**
+   - Click **Create Route** or **Save**
+   - Your route is now active
+
+#### Option B: Using Mailgun API (Recommended for automation)
+
+You can also create routes programmatically using the Mailgun API:
+
+```bash
+curl -X POST "https://api.mailgun.net/v3/routes" \
+  -u "api:YOUR_API_KEY" \
+  -F "priority=0" \
+  -F "description=Inbound Email Webhook" \
+  -F "expression=catch_all()" \
+  -F "action=forward('https://yourdomain.com/webhook/inbound')"
+```
+
+Or using Node.js:
+
+```javascript
+const formData = require('form-data');
+const Mailgun = require('mailgun.js');
+const mailgun = new Mailgun(formData);
+
+const mg = mailgun.client({
+  username: 'api',
+  key: process.env.MAILGUN_API_KEY
+});
+
+// Create inbound route
+mg.routes.create({
+  priority: 0,
+  description: 'Inbound Email Webhook',
+  expression: 'catch_all()',
+  action: ['forward("https://yourdomain.com/webhook/inbound")']
+})
+.then(msg => console.log('Route created:', msg))
+.catch(err => console.error('Error:', err));
+```
+
+### Step 4: Get Your Webhook Signing Key
+
+1. **Navigate to Webhooks Settings**
+   - In Mailgun Dashboard, go to **Settings** → **Webhooks**
+   - Or go to: [https://app.mailgun.com/app/webhooks](https://app.mailgun.com/app/webhooks)
+
+2. **Copy Your Signing Key**
+   - Find **Webhook Signing Key** section
+   - Click **Show** or **Reveal** to see your key
+   - Copy the signing key (it looks like: `key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
+
+3. **Set Environment Variable**
+   ```bash
+   export MAILGUN_WEBHOOK_SIGNING_KEY=your-signing-key-here
+   ```
+   
+   Or add to your `.env` file:
+   ```
+   MAILGUN_WEBHOOK_SIGNING_KEY=your-signing-key-here
+   ```
+
+### Step 5: Test Your Webhook
+
+1. **Deploy Your Server**
+   - Make sure your Express server is running and accessible via HTTPS
+   - Your webhook URL should be publicly accessible
+
+2. **Send a Test Email**
+   - Send an email to any address at your domain (e.g., `test@yourdomain.com`)
+   - Mailgun will forward it to your webhook URL
+
+3. **Check Your Logs**
+   - Check your server logs to see if the webhook was received
+   - Verify the email data is being processed correctly
+
+4. **Verify in Mailgun Dashboard**
+   - Go to **Logs** → **Webhooks** in Mailgun Dashboard
+   - You should see webhook delivery attempts and their status
+
+### Step 6: Verify Domain DNS Settings (If Needed)
+
+If you haven't set up your domain yet, make sure to:
+
+1. **Add MX Records** (for receiving emails)
+   - Go to **Sending** → **Domains** → Your Domain → **DNS Records**
+   - Add MX record pointing to Mailgun:
+     - Priority: `10`
+     - Value: `mxa.mailgun.org`
+   - Add second MX record:
+     - Priority: `10`
+     - Value: `mxb.mailgun.org`
+
+2. **Verify Domain**
+   - Mailgun will provide DNS records to verify domain ownership
+   - Add the TXT record to your domain's DNS settings
+   - Wait for DNS propagation (can take up to 48 hours)
+
+### Troubleshooting
+
+**Webhook not receiving emails?**
+- ✅ Verify your webhook URL is accessible (test with curl or browser)
+- ✅ Ensure you're using HTTPS (Mailgun requires it)
+- ✅ Check Mailgun logs for delivery errors
+- ✅ Verify your route is active in Mailgun Dashboard
+- ✅ Check your server logs for incoming requests
+
+**Signature verification failing?**
+- ✅ Verify `MAILGUN_WEBHOOK_SIGNING_KEY` is set correctly
+- ✅ Check that you copied the full signing key
+- ✅ Ensure the key matches the one in Mailgun Dashboard
+
+**Emails not being forwarded?**
+- ✅ Verify MX records are set correctly
+- ✅ Check domain verification status
+- ✅ Ensure route filter expression matches your test email
+- ✅ Check Mailgun logs for any errors
+
+### Example Webhook URL Formats
+
+- Production: `https://api.yourdomain.com/webhook/inbound`
+- Staging: `https://staging-api.yourdomain.com/webhook/inbound`
+- Local testing (using ngrok): `https://abc123.ngrok.io/webhook/inbound`
+
+**Note**: For local development, use a tool like [ngrok](https://ngrok.com/) to expose your local server:
+```bash
+ngrok http 3000
+# Use the HTTPS URL provided by ngrok
+```
+
+## 🎯 Production Checklist
+
+- ✅ Set `MAILGUN_WEBHOOK_SIGNING_KEY` environment variable
+- ✅ Use HTTPS for webhook URL (Mailgun requires it)
+- ✅ Implement your email processing logic
+- ✅ Handle attachments if needed (buffers are included)
+- ✅ Set up error monitoring/logging
+- ✅ Test webhook signature verification
+- ✅ Always return 200 status to Mailgun (prevents retries)
+
+## ⚠️ Important Notes
+
+- **Always return 200** to Mailgun (even on errors) to prevent retries
+- **Use HTTPS** for webhook URLs (Mailgun requirement)
+- **Full manual control** - this package only provides utilities, you handle everything
+- **Attachments include buffers** - handle large files appropriately
+- **Zero dependencies** - only uses Node.js built-in modules
+
+## 📄 License
 
 MIT
 
+## 🤝 Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.

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),
@@ -139,144 +226,13 @@ function processEmailData(req) {
   };
 }
 
-/**
- * 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
+// Export utility functions for manual processing
 module.exports = {
-  createMailgunInboundRouter,
-  createMailgunInboundMiddleware,
   processEmailData,
-  verifyMailgunSignature,
+  verifyRequestSignature, // Automatic signature verification (recommended)
+  verifyMailgunSignature, // Manual signature verification (advanced)
   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.0.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"
+  ]
 }

package/SETUP.md

@@ -1,62 +0,0 @@
-# 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
-```
-