MIME Parsing: MailParse vs Mailgun Inbound Routing

Why MIME Parsing Matters for Inbound Email Workflows

MIME parsing sits at the heart of inbound email processing. If your application ingests user replies, processes automated notifications, or accepts file submissions via email, you need reliable decoding of MIME-encoded messages. This includes extracting headers, text parts, HTML parts, inline images, attachments, and nested messages, then presenting that as structured data your code can trust.

Not all parsers handle edge cases equally. Real-world email contains malformed boundaries, mixed charsets, quoted-printable bodies, base64 attachments, and nested message/rfc822 parts. Getting this wrong leads to missing files, broken inline images, or misinterpreted headers. When choosing between platforms like mailgun inbound routing and a dedicated MIME-parsing service, focus on how they decode, normalize, and deliver complex messages - not just whether they can forward an inbound webhook.

This comparison looks specifically at MIME parsing, decoding quality, delivery formats, and developer experience. For broader planning around email systems, see the Email Infrastructure Checklist for SaaS Platforms and the Top Inbound Email Processing Ideas for SaaS Platforms.

How MailParse Handles MIME Parsing

This service focuses on turning raw MIME into a structured JSON document that is easy for developers to consume. Incoming emails are received on instant addresses, parsed in a streaming pipeline, and delivered via a JSON webhook or polled from a REST API. The design centers on decoding accuracy, deterministic structure, and predictable performance.

Structured JSON schema

• Headers - Lowercased, deduplicated header map plus a preserved raw header list, with RFC 2047 encoded-words decoded and normalized to UTF-8.
• Parts - An array representing the MIME tree, where each node includes:
  • contentType, charset, disposition, filename, contentId
  • transferEncoding resolved to binary or text content
  • size in bytes and sha256 for integrity checks
  • For binary parts, content is base64 in the JSON body or stored with a signed URL pointer depending on size
• Inline image resolution - CIDs are mapped to parts, and a helper field lists the relationships between HTML content and inline images.
• Nested messages - message/rfc822 parts are parsed recursively and exposed as nested structures, not opaque blobs.

Webhook delivery format

Webhooks deliver a single JSON payload, not multipart form-data. This avoids mixing files and fields and enables atomic processing. Large attachments can be included as signed URLs with associated hashes to support streaming downloads.

REST polling and replays

Messages are available via REST with cursor-based pagination. You can replay webhook deliveries, fetch original raw MIME, and compare parsed output to source for debugging. This helps during migrations and when verifying how specific MIME messages are decoded.

Decoding details that matter

• Quoted-printable and base64 bodies are decoded to UTF-8 text where appropriate, with charset mapping and fallback handling for misdeclared charsets.
• Header parameters like filename* and encoded continuations are normalized per RFC 2231 and RFC 5987.
• TNEF (winmail.dat) extraction is attempted so that attachments hidden in legacy clients are surfaced.
• AMP part detection (text/x-amp-html) and multipart/related grouping help you decide which variant to render.

How Mailgun Inbound Routing Handles MIME Parsing

Mailgun's receiving pipeline uses routes to forward inbound messages to your URL. The default mailgun-inbound-routing webhook posts a multipart/form-data request that includes common fields and any attachments as uploaded files. Typical fields include sender, recipient, subject, body-plain, body-html, stripped-text, stripped-html, and a serialized set of headers. Attachments arrive as separate parts with filenames and content types.

You can configure routes to store messages and receive a URL for raw MIME retrieval, which is helpful for troubleshooting. Mailgun signs webhook posts so you can verify authenticity. The combination of parsed fields and files works well for many straightforward use cases, especially when you want ready-to-use text or HTML content and do not need the full MIME tree.

Where complexity grows is in reconstructing the original structure from multipart/form-data. Inline images need custom CID mapping across attachments and HTML bodies. Nested message/rfc822 content is typically provided as an attachment, which you would need to parse yourself if you want structured access. For teams needing the original MIME available consistently, enabling storage and retrieving via the provided link is a common pattern.

Side-by-Side Comparison of MIME Parsing Features

Feature	MailParse	Mailgun Inbound Routing
Webhook delivery format	JSON payload with structured MIME tree	Multipart/form-data fields plus file attachments
Raw MIME availability	Retrievable via REST and linked in webhook for debugging	Available if message storage is enabled, via message URL
Header decoding	RFC 2047 and RFC 2231 decoding with normalized UTF-8	Serialized headers included, some decoding left to the consumer
Inline image (CID) mapping	Explicit mapping between HTML and related parts	Requires custom mapping across form-data attachments
Nested message/rfc822 handling	Parsed recursively into nested structures	Provided as attachment - further parsing is your responsibility
Transfer encoding decoding	Base64 and quoted-printable decoded, with size and hash	Attachments provided as files, text fields provided decoded
Character set normalization	Automatic charset mapping to UTF-8 for text parts	Text fields are decoded, deep charset normalization may vary
REST polling	Yes - messages and parsed structures available via API	Inbound is primarily webhook-driven - storage can be queried indirectly
Replay and diff tooling	Webhook replays and side-by-side raw vs parsed inspection	Replays not standard - raw MIME can be fetched if stored
Scalability and cost profile	Optimized for high-volume parsing focused on inbound JSON delivery	Can become expensive at scale when relying on storage and routing rules
Webhook delivery consistency	JSON-only payloads simplify delivery and processing	Generally solid, but teams report occasional timing inconsistencies across regions

Code Examples

JSON Webhook handling for a MIME parsing service

The following Node.js example accepts a JSON webhook and writes attachments to disk. It assumes HMAC verification with a shared secret and that large attachments may be links you can stream.

const express = require('express');
const crypto = require('crypto');
const fs = require('fs');
const https = require('https');
const app = express();

app.use(express.json({ limit: '25mb' })); // increase if you expect big payloads

function verifySignature(req, secret) {
  const timestamp = req.header('x-timestamp');
  const signature = req.header('x-signature');
  if (!timestamp || !signature) return false;
  const body = JSON.stringify(req.body);
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp + '.' + body);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

app.post('/inbound', async (req, res) => {
  if (!verifySignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('invalid signature');
  }

  // Example shape:
  // {
  //   id, headers, parts: [{contentType, disposition, filename, contentId, size, sha256, dataBase64, url}]
  //   text, html, inlineMap: [{ cid, partIndex }]
  // }

  const msg = req.body;

  // Persist text and HTML
  if (msg.text) fs.writeFileSync(`./out/${msg.id}.txt`, msg.text, 'utf8');
  if (msg.html) fs.writeFileSync(`./out/${msg.id}.html`, msg.html, 'utf8');

  // Download large attachments via signed URLs or write embedded base64
  for (const [i, p] of msg.parts.entries()) {
    if (p.disposition === 'attachment' || p.disposition === 'inline') {
      const path = `./out/${msg.id}-${i}-${p.filename || 'part'}`;
      if (p.url) {
        await new Promise((resolve, reject) => {
          https.get(p.url, stream => {
            const file = fs.createWriteStream(path);
            stream.pipe(file);
            file.on('finish', () => file.close(resolve));
          }).on('error', reject);
        });
      } else if (p.dataBase64) {
        fs.writeFileSync(path, Buffer.from(p.dataBase64, 'base64'));
      }
    }
  }

  // Acknowledge quickly to avoid retries
  res.status(202).send('ok');
});

app.listen(3000, () => console.log('listening on 3000'));

mailgun-inbound-routing webhook using multipart/form-data

Mailgun posts multipart data. You collect fields like body-plain and body-html, verify the signature, and save attachments from the file parts. This example uses Express and Multer.

const express = require('express');
const multer = require('multer');
const crypto = require('crypto');
const fs = require('fs');

const app = express();
const upload = multer({ dest: './tmp' });

function verifyMailgunSignature(apiKey, timestamp, token, signature) {
  const hmac = crypto.createHmac('sha256', apiKey);
  hmac.update(timestamp + token);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

app.post('/mg-inbound', upload.any(), (req, res) => {
  const { timestamp, token, signature } = req.body;
  if (!verifyMailgunSignature(process.env.MAILGUN_API_KEY, timestamp, token, signature)) {
    return res.status(401).send('invalid signature');
  }

  const from = req.body.sender;
  const recipient = req.body.recipient;
  const subject = req.body.subject;
  const text = req.body['body-plain'];
  const html = req.body['body-html']; // may be absent for plain-only emails

  // Attachments are in req.files
  for (const f of req.files) {
    // f.originalname, f.mimetype, f.path
    const dest = `./out/${Date.now()}-${f.originalname || 'attachment'}`;
    fs.renameSync(f.path, dest);
  }

  // Optionally, reconstruct inline images by matching CIDs in HTML to attachment names
  // using the message-headers field for Content-Id references if present.

  res.status(202).send('ok');
});

app.listen(3001, () => console.log('listening on 3001'));

If you enable storage, Mailgun provides a URL to fetch the raw MIME. Use that to re-parse complex message/rfc822 attachments or to validate decoding differences between form-data fields and the original source.

Performance and Reliability

Payload format and throughput

JSON webhooks with embedded or linked attachments reduce overhead compared to multipart/form-data, especially when you require the full MIME tree for processing. Form-data requires additional parsing and may trigger extra I/O if your framework writes temporary files. For high-throughput parsing, a lean, normalized JSON structure often benchmarks faster per message and simplifies stateless processing across workers.

Edge case handling

• Malformed boundaries - A resilient parser should tolerate missing or extra hyphens, stray CRLFs, and out-of-order epilogues.
• Nested structures - Forwarded messages as message/rfc822 should be parsed into nested objects, not left as opaque attachments.
• Charset oddities - Many emails mix ISO-8859-1 and UTF-8, or mislabel charsets. Automatic mapping and fallback is essential for readable text.
• Quoted-printable soft breaks - Properly joined lines avoid unexpected spaces or broken URLs in text bodies.
• TNEF and calendar parts - Extract attachments from TNEF where possible and recognize text/calendar segments for ICS handling.

Webhook delivery consistency

Both platforms retry on failure and sign requests so you can validate authenticity. Teams using mailgun inbound routing have reported occasional regional timing variance and sporadic batching that can lead to unpredictable arrival times under load. To mitigate, keep the webhook fast, return 2xx quickly, and push heavy processing to a queue. Ensure idempotency by deduping on the Message-Id header or platform-specific message ID.

Operational guidance

• Respond within 2 to 5 seconds to minimize retries. Persist the payload and process asynchronously.
• Implement HMAC validation and include a replay prevention window using timestamps or nonces.
• Set attachment size policies and stream large files to object storage.
• Log both raw MIME and parsed output for a subset of messages to diagnose decoding issues.

If you are designing inbound pipelines for customer support, see the Email Infrastructure Checklist for Customer Support Teams for operational best practices.

Verdict: Which Is Better for MIME Parsing?

For applications that depend on precise decoding and a faithful representation of the MIME tree, Mailgun's inbound webhook is serviceable but oriented toward convenience fields in form-data. If you need nested message parsing, consistent CID mapping, normalized headers, and replayable JSON at scale, MailParse offers a more comprehensive MIME-parsing experience with fewer moving parts.

If your workload is simple - for example, capturing plain text replies and a couple of attachments - mailgun inbound routing works well and is easy to adopt. As complexity and volume grow, the cost of form-data processing, the friction of reconstructing inline relationships, and occasional delivery variance can add operational overhead. A JSON-first MIME parser reduces those tradeoffs and keeps your code focused on business logic instead of decoding details.

FAQ

What is MIME parsing and why can't I just read the email body?

MIME parsing is the process of interpreting an email's structure to extract parts like text/plain, text/html, inline images, attachments, and nested messages. Modern emails are multipart and often use encodings like base64 or quoted-printable. Reading only the body misses attachments and inline images, and it can mangle characters without charset normalization.

Does mailgun-inbound-routing provide the raw MIME?

Yes, if you enable message storage, Mailgun can provide a URL to the raw MIME. Without storage, the webhook arrives as multipart/form-data with parsed fields and attachments, which may not represent the full tree. Retrieving raw MIME is useful for verifying edge cases or re-parsing message/rfc822 attachments.

How do I handle inline images referenced by CID?

Look for Content-Id headers on related parts and match them to cid: references in the HTML. With form-data, you will need a custom mapping between attachments and the HTML. With JSON-based parsers that provide an inline map, you can programmatically replace cid: URLs with signed links or local paths.

What about very large attachments or messages?

Use streaming where possible, store files in object storage, and avoid holding entire attachments in memory. Return a quick 2xx response from your webhook and process in a queue. Many platforms provide signed URLs for large parts to keep webhook payloads small and reliable.

How can I improve deliverability for inbound use cases?

Inbound reliability starts with good deliverability. Authenticate domains with SPF, DKIM, and DMARC, monitor bounces, and segment transactional traffic. A solid foundation reduces malformed or spammy messages that complicate MIME parsing. For a practical checklist, see the Email Deliverability Checklist for SaaS Platforms.