Mime - Learning Module | OneNoughtOne

Loading content...

0/228

Attachments: Files in Transit

The Files We Send

Email attachments are so commonplace today that we barely notice them. We click "Attach," select a file, and expect it to arrive intact at the destination—whether that's a 15 KB invoice PDF or a 25 MB presentation deck. But this seamless experience masks considerable engineering complexity.

An email attachment involves every MIME concept we've studied working in concert: the file is identified with a Content-Type, encoded with Base64 for safe transport, wrapped in multipart structure with the message body, and labeled with Content-Disposition for proper handling at the destination.

This page explores the complete attachment lifecycle—from user selection through encoding, transmission, reception, security scanning, and extraction. Understanding this flow is essential for anyone building email systems, debugging delivery problems, or implementing file-handling features in applications.

What You Will Learn

By the end of this page, you will understand how email clients construct attachments, the complete MIME structure of a message with attachments, size limits and how they're enforced, security implications and scanning, inline vs attached content differences, and troubleshooting attachment problems.

Anatomy of an Attachment

An email attachment is simply a MIME part with specific characteristics. Let's dissect exactly how a file becomes an attachment.

Required Components

Every attachment consists of four elements:

Content-Type: Identifies what kind of file it is
Content-Transfer-Encoding: How the file is encoded (usually Base64)
Content-Disposition: Signals "attachment" with filename
Encoded Body: The actual file content, typically Base64-encoded

Optional but Common

Content-ID: For referencing the attachment from HTML body
Content-Description: Human-readable description
Content-Length: For informational purposes (not commonly used in MIME)

attachment-anatomy.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# A complete attachment part within a multipart message
 
--boundary_string_abc123
Content-Type: application/pdf; name="quarterly-report-Q1-2024.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="quarterly-report-Q1-2024.pdf";
    size=2458976;
    creation-date="Fri, 15 Mar 2024 09:30:00 GMT";
    modification-date="Mon, 18 Mar 2024 14:22:00 GMT"
Content-Description: Q1 2024 Financial Report
 
JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFn
ZXMgMiAwIFIKPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0xlbmd0aCA0NAovRmls
dGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJwzNzJQMDJWMDY0MLe0VEhJ
...
(thousands more lines of Base64)
...
JSVFBRgo=
 
--boundary_string_abc123
(next part or closing delimiter)

Breaking Down Each Header

Content-Type: application/pdf; name="quarterly-report-Q1-2024.pdf"

The MIME type identifies the file format. The name parameter is a legacy way to suggest a filename (Content-Disposition is preferred).

Content-Transfer-Encoding: base64

Indicates the file content is Base64-encoded. Email clients must decode before saving.

Content-Disposition: attachment; filename="..."

The attachment disposition tells clients to offer downloading rather than displaying inline. Parameters include:

filename (primary filename suggestion)
filename* (UTF-8 encoded filename for international characters)
size (file size in bytes, informational)
creation-date / modification-date (file timestamps)

The Body

After the blank line following headers, the entire file content appears as Base64 text. For a 2.5 MB PDF, this is approximately 3.3 MB of Base64 text, wrapped at 76 characters per line.

Filename Synchronization

You'll often see filename specified in both Content-Type (name=) and Content-Disposition (filename=). Content-Disposition takes precedence per RFC 2183, but legacy clients may check Content-Type. For maximum compatibility, include both with identical values.

Converting Mermaid diagram...

Complete Message Structure

When you send an email with text, HTML formatting, and attachments, the resulting MIME structure can be surprisingly deep. Let's examine a realistic complete message.

The Typical Structure

A formatted email with inline images and attachments uses nested multipart types:

multipart/mixed (wraps everything)
├── multipart/alternative (body formats)
│   ├── text/plain (plain text fallback)
│   └── multipart/related (HTML + inline images)
│       ├── text/html (formatted body)
│       ├── image/png (inline logo)
│       └── image/jpeg (inline photo)
├── application/pdf (attachment 1)
└── application/vnd.ms-excel (attachment 2)

This structure allows:

Recipients without HTML support see plain text
HTML-capable clients render formatted content with inline images
Attachments are offered for download regardless of display capability

complete-email-with-attachments.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
From: sales@company.com
To: customer@example.com
Subject: Your Invoice and Statement
Date: Wed, 20 Mar 2024 10:15:30 -0700
MIME-Version: 1.0
Content-Type: multipart/mixed; 
    boundary="=====MIXED_BOUNDARY====="
 
--=====MIXED_BOUNDARY=====
Content-Type: multipart/alternative; 
    boundary="=====ALT_BOUNDARY====="
 
--=====ALT_BOUNDARY=====
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
 
Dear Customer,
 
Please find your invoice and monthly statement attached.
 
Invoice: #INV-2024-0342
Amount: $1,234.56
Due Date: April 19, 2024
 
Payment can be made via the link in the HTML version of this email,
or by check mailed to our address.
 
Best regards,
Accounts Receivable
 
--=====ALT_BOUNDARY=====
Content-Type: multipart/related;
    boundary="=====RELATED_BOUNDARY=====";
    type="text/html"
 
--=====RELATED_BOUNDARY=====
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable
 
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: 'Segoe UI', Arial, sans-serif; line-height: 1.6; }
    .header { background: #1e40af; color: white; padding: 20px; }
    .invoice-box { background: #f8fafc; border: 1px solid #e2e8f0; 
                   padding: 20px; margin: 20px 0; }
    .amount { font-size: 24px; color: #059669; font-weight: bold; }
    .pay-btn { background: #2563eb; color: white; padding: 12px 24px;
               text-decoration: none; border-radius: 6px; }
  </style>
</head>
<body>
  <div class=3D"header">
    <img src=3D"cid:logo@company.com" alt=3D"Company Logo" height=3D"40">
  </div>
  <p>Dear Customer,</p>
  <div class=3D"invoice-box">
    <p><strong>Invoice:</strong> #INV-2024-0342</p>
    <p class=3D"amount">Amount Due: $1,234.56</p>
    <p><strong>Due Date:</strong> April 19, 2024</p>
  </div>
  <p><a href=3D"https://pay.company.com/inv-0342" class=3D"pay-btn">
     Pay Now</a></p>
  <p>Please find your invoice and statement attached.</p>
</body>
</html>
 
--=====RELATED_BOUNDARY=====
Content-Type: image/png
Content-Transfer-Encoding: base64
Content-ID: <logo@company.com>
Content-Disposition: inline; filename="logo.png"
 
iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAYAAAAIeF9DAAAAlUlEQVR42u3Q
MQEAAAgDoGn/zmYHDwQIdhIJCREJCREJCREJCREJCREJCREJCREJCREJCREJ
CREJCREJCREJCREJCRERkZAQCQkRCQkRCQkRCQkRCQkRCQkRCQkRCQkRCQkR
...
 
--=====RELATED_BOUNDARY=====--
 
--=====ALT_BOUNDARY=====--
 
--=====MIXED_BOUNDARY=====
Content-Type: application/pdf; name="Invoice-2024-0342.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="Invoice-2024-0342.pdf";
    size=245632
 
JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFn
ZXMgMiAwIFIKPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0xlbmd0aCA0NAovRmls
...
(Base64 PDF content - ~330 KB of text for a 245 KB PDF)
...
JSVFT0YK
 
--=====MIXED_BOUNDARY=====
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; 
    name="Statement-March-2024.xlsx"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="Statement-March-2024.xlsx";
    size=89744
 
UEsDBBQAAAAIAGCKOU4NcwzNfQEAAOcCAAALABwAX3JlbHMvLnJlbHNVVAkA
A5H+6VyR/ulcdXgLAAEE6AMAAAToAwAAzZLBTsMwDIbv...
...
(Base64 Excel content)
...
AABQSwECLQAUAAAACAAA
 
--=====MIXED_BOUNDARY=====--

Structure Breakdown

This email demonstrates the full MIME hierarchy:

multipart/mixed (outer container)
- Chosen because we have body content AND separate attachments
- Everything is a "part" of this container
multipart/alternative (first part of mixed)
- Contains text/plain and enhanced HTML versions
- Client displays the richest format it supports
multipart/related (within alternative)
- The HTML body references inline images via cid: URLs
- Images are content-ID accessible from HTML
Attachment parts (subsequent parts of mixed)
- Each file is a separate part
- Content-Disposition: attachment triggers download behavior
- Base64 encoded for safe transport

Inline vs Attached Content

The distinction between inline and attached content is subtle but important. It determines whether content is displayed within the message body or offered for download.

Content-Disposition Values

Content-Disposition: inline      → Display within message
Content-Disposition: attachment  → Offer for download

When to Use Each

Disposition	Use Case	Example
inline	Images shown in HTML body	Company logo, embedded photo
inline	Simple images that ARE the message	Single image email
attachment	Files user should save	PDFs, documents, archives
attachment	Unknown/dangerous file types	Executables, scripts
attachment	Large media files	Videos, large images
(neither)	Legacy compatibility	Some clients ignore header

inline-vs-attachment.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# INLINE: Image displayed within HTML body
Content-Type: image/jpeg
Content-Transfer-Encoding: base64
Content-ID: <product-photo@newsletter.example.com>
Content-Disposition: inline; filename="product.jpg"
 
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBA...
 
# In HTML:
<img src="cid:product-photo@newsletter.example.com" alt="New Product">
 
---
 
# ATTACHMENT: File offered for download
Content-Type: image/jpeg
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="product-hi-res.jpg"
 
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBA...
 
# Same image data, but client shows download prompt instead of displaying
 
---
 
# Content-ID enables inline referencing
# The cid: URL scheme links HTML to MIME parts
 
HTML:  <img src="cid:unique-id@domain">
                     ↓ matches ↓
Header: Content-ID: <unique-id@domain>

Client Behavior Varies

Different email clients interpret disposition differently. Some clients display inline images automatically; others require user action. Some ignore disposition entirely and decide based on Content-Type. For critical applications, test across multiple clients.

The cid: URL Scheme

Content-ID enables referencing MIME parts from HTML. The scheme is:

cid:content-id-value

Where content-id-value matches the Content-ID header (without angle brackets).

Example Flow:

Image part has: Content-ID: <logo-2024@company.example.com>
HTML references: <img src="cid:logo-2024@company.example.com">
Email client resolves cid: URL to the corresponding MIME part
Image displays inline within the HTML body

Why Not Use Regular URLs for Images?

External images (https://example.com/image.jpg) in email have issues:

Blocked by default as tracking pixels
Require network access to display
May be unavailable when recipient views message
Security concern: loads reveal recipient's IP and viewing time

Inline images via cid: display immediately, work offline, and respect recipient privacy.

Size Limits and Handling

Email systems impose various size limits that affect attachments. Understanding where limits are enforced helps diagnose delivery failures.

Where Limits Are Enforced

Attachment limits exist at multiple points:

Email Client: May reject large attachments before sending
Sending MTA: Outbound mail server may refuse oversized messages
Receiving MTA: Inbound server may reject or truncate
Mailbox Storage: Quota limits available space
Corporate Gateways: Security appliances may strip large attachments

Common Limit Values

Typical Email Size Limits
Provider/System	Max Attachment	Max Message	Notes
Gmail	25 MB	~25 MB	Google Drive links suggested for larger
Microsoft 365	25 MB (web)	25-150 MB	Outlook desktop may have higher limits
Yahoo Mail	25 MB	~25 MB	Similar to Gmail
Exchange Server	10-150 MB	Configurable	Admin-defined limits
Corporate Gateways	5-20 MB	Varies	Often more restrictive
SMTP Standard	No limit specified	Implementation-defined	RFC suggests ~10 MB reasonable

The 33% Overhead Problem

Base64 encoding increases attachment size by approximately 33%. A 25 MB file becomes ~33.3 MB after encoding. When limits are advertised as "25 MB," it's often ambiguous whether this means:

The original file size before encoding
The encoded size in the message
The complete message size including headers and body

Safe practice: assume the limit applies to the final encoded message size, and target files at ~75% of advertised limits.

ERROR Responses for Oversized Messages

When messages are rejected for size:

552 5.3.4 Message size exceeds fixed limit
552 5.2.3 Message exceeds maximum fixed size
552 Requested mail action aborted: exceeded storage allocation

These errors typically result in a bounce message (NDR) to the sender.

The Silent Stripping Problem

Some email gateways silently strip large attachments rather than bouncing the message. The recipient receives the email without attachments, possibly without any notification. If an attachment is critical, request confirmation of receipt or use alternative delivery methods for large files.

Alternatives for Large Files

When email size limits are problematic:

Cloud Storage Links: Upload to Google Drive, OneDrive, Dropbox; share link via email
File Transfer Services: WeTransfer, Firefox Send (discontinued), file.io
Compression: ZIP or RAR to reduce file size
Splitting: Divide large files into multiple emails (fragile; often fails)
FTP/SFTP: Direct file transfer for large/regular transfers

Enterprise Solutions

Corporate environments often use:

Large file transfer integration with email clients
Automatic conversion of large attachments to cloud links
Dedicated secure file exchange platforms
Message/attachment archival systems

Security Implications

Email attachments are a primary vector for malware distribution. Understanding security implications is essential for anyone handling email at scale.

Attack Vectors via Attachments

Common Attachment Threats

•Executable Malware: .exe, .scr, .bat files containing viruses, trojans, or ransomware
•Macro-Enabled Documents: .docm, .xlsm with malicious VBA macros that execute on opening
•Spoofed Extensions: "invoice.pdf.exe" — extension hidden on Windows, appears as PDF
•Archive Bombs: Highly compressed files that expand to fill disk space (zip bombs)
•Polyglot Files: Files valid as multiple types (e.g., valid JPEG and valid JavaScript)
•Embedded Content: PDFs or Office docs containing embedded scripts or objects
•HTML Attachments: Can contain JavaScript, phishing forms, or redirect to malicious sites

Content-Type Spoofing

Attackers may set misleading Content-Type headers:

# Malicious: executable disguised as PDF
Content-Type: application/pdf; name="invoice.exe"
Content-Disposition: attachment; filename="invoice.pdf.exe"

Naive clients might show a PDF icon (based on Content-Type) while the file is actually an executable. Security scanning must examine actual file content, not just headers.

Security Scanning Approaches

Signature-Based: Match known malware signatures
Heuristic Analysis: Detect suspicious patterns (e.g., executable in ZIP)
Sandboxing: Execute in isolated environment, observe behavior
Content Disarm and Reconstruction (CDR): Strip active content, rebuild safe version
Machine Learning: Detect novel malware via pattern recognition
Extension/Type Matching: Verify Content-Type matches actual file type

Commonly Blocked Attachment Types
Extension	Type	Reason for Blocking
.exe, .com, .scr	Executables	Direct malware execution
.bat, .cmd, .ps1	Scripts	Command/PowerShell execution
.vbs, .js, .wsf	Scripts	Windows Script Host execution
.msi, .msp	Installers	Software installation
.docm, .xlsm, .pptm	Macro-enabled Office	Macro malware
.jar, .jnlp	Java	Java applet execution
.hta, .html	HTML	Script execution, phishing
.iso, .img	Disk images	Can contain executables
.lnk	Shortcuts	Can execute commands

Password-Protected Archives

Some malware arrives in password-protected ZIP files with the password in the email body. This bypasses scanning (file can't be examined) while providing user with means to open it. Users should be extremely suspicious of unsolicited password-protected attachments.

attachment-security-checks.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
// TypeScript: Basic attachment security validation
 
interface AttachmentValidation {
  isSafe: boolean;
  warnings: string[];
  errors: string[];
}
 
const BLOCKED_EXTENSIONS = new Set([
  'exe', 'com', 'scr', 'bat', 'cmd', 'ps1', 'vbs', 'js', 
  'wsf', 'msi', 'msp', 'docm', 'xlsm', 'pptm', 'jar', 'jnlp',
  'hta', 'iso', 'img', 'lnk', 'pif', 'application', 'gadget',
  'msc', 'msp', 'reg', 'scf', 'ws'
]);
 
const DANGEROUS_CONTENT_TYPES = new Set([
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-sh',
  'application/x-shellscript',
]);
 
function validateAttachment(
  filename: string,
  contentType: string,
  fileSize: number,
  fileMagicBytes: Buffer
): AttachmentValidation {
  const warnings: string[] = [];
  const errors: string[] = [];
  
  // Extract extension(s)
  const parts = filename.toLowerCase().split('.');
  const extension = parts.pop() ?? '';
  const secondExtension = parts.length > 0 ? parts.pop() : null;
  
  // Check for blocked extensions
  if (BLOCKED_EXTENSIONS.has(extension)) {
    errors.push(`Blocked file extension: .${extension}`);
  }
  
  // Check for double extension trick
  if (secondExtension && BLOCKED_EXTENSIONS.has(secondExtension)) {
    errors.push(`Suspicious double extension: .${secondExtension}.${extension}`);
  }
  
  // Check dangerous content types
  if (DANGEROUS_CONTENT_TYPES.has(contentType.toLowerCase())) {
    errors.push(`Dangerous content type: ${contentType}`);
  }
  
  // Check content type vs extension mismatch
  if (contentType === 'application/pdf' && extension !== 'pdf') {
    warnings.push(`Content-Type/extension mismatch: ${contentType} vs .${extension}`);
  }
  
  // Verify magic bytes match claimed type
  const actualType = detectFileType(fileMagicBytes);
  if (actualType && !contentType.includes(actualType)) {
    warnings.push(`Content type mismatch: header says ${contentType}, file appears to be ${actualType}`);
  }
  
  // Check for ZIP bomb potential
  if ((extension === 'zip' || extension === 'gz') && fileSize < 1000) {
    warnings.push('Very small archive - potential zip bomb');
  }
  
  // Check for excessively large files
  if (fileSize > 25 * 1024 * 1024) {
    warnings.push(`Large attachment: ${(fileSize / 1024 / 1024).toFixed(1)} MB`);
  }
  
  return {
    isSafe: errors.length === 0,
    warnings,
    errors
  };
}
 
function detectFileType(magic: Buffer): string | null {
  // Check magic bytes (file signatures)
  if (magic[0] === 0xFF && magic[1] === 0xD8) return 'image/jpeg';
  if (magic[0] === 0x89 && magic[1] === 0x50) return 'image/png';
  if (magic[0] === 0x25 && magic[1] === 0x50) return 'application/pdf';
  if (magic[0] === 0x50 && magic[1] === 0x4B) return 'application/zip';
  if (magic[0] === 0x4D && magic[1] === 0x5A) return 'application/x-msdownload'; // EXE
  // ... more magic byte checks
  return null;
}
 
// Usage
const result = validateAttachment(
  'invoice.pdf.exe',
  'application/pdf',
  45000,
  Buffer.from([0x4D, 0x5A, 0x90, 0x00]) // MZ header = executable
);
 
console.log(result);
// {
//   isSafe: false,
//   warnings: ['Content type mismatch: header says application/pdf, file appears to be application/x-msdownload'],
//   errors: ['Blocked file extension: .exe', 'Suspicious double extension: .pdf.exe']
// }

Extracting Attachments

Whether building an email client, processing incoming messages, or migrating data, extracting attachments is a common task. Here's the complete process.

Extraction Algorithm

Parse message structure: Identify all MIME parts recursively
Identify attachments: Look for Content-Disposition: attachment or file-like Content-Types
Extract metadata: Filename, size, content type from headers
Decode content: Apply Content-Transfer-Encoding reversal (usually Base64)
Sanitize filename: Remove dangerous characters, validate extension
Store or process: Save to filesystem or handle in memory

extract-attachments.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
// TypeScript: Complete attachment extraction
 
import { simpleParser, ParsedMail, Attachment } from 'mailparser';
import * as fs from 'fs/promises';
import * as path from 'path';
 
interface ExtractedAttachment {
  filename: string;
  originalFilename: string;
  contentType: string;
  size: number;
  content: Buffer;
  contentId?: string;
  isInline: boolean;
}
 
async function extractAttachments(emailSource: Buffer | string): Promise<ExtractedAttachment[]> {
  const parsed: ParsedMail = await simpleParser(emailSource);
  const extracted: ExtractedAttachment[] = [];
  
  if (!parsed.attachments) {
    return extracted;
  }
  
  for (const attachment of parsed.attachments) {
    // Sanitize filename
    const sanitizedFilename = sanitizeFilename(
      attachment.filename || `attachment-${extracted.length + 1}`
    );
    
    extracted.push({
      filename: sanitizedFilename,
      originalFilename: attachment.filename ?? 'unknown',
      contentType: attachment.contentType,
      size: attachment.size,
      content: attachment.content,
      contentId: attachment.contentId,
      isInline: attachment.contentDisposition === 'inline'
    });
  }
  
  return extracted;
}
 
function sanitizeFilename(filename: string): string {
  // Remove directory traversal
  let sanitized = path.basename(filename);
  
  // Remove null bytes and control characters
  sanitized = sanitized.replace(/[\x00-\x1f\x7f]/g, '');
  
  // Replace dangerous characters
  sanitized = sanitized.replace(/[<>:"/\\|?*]/g, '_');
  
  // Handle Windows reserved names
  const reserved = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
  if (reserved.test(sanitized)) {
    sanitized = '_' + sanitized;
  }
  
  // Limit length
  if (sanitized.length > 200) {
    const ext = path.extname(sanitized);
    const base = path.basename(sanitized, ext);
    sanitized = base.substring(0, 200 - ext.length) + ext;
  }
  
  // Ensure not empty
  if (!sanitized || sanitized === '.' || sanitized === '..') {
    sanitized = 'attachment';
  }
  
  return sanitized;
}
 
async function saveAttachments(
  emailSource: Buffer,
  outputDir: string
): Promise<string[]> {
  const attachments = await extractAttachments(emailSource);
  const savedPaths: string[] = [];
  
  await fs.mkdir(outputDir, { recursive: true });
  
  for (const attachment of attachments) {
    // Handle duplicate filenames
    let finalPath = path.join(outputDir, attachment.filename);
    let counter = 1;
    
    while (await fileExists(finalPath)) {
      const ext = path.extname(attachment.filename);
      const base = path.basename(attachment.filename, ext);
      finalPath = path.join(outputDir, `${base}-${counter}${ext}`);
      counter++;
    }
    
    await fs.writeFile(finalPath, attachment.content);
    savedPaths.push(finalPath);
    
    console.log(`Saved: ${finalPath} (${formatBytes(attachment.size)})`);
  }
  
  return savedPaths;
}
 
async function fileExists(filepath: string): Promise<boolean> {
  try {
    await fs.access(filepath);
    return true;
  } catch {
    return false;
  }
}
 
function formatBytes(bytes: number): string {
  if (bytes < 1024) return bytes + ' B';
  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
  return (bytes / 1024 / 1024).toFixed(1) + ' MB';
}
 
// Usage
const emailBuffer = await fs.readFile('message.eml');
const paths = await saveAttachments(emailBuffer, './extracted-attachments');
console.log(`Extracted ${paths.length} attachments`);

Never Trust Attachment Filenames

Attachment filenames come from untrusted sources. Always sanitize before using for filesystem operations. Path traversal attacks (../../etc/passwd), reserved names (CON, NUL on Windows), and encoding tricks can all cause security issues or crashes.

Handling Inline Content

Inline attachments (Content-Disposition: inline with Content-ID) are referenced by HTML body content. To display emails correctly:

Extract inline attachments to data URIs or temporary storage
Replace cid: URLs in HTML with accessible paths/URIs
Display modified HTML

<!-- Original (requires cid: resolution) -->
<img src="cid:logo@company.com" alt="Logo">

<!-- After processing (data URI) -->
<img src="data:image/png;base64,iVBORw0KGgo..." alt="Logo">

<!-- Or (local path) -->
<img src="/attachments/msg-123/logo.png" alt="Logo">

For web-based email clients, using data URIs avoids additional HTTP requests but increases HTML size. For native clients, saving to temp files works better for large images.

Troubleshooting Attachment Problems

When attachments fail, diagnosing the problem requires understanding the complete transmission path. Here are common issues and their solutions.

Symptom: Attachment Missing Entirely

Possible causes:

Size limit exceeded; attachment stripped by gateway
Blocked file type removed by security filter
Multipart parsing error; attachment not recognized
Sender's client failed to include attachment

Diagnosis:

Check sender's sent folder for encoded attachment
Examine message headers for filtering proxies
Check gateway/security logs for blocked content
Request sender re-send with different format (e.g., ZIP, renamed extension)

Attachment Troubleshooting Checklist

•Verify attachment exists in source: Check sender's sent folder or raw message source
•Check message size: Was it over limits? Check bounces/NDRs
•Examine security headers: X-Proofpoint-Spam-Details, X-MS-Exchange-* may indicate stripping
•Verify boundary consistency: Header boundary must match body delimiters exactly
•Check encoding integrity: Base64 should be valid; test with online decoder
•Validate Content-Type: Type/extension mismatch may cause handling issues
•Test with different client: Client-specific bugs are common
•Try alternative format: ZIP the file, change extension, or use cloud link

Symptom: Attachment Corrupted

Possible causes:

Encoding/decoding mismatch (wrong transfer encoding applied)
Line ending conversion (CRLF ↔ LF) corrupted binary
Charset conversion applied to binary data
Transmission truncation (size limit hit mid-transfer)
Double encoding (Base64 applied twice)

Diagnosis:

Compare file sizes (original vs received)
Check Content-Transfer-Encoding header
Examine raw message for valid Base64
Check for server log errors during transmission
Try decoding manually to identify corruption point

Symptom: "winmail.dat" Instead of Attachments

Microsoft Outlook using TNEF (Transport Neutral Encapsulation Format) wraps attachments in a proprietary format:

Recipients without Outlook see only "winmail.dat"
Contains actual attachments in TNEF encoding
Solution: Sender should disable "Rich Text Format" in Outlook
Receivers can use tools like "TNEF's Enough" to extract

diagnose-attachment-issues.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
#!/bin/bash
# Diagnostic script for email attachment issues
 
EMAIL_FILE="$1"
 
echo "=== Attachment Diagnostics ==="
echo ""
 
# Check for multipart structure
echo "1. Multipart Structure:"
if grep -q "multipart/" "$EMAIL_FILE"; then
    grep -i "content-type:.*multipart" "$EMAIL_FILE"
    echo "   Boundaries declared:"
    grep -oP 'boundary="?[^";s]+' "$EMAIL_FILE"
else
    echo "   NOT multipart - unlikely to have attachments"
fi
echo ""
 
# Count parts
echo "2. MIME Parts (approximate):"
PART_COUNT=$(grep -c "^--" "$EMAIL_FILE" 2>/dev/null || echo "0")
echo "   Found ~$PART_COUNT boundary markers"
echo ""
 
# Check for attachment disposition
echo "3. Attachment Dispositions:"
grep -i "content-disposition:.*attachment" "$EMAIL_FILE" || echo "   No 'attachment' disposition found"
echo ""
 
# Check for Content-ID (inline)
echo "4. Inline Content (Content-ID):"
grep -i "content-id:" "$EMAIL_FILE" || echo "   No Content-ID headers found"
echo ""
 
# List Content-Types
echo "5. Content-Types Found:"
grep -i "^content-type:" "$EMAIL_FILE" | head -20
echo ""
 
# Check for Base64
echo "6. Base64 Encoding:"
if grep -q "content-transfer-encoding:.*base64" "$EMAIL_FILE"; then
    echo "   Base64 encoding found"
    # Validate Base64 blocks
    B64_CHARS=$(grep -oP '^[A-Za-z0-9+/=]{20,}$' "$EMAIL_FILE" | wc -l)
    echo "   Lines of Base64 data: ~$B64_CHARS"
else
    echo "   No Base64 encoding found"
fi
echo ""
 
# Check filenames
echo "7. Filenames Found:"
grep -oP 'filename="?[^";s]+' "$EMAIL_FILE" | sed 's/filename=/   /g'
echo ""
 
# File size
echo "8. Total Message Size:"
ls -lh "$EMAIL_FILE" | awk '{print "   "$5}'

Summary: Attachments

Attachments are where all MIME concepts come together in practical application. Let's consolidate the essential knowledge:

Key Takeaways

•Attachments are MIME parts — Identified by Content-Type, encoded via Content-Transfer-Encoding (usually Base64), and labeled with Content-Disposition: attachment.
•Message structure is hierarchical — Emails with HTML bodies, inline images, and attachments use nested multipart types (mixed → alternative → related).
•Inline vs attachment determines display — Content-Disposition controls whether content displays in body (inline with cid: references) or is offered for download.
•Size limits exist everywhere — Client, MTA, gateway, and storage limits can cause rejection or silent stripping. Account for 33% Base64 overhead.
•Security is paramount — Attachments are major malware vector. Validate types, scan content, sanitize filenames, and block dangerous extensions.
•Extraction requires care — Parse MIME structure, decode properly, sanitize filenames for filesystem safety, and handle duplicates gracefully.

Module Complete: MIME

You've now completed the comprehensive MIME module. From the fundamental purpose of extending email beyond ASCII, through content types, multipart structures, encoding mechanisms, to the practical reality of attachments—you have a complete understanding of the technology that enables rich email communication.

MIME's influence extends far beyond email into HTTP, APIs, file type handling, and data serialization across the modern Internet. The concepts you've learned here form essential knowledge for any engineer working with networked applications.

Module Complete

Congratulations! You've completed the MIME module with a thorough understanding of email attachments—from anatomy and structure through security and troubleshooting. You now understand how seemingly simple file sharing actually involves sophisticated MIME machinery working seamlessly behind the scenes. Next, you'll explore email security mechanisms that protect against spam, phishing, and spoofing.

Attachments: Files in Transit

The Files We Send

What You Will Learn

Anatomy of an Attachment

An email attachment is simply a MIME part with specific characteristics. Let's dissect exactly how a file becomes an attachment.

Required Components

Every attachment consists of four elements:

Content-Type: Identifies what kind of file it is
Content-Transfer-Encoding: How the file is encoded (usually Base64)
Content-Disposition: Signals "attachment" with filename
Encoded Body: The actual file content, typically Base64-encoded

Optional but Common

Content-ID: For referencing the attachment from HTML body
Content-Description: Human-readable description
Content-Length: For informational purposes (not commonly used in MIME)

attachment-anatomy.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# A complete attachment part within a multipart message
 
--boundary_string_abc123
Content-Type: application/pdf; name="quarterly-report-Q1-2024.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="quarterly-report-Q1-2024.pdf";
    size=2458976;
    creation-date="Fri, 15 Mar 2024 09:30:00 GMT";
    modification-date="Mon, 18 Mar 2024 14:22:00 GMT"
Content-Description: Q1 2024 Financial Report
 
JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFn
ZXMgMiAwIFIKPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0xlbmd0aCA0NAovRmls
dGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJwzNzJQMDJWMDY0MLe0VEhJ
...
(thousands more lines of Base64)
...
JSVFBRgo=
 
--boundary_string_abc123
(next part or closing delimiter)

Breaking Down Each Header

Content-Type: application/pdf; name="quarterly-report-Q1-2024.pdf"

The MIME type identifies the file format. The name parameter is a legacy way to suggest a filename (Content-Disposition is preferred).

Content-Transfer-Encoding: base64

Indicates the file content is Base64-encoded. Email clients must decode before saving.

Content-Disposition: attachment; filename="..."

The attachment disposition tells clients to offer downloading rather than displaying inline. Parameters include:

filename (primary filename suggestion)
filename* (UTF-8 encoded filename for international characters)
size (file size in bytes, informational)
creation-date / modification-date (file timestamps)

The Body

After the blank line following headers, the entire file content appears as Base64 text. For a 2.5 MB PDF, this is approximately 3.3 MB of Base64 text, wrapped at 76 characters per line.

Filename Synchronization

Converting Mermaid diagram...

Complete Message Structure

When you send an email with text, HTML formatting, and attachments, the resulting MIME structure can be surprisingly deep. Let's examine a realistic complete message.

The Typical Structure

A formatted email with inline images and attachments uses nested multipart types:

multipart/mixed (wraps everything)
├── multipart/alternative (body formats)
│   ├── text/plain (plain text fallback)
│   └── multipart/related (HTML + inline images)
│       ├── text/html (formatted body)
│       ├── image/png (inline logo)
│       └── image/jpeg (inline photo)
├── application/pdf (attachment 1)
└── application/vnd.ms-excel (attachment 2)

This structure allows:

Recipients without HTML support see plain text
HTML-capable clients render formatted content with inline images
Attachments are offered for download regardless of display capability

complete-email-with-attachments.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
From: sales@company.com
To: customer@example.com
Subject: Your Invoice and Statement
Date: Wed, 20 Mar 2024 10:15:30 -0700
MIME-Version: 1.0
Content-Type: multipart/mixed; 
    boundary="=====MIXED_BOUNDARY====="
 
--=====MIXED_BOUNDARY=====
Content-Type: multipart/alternative; 
    boundary="=====ALT_BOUNDARY====="
 
--=====ALT_BOUNDARY=====
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
 
Dear Customer,
 
Please find your invoice and monthly statement attached.
 
Invoice: #INV-2024-0342
Amount: $1,234.56
Due Date: April 19, 2024
 
Payment can be made via the link in the HTML version of this email,
or by check mailed to our address.
 
Best regards,
Accounts Receivable
 
--=====ALT_BOUNDARY=====
Content-Type: multipart/related;
    boundary="=====RELATED_BOUNDARY=====";
    type="text/html"
 
--=====RELATED_BOUNDARY=====
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable
 
<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: 'Segoe UI', Arial, sans-serif; line-height: 1.6; }
    .header { background: #1e40af; color: white; padding: 20px; }
    .invoice-box { background: #f8fafc; border: 1px solid #e2e8f0; 
                   padding: 20px; margin: 20px 0; }
    .amount { font-size: 24px; color: #059669; font-weight: bold; }
    .pay-btn { background: #2563eb; color: white; padding: 12px 24px;
               text-decoration: none; border-radius: 6px; }
  </style>
</head>
<body>
  <div class=3D"header">
    <img src=3D"cid:logo@company.com" alt=3D"Company Logo" height=3D"40">
  </div>
  <p>Dear Customer,</p>
  <div class=3D"invoice-box">
    <p><strong>Invoice:</strong> #INV-2024-0342</p>
    <p class=3D"amount">Amount Due: $1,234.56</p>
    <p><strong>Due Date:</strong> April 19, 2024</p>
  </div>
  <p><a href=3D"https://pay.company.com/inv-0342" class=3D"pay-btn">
     Pay Now</a></p>
  <p>Please find your invoice and statement attached.</p>
</body>
</html>
 
--=====RELATED_BOUNDARY=====
Content-Type: image/png
Content-Transfer-Encoding: base64
Content-ID: <logo@company.com>
Content-Disposition: inline; filename="logo.png"
 
iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAYAAAAIeF9DAAAAlUlEQVR42u3Q
MQEAAAgDoGn/zmYHDwQIdhIJCREJCREJCREJCREJCREJCREJCREJCREJCREJ
CREJCREJCREJCREJCRERkZAQCQkRCQkRCQkRCQkRCQkRCQkRCQkRCQkRCQkR
...
 
--=====RELATED_BOUNDARY=====--
 
--=====ALT_BOUNDARY=====--
 
--=====MIXED_BOUNDARY=====
Content-Type: application/pdf; name="Invoice-2024-0342.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="Invoice-2024-0342.pdf";
    size=245632
 
JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFn
ZXMgMiAwIFIKPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0xlbmd0aCA0NAovRmls
...
(Base64 PDF content - ~330 KB of text for a 245 KB PDF)
...
JSVFT0YK
 
--=====MIXED_BOUNDARY=====
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; 
    name="Statement-March-2024.xlsx"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; 
    filename="Statement-March-2024.xlsx";
    size=89744
 
UEsDBBQAAAAIAGCKOU4NcwzNfQEAAOcCAAALABwAX3JlbHMvLnJlbHNVVAkA
A5H+6VyR/ulcdXgLAAEE6AMAAAToAwAAzZLBTsMwDIbv...
...
(Base64 Excel content)
...
AABQSwECLQAUAAAACAAA
 
--=====MIXED_BOUNDARY=====--

Structure Breakdown

This email demonstrates the full MIME hierarchy:

multipart/mixed (outer container)
- Chosen because we have body content AND separate attachments
- Everything is a "part" of this container
multipart/alternative (first part of mixed)
- Contains text/plain and enhanced HTML versions
- Client displays the richest format it supports
multipart/related (within alternative)
- The HTML body references inline images via cid: URLs
- Images are content-ID accessible from HTML
Attachment parts (subsequent parts of mixed)
- Each file is a separate part
- Content-Disposition: attachment triggers download behavior
- Base64 encoded for safe transport

Inline vs Attached Content

The distinction between inline and attached content is subtle but important. It determines whether content is displayed within the message body or offered for download.

Content-Disposition Values

Content-Disposition: inline      → Display within message
Content-Disposition: attachment  → Offer for download

When to Use Each

Disposition	Use Case	Example
inline	Images shown in HTML body	Company logo, embedded photo
inline	Simple images that ARE the message	Single image email
attachment	Files user should save	PDFs, documents, archives
attachment	Unknown/dangerous file types	Executables, scripts
attachment	Large media files	Videos, large images
(neither)	Legacy compatibility	Some clients ignore header

inline-vs-attachment.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# INLINE: Image displayed within HTML body
Content-Type: image/jpeg
Content-Transfer-Encoding: base64
Content-ID: <product-photo@newsletter.example.com>
Content-Disposition: inline; filename="product.jpg"
 
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBA...
 
# In HTML:
<img src="cid:product-photo@newsletter.example.com" alt="New Product">
 
---
 
# ATTACHMENT: File offered for download
Content-Type: image/jpeg
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="product-hi-res.jpg"
 
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAUDBA...
 
# Same image data, but client shows download prompt instead of displaying
 
---
 
# Content-ID enables inline referencing
# The cid: URL scheme links HTML to MIME parts
 
HTML:  <img src="cid:unique-id@domain">
                     ↓ matches ↓
Header: Content-ID: <unique-id@domain>

Client Behavior Varies

The cid: URL Scheme

Content-ID enables referencing MIME parts from HTML. The scheme is:

cid:content-id-value

Where content-id-value matches the Content-ID header (without angle brackets).

Example Flow:

Image part has: Content-ID: <logo-2024@company.example.com>
HTML references: <img src="cid:logo-2024@company.example.com">
Email client resolves cid: URL to the corresponding MIME part
Image displays inline within the HTML body

Why Not Use Regular URLs for Images?

External images (https://example.com/image.jpg) in email have issues:

Blocked by default as tracking pixels
Require network access to display
May be unavailable when recipient views message
Security concern: loads reveal recipient's IP and viewing time

Inline images via cid: display immediately, work offline, and respect recipient privacy.

Size Limits and Handling

Email systems impose various size limits that affect attachments. Understanding where limits are enforced helps diagnose delivery failures.

Where Limits Are Enforced

Attachment limits exist at multiple points:

Email Client: May reject large attachments before sending
Sending MTA: Outbound mail server may refuse oversized messages
Receiving MTA: Inbound server may reject or truncate
Mailbox Storage: Quota limits available space
Corporate Gateways: Security appliances may strip large attachments

Common Limit Values

Typical Email Size Limits
Provider/System	Max Attachment	Max Message	Notes
Gmail	25 MB	~25 MB	Google Drive links suggested for larger
Microsoft 365	25 MB (web)	25-150 MB	Outlook desktop may have higher limits
Yahoo Mail	25 MB	~25 MB	Similar to Gmail
Exchange Server	10-150 MB	Configurable	Admin-defined limits
Corporate Gateways	5-20 MB	Varies	Often more restrictive
SMTP Standard	No limit specified	Implementation-defined	RFC suggests ~10 MB reasonable

The 33% Overhead Problem

Base64 encoding increases attachment size by approximately 33%. A 25 MB file becomes ~33.3 MB after encoding. When limits are advertised as "25 MB," it's often ambiguous whether this means:

The original file size before encoding
The encoded size in the message
The complete message size including headers and body

Safe practice: assume the limit applies to the final encoded message size, and target files at ~75% of advertised limits.

ERROR Responses for Oversized Messages

When messages are rejected for size:

552 5.3.4 Message size exceeds fixed limit
552 5.2.3 Message exceeds maximum fixed size
552 Requested mail action aborted: exceeded storage allocation

These errors typically result in a bounce message (NDR) to the sender.

The Silent Stripping Problem

Alternatives for Large Files

When email size limits are problematic:

Cloud Storage Links: Upload to Google Drive, OneDrive, Dropbox; share link via email
File Transfer Services: WeTransfer, Firefox Send (discontinued), file.io
Compression: ZIP or RAR to reduce file size
Splitting: Divide large files into multiple emails (fragile; often fails)
FTP/SFTP: Direct file transfer for large/regular transfers

Enterprise Solutions

Corporate environments often use:

Large file transfer integration with email clients
Automatic conversion of large attachments to cloud links
Dedicated secure file exchange platforms
Message/attachment archival systems

Security Implications

Email attachments are a primary vector for malware distribution. Understanding security implications is essential for anyone handling email at scale.

Attack Vectors via Attachments

Common Attachment Threats

•Executable Malware: .exe, .scr, .bat files containing viruses, trojans, or ransomware
•Macro-Enabled Documents: .docm, .xlsm with malicious VBA macros that execute on opening
•Spoofed Extensions: "invoice.pdf.exe" — extension hidden on Windows, appears as PDF
•Archive Bombs: Highly compressed files that expand to fill disk space (zip bombs)
•Polyglot Files: Files valid as multiple types (e.g., valid JPEG and valid JavaScript)
•Embedded Content: PDFs or Office docs containing embedded scripts or objects
•HTML Attachments: Can contain JavaScript, phishing forms, or redirect to malicious sites

Content-Type Spoofing

Attackers may set misleading Content-Type headers:

# Malicious: executable disguised as PDF
Content-Type: application/pdf; name="invoice.exe"
Content-Disposition: attachment; filename="invoice.pdf.exe"

Naive clients might show a PDF icon (based on Content-Type) while the file is actually an executable. Security scanning must examine actual file content, not just headers.

Security Scanning Approaches

Signature-Based: Match known malware signatures
Heuristic Analysis: Detect suspicious patterns (e.g., executable in ZIP)
Sandboxing: Execute in isolated environment, observe behavior
Content Disarm and Reconstruction (CDR): Strip active content, rebuild safe version
Machine Learning: Detect novel malware via pattern recognition
Extension/Type Matching: Verify Content-Type matches actual file type

Commonly Blocked Attachment Types
Extension	Type	Reason for Blocking
.exe, .com, .scr	Executables	Direct malware execution
.bat, .cmd, .ps1	Scripts	Command/PowerShell execution
.vbs, .js, .wsf	Scripts	Windows Script Host execution
.msi, .msp	Installers	Software installation
.docm, .xlsm, .pptm	Macro-enabled Office	Macro malware
.jar, .jnlp	Java	Java applet execution
.hta, .html	HTML	Script execution, phishing
.iso, .img	Disk images	Can contain executables
.lnk	Shortcuts	Can execute commands

Password-Protected Archives

attachment-security-checks.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
// TypeScript: Basic attachment security validation
 
interface AttachmentValidation {
  isSafe: boolean;
  warnings: string[];
  errors: string[];
}
 
const BLOCKED_EXTENSIONS = new Set([
  'exe', 'com', 'scr', 'bat', 'cmd', 'ps1', 'vbs', 'js', 
  'wsf', 'msi', 'msp', 'docm', 'xlsm', 'pptm', 'jar', 'jnlp',
  'hta', 'iso', 'img', 'lnk', 'pif', 'application', 'gadget',
  'msc', 'msp', 'reg', 'scf', 'ws'
]);
 
const DANGEROUS_CONTENT_TYPES = new Set([
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-sh',
  'application/x-shellscript',
]);
 
function validateAttachment(
  filename: string,
  contentType: string,
  fileSize: number,
  fileMagicBytes: Buffer
): AttachmentValidation {
  const warnings: string[] = [];
  const errors: string[] = [];
  
  // Extract extension(s)
  const parts = filename.toLowerCase().split('.');
  const extension = parts.pop() ?? '';
  const secondExtension = parts.length > 0 ? parts.pop() : null;
  
  // Check for blocked extensions
  if (BLOCKED_EXTENSIONS.has(extension)) {
    errors.push(`Blocked file extension: .${extension}`);
  }
  
  // Check for double extension trick
  if (secondExtension && BLOCKED_EXTENSIONS.has(secondExtension)) {
    errors.push(`Suspicious double extension: .${secondExtension}.${extension}`);
  }
  
  // Check dangerous content types
  if (DANGEROUS_CONTENT_TYPES.has(contentType.toLowerCase())) {
    errors.push(`Dangerous content type: ${contentType}`);
  }
  
  // Check content type vs extension mismatch
  if (contentType === 'application/pdf' && extension !== 'pdf') {
    warnings.push(`Content-Type/extension mismatch: ${contentType} vs .${extension}`);
  }
  
  // Verify magic bytes match claimed type
  const actualType = detectFileType(fileMagicBytes);
  if (actualType && !contentType.includes(actualType)) {
    warnings.push(`Content type mismatch: header says ${contentType}, file appears to be ${actualType}`);
  }
  
  // Check for ZIP bomb potential
  if ((extension === 'zip' || extension === 'gz') && fileSize < 1000) {
    warnings.push('Very small archive - potential zip bomb');
  }
  
  // Check for excessively large files
  if (fileSize > 25 * 1024 * 1024) {
    warnings.push(`Large attachment: ${(fileSize / 1024 / 1024).toFixed(1)} MB`);
  }
  
  return {
    isSafe: errors.length === 0,
    warnings,
    errors
  };
}
 
function detectFileType(magic: Buffer): string | null {
  // Check magic bytes (file signatures)
  if (magic[0] === 0xFF && magic[1] === 0xD8) return 'image/jpeg';
  if (magic[0] === 0x89 && magic[1] === 0x50) return 'image/png';
  if (magic[0] === 0x25 && magic[1] === 0x50) return 'application/pdf';
  if (magic[0] === 0x50 && magic[1] === 0x4B) return 'application/zip';
  if (magic[0] === 0x4D && magic[1] === 0x5A) return 'application/x-msdownload'; // EXE
  // ... more magic byte checks
  return null;
}
 
// Usage
const result = validateAttachment(
  'invoice.pdf.exe',
  'application/pdf',
  45000,
  Buffer.from([0x4D, 0x5A, 0x90, 0x00]) // MZ header = executable
);
 
console.log(result);
// {
//   isSafe: false,
//   warnings: ['Content type mismatch: header says application/pdf, file appears to be application/x-msdownload'],
//   errors: ['Blocked file extension: .exe', 'Suspicious double extension: .pdf.exe']
// }

Extracting Attachments

Whether building an email client, processing incoming messages, or migrating data, extracting attachments is a common task. Here's the complete process.

Extraction Algorithm

Parse message structure: Identify all MIME parts recursively
Identify attachments: Look for Content-Disposition: attachment or file-like Content-Types
Extract metadata: Filename, size, content type from headers
Decode content: Apply Content-Transfer-Encoding reversal (usually Base64)
Sanitize filename: Remove dangerous characters, validate extension
Store or process: Save to filesystem or handle in memory

extract-attachments.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
// TypeScript: Complete attachment extraction
 
import { simpleParser, ParsedMail, Attachment } from 'mailparser';
import * as fs from 'fs/promises';
import * as path from 'path';
 
interface ExtractedAttachment {
  filename: string;
  originalFilename: string;
  contentType: string;
  size: number;
  content: Buffer;
  contentId?: string;
  isInline: boolean;
}
 
async function extractAttachments(emailSource: Buffer | string): Promise<ExtractedAttachment[]> {
  const parsed: ParsedMail = await simpleParser(emailSource);
  const extracted: ExtractedAttachment[] = [];
  
  if (!parsed.attachments) {
    return extracted;
  }
  
  for (const attachment of parsed.attachments) {
    // Sanitize filename
    const sanitizedFilename = sanitizeFilename(
      attachment.filename || `attachment-${extracted.length + 1}`
    );
    
    extracted.push({
      filename: sanitizedFilename,
      originalFilename: attachment.filename ?? 'unknown',
      contentType: attachment.contentType,
      size: attachment.size,
      content: attachment.content,
      contentId: attachment.contentId,
      isInline: attachment.contentDisposition === 'inline'
    });
  }
  
  return extracted;
}
 
function sanitizeFilename(filename: string): string {
  // Remove directory traversal
  let sanitized = path.basename(filename);
  
  // Remove null bytes and control characters
  sanitized = sanitized.replace(/[\x00-\x1f\x7f]/g, '');
  
  // Replace dangerous characters
  sanitized = sanitized.replace(/[<>:"/\\|?*]/g, '_');
  
  // Handle Windows reserved names
  const reserved = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
  if (reserved.test(sanitized)) {
    sanitized = '_' + sanitized;
  }
  
  // Limit length
  if (sanitized.length > 200) {
    const ext = path.extname(sanitized);
    const base = path.basename(sanitized, ext);
    sanitized = base.substring(0, 200 - ext.length) + ext;
  }
  
  // Ensure not empty
  if (!sanitized || sanitized === '.' || sanitized === '..') {
    sanitized = 'attachment';
  }
  
  return sanitized;
}
 
async function saveAttachments(
  emailSource: Buffer,
  outputDir: string
): Promise<string[]> {
  const attachments = await extractAttachments(emailSource);
  const savedPaths: string[] = [];
  
  await fs.mkdir(outputDir, { recursive: true });
  
  for (const attachment of attachments) {
    // Handle duplicate filenames
    let finalPath = path.join(outputDir, attachment.filename);
    let counter = 1;
    
    while (await fileExists(finalPath)) {
      const ext = path.extname(attachment.filename);
      const base = path.basename(attachment.filename, ext);
      finalPath = path.join(outputDir, `${base}-${counter}${ext}`);
      counter++;
    }
    
    await fs.writeFile(finalPath, attachment.content);
    savedPaths.push(finalPath);
    
    console.log(`Saved: ${finalPath} (${formatBytes(attachment.size)})`);
  }
  
  return savedPaths;
}
 
async function fileExists(filepath: string): Promise<boolean> {
  try {
    await fs.access(filepath);
    return true;
  } catch {
    return false;
  }
}
 
function formatBytes(bytes: number): string {
  if (bytes < 1024) return bytes + ' B';
  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
  return (bytes / 1024 / 1024).toFixed(1) + ' MB';
}
 
// Usage
const emailBuffer = await fs.readFile('message.eml');
const paths = await saveAttachments(emailBuffer, './extracted-attachments');
console.log(`Extracted ${paths.length} attachments`);

Never Trust Attachment Filenames

Handling Inline Content

Inline attachments (Content-Disposition: inline with Content-ID) are referenced by HTML body content. To display emails correctly:

Extract inline attachments to data URIs or temporary storage
Replace cid: URLs in HTML with accessible paths/URIs
Display modified HTML

<!-- Original (requires cid: resolution) -->
<img src="cid:logo@company.com" alt="Logo">

<!-- After processing (data URI) -->
<img src="data:image/png;base64,iVBORw0KGgo..." alt="Logo">

<!-- Or (local path) -->
<img src="/attachments/msg-123/logo.png" alt="Logo">

For web-based email clients, using data URIs avoids additional HTTP requests but increases HTML size. For native clients, saving to temp files works better for large images.

Troubleshooting Attachment Problems

When attachments fail, diagnosing the problem requires understanding the complete transmission path. Here are common issues and their solutions.

Symptom: Attachment Missing Entirely

Possible causes:

Size limit exceeded; attachment stripped by gateway
Blocked file type removed by security filter
Multipart parsing error; attachment not recognized
Sender's client failed to include attachment

Diagnosis:

Check sender's sent folder for encoded attachment
Examine message headers for filtering proxies
Check gateway/security logs for blocked content
Request sender re-send with different format (e.g., ZIP, renamed extension)

Attachment Troubleshooting Checklist

•Verify attachment exists in source: Check sender's sent folder or raw message source
•Check message size: Was it over limits? Check bounces/NDRs
•Examine security headers: X-Proofpoint-Spam-Details, X-MS-Exchange-* may indicate stripping
•Verify boundary consistency: Header boundary must match body delimiters exactly
•Check encoding integrity: Base64 should be valid; test with online decoder
•Validate Content-Type: Type/extension mismatch may cause handling issues
•Test with different client: Client-specific bugs are common
•Try alternative format: ZIP the file, change extension, or use cloud link

Symptom: Attachment Corrupted

Possible causes:

Encoding/decoding mismatch (wrong transfer encoding applied)
Line ending conversion (CRLF ↔ LF) corrupted binary
Charset conversion applied to binary data
Transmission truncation (size limit hit mid-transfer)
Double encoding (Base64 applied twice)

Diagnosis:

Compare file sizes (original vs received)
Check Content-Transfer-Encoding header
Examine raw message for valid Base64
Check for server log errors during transmission
Try decoding manually to identify corruption point

Symptom: "winmail.dat" Instead of Attachments

Microsoft Outlook using TNEF (Transport Neutral Encapsulation Format) wraps attachments in a proprietary format:

Recipients without Outlook see only "winmail.dat"
Contains actual attachments in TNEF encoding
Solution: Sender should disable "Rich Text Format" in Outlook
Receivers can use tools like "TNEF's Enough" to extract

diagnose-attachment-issues.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
#!/bin/bash
# Diagnostic script for email attachment issues
 
EMAIL_FILE="$1"
 
echo "=== Attachment Diagnostics ==="
echo ""
 
# Check for multipart structure
echo "1. Multipart Structure:"
if grep -q "multipart/" "$EMAIL_FILE"; then
    grep -i "content-type:.*multipart" "$EMAIL_FILE"
    echo "   Boundaries declared:"
    grep -oP 'boundary="?[^";s]+' "$EMAIL_FILE"
else
    echo "   NOT multipart - unlikely to have attachments"
fi
echo ""
 
# Count parts
echo "2. MIME Parts (approximate):"
PART_COUNT=$(grep -c "^--" "$EMAIL_FILE" 2>/dev/null || echo "0")
echo "   Found ~$PART_COUNT boundary markers"
echo ""
 
# Check for attachment disposition
echo "3. Attachment Dispositions:"
grep -i "content-disposition:.*attachment" "$EMAIL_FILE" || echo "   No 'attachment' disposition found"
echo ""
 
# Check for Content-ID (inline)
echo "4. Inline Content (Content-ID):"
grep -i "content-id:" "$EMAIL_FILE" || echo "   No Content-ID headers found"
echo ""
 
# List Content-Types
echo "5. Content-Types Found:"
grep -i "^content-type:" "$EMAIL_FILE" | head -20
echo ""
 
# Check for Base64
echo "6. Base64 Encoding:"
if grep -q "content-transfer-encoding:.*base64" "$EMAIL_FILE"; then
    echo "   Base64 encoding found"
    # Validate Base64 blocks
    B64_CHARS=$(grep -oP '^[A-Za-z0-9+/=]{20,}$' "$EMAIL_FILE" | wc -l)
    echo "   Lines of Base64 data: ~$B64_CHARS"
else
    echo "   No Base64 encoding found"
fi
echo ""
 
# Check filenames
echo "7. Filenames Found:"
grep -oP 'filename="?[^";s]+' "$EMAIL_FILE" | sed 's/filename=/   /g'
echo ""
 
# File size
echo "8. Total Message Size:"
ls -lh "$EMAIL_FILE" | awk '{print "   "$5}'

Summary: Attachments

Attachments are where all MIME concepts come together in practical application. Let's consolidate the essential knowledge:

Key Takeaways

•Attachments are MIME parts — Identified by Content-Type, encoded via Content-Transfer-Encoding (usually Base64), and labeled with Content-Disposition: attachment.
•Message structure is hierarchical — Emails with HTML bodies, inline images, and attachments use nested multipart types (mixed → alternative → related).
•Inline vs attachment determines display — Content-Disposition controls whether content displays in body (inline with cid: references) or is offered for download.
•Size limits exist everywhere — Client, MTA, gateway, and storage limits can cause rejection or silent stripping. Account for 33% Base64 overhead.
•Security is paramount — Attachments are major malware vector. Validate types, scan content, sanitize filenames, and block dangerous extensions.
•Extraction requires care — Parse MIME structure, decode properly, sanitize filenames for filesystem safety, and handle duplicates gracefully.

Module Complete: MIME

Module Complete