MIME Attachment Filename Doctor
Paste raw .eml (RFC 822 / MIME) source, or upload a .eml file, and see exactly which declared attachment filenames will fail to save, get silently altered, or disagree between mail clients when a recipient actually saves them to disk on Windows, macOS or Linux.
Processed locally in your browser. Your file is never uploaded.
How to use this calculator
- Paste raw .eml source, or upload a .eml file — nothing leaves your browser.
- Select "Check attachment filenames".
- Review each flagged filename: which operating systems/clients are affected and why.
- Use the offered rewrite where one is available — character replacement, reserved-device-name suffixing, trailing dot/space trimming and RFC 2231 encoding are all safe, mechanical fixes; the rest (header disagreements, the double-extension heuristic) are explained because a safe automatic fix can't be guessed.
Assumptions
- Recognises eight specific attachment-filename portability problems: Windows-reserved characters, Windows-reserved device names, trailing dots/spaces, a missing plain-filename fallback for the RFC 2231 extended form, filenames over the common 255-byte limit, Content-Disposition/Content-Type filename disagreement, the double-extension extension-spoofing pattern, and raw non-ASCII filename bytes with no RFC 2231/2047 encoding.
- Reuses this microsite's existing .eml/MIME parser (the same one behind the EML/MIME Import Doctor) to locate each MIME part's declared filename — it does not re-derive MIME parsing.
- When both Content-Disposition's filename and Content-Type's name are present and agree, Content-Disposition's filename is treated as the one a real client would use to save the file (the precedence most mail clients follow); when they disagree, both are shown and flagged rather than one being silently preferred.
- A message with no attachments (no Content-Disposition: attachment and no filename/name parameters anywhere) reports zero issues — that's not a problem for this tool to flag.
Methodology
The raw text is parsed into a MIME part tree, and each part's Content-Disposition and Content-Type headers are inspected for filename/name parameters. Each declared filename is checked against documented Windows/macOS/Linux filesystem rules and RFC 2183/2231/6266 header requirements. A rewrite is offered only when it is mechanically safe and unambiguous: replacing reserved characters, suffixing a reserved device name, trimming trailing dots/spaces, adding a plain fallback for an RFC 2231 extended filename when it decodes to plain ASCII, and RFC 2231-encoding a raw non-ASCII filename. Header disagreements and the double-extension pattern are flagged with an explanation only, since guessing which name was intended — or renaming someone's real attachment based on a heuristic — is not this tool's call to make.
Worked example
A PDF attachment filename containing a colon and a question mark
Inputs: Content-Disposition: attachment; filename="Q3 report: draft?.pdf"
Result: Windows (NTFS/exFAT) refuses to save a file whose name contains < > : " / \ | ? * even though these are valid on Linux/macOS. Flagged as an error, with a safe rewrite replacing each reserved character with "_".
A .txt attachment named exactly "con.txt"
Inputs: Content-Disposition: attachment; filename="con.txt"
Result: Windows reserves CON, PRN, AUX, NUL, COM1-COM9 and LPT1-LPT9 regardless of extension. Flagged as an error, with a safe rewrite appending an underscore to the reserved name ("con_.txt").
An executable disguised behind a document-looking extension
Inputs: Content-Disposition: attachment; filename="invoice.pdf.exe"
Result: A safe-looking extension immediately followed by an executable-style one is a well-known malware-disguise pattern. Flagged as a warning (a heuristic, not a certainty) with no automatic rename — that decision is left to the recipient.
Practical guidance
- Avoid Windows-reserved characters (< > : " / \ | ? *) and reserved device names (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9) in any attachment filename you control — they will fail to save on Windows regardless of how the sending client behaves.
- If a filename needs non-ASCII characters, use the RFC 2231 extended form ("filename*=UTF-8''percent-encoded") and include a plain ASCII "filename=" fallback alongside it for older/simpler clients that don't understand the extended form.
- Never trust a Content-Type declaration to identify an attachment safely — a "safe-looking" extension followed by an executable-style one is a real, documented disguise technique, not just a portability quirk.
- Keep attachment filenames well under 255 bytes (UTF-8) — some email gateways and older systems truncate well before that.
Common mistakes
- Assuming a filename that displays correctly in the sending client will save correctly everywhere — a reserved character or device name only breaks when the recipient's operating system tries to create the file, which the sender never sees.
- Treating "filename*=" and "filename=" as interchangeable — a client that doesn't understand the RFC 2231 extended form will show no filename or a garbled one if there's no plain fallback.
FAQs
Why is a reserved character an error but a header disagreement only a warning?
A reserved character or device name will definitely fail to save on Windows — there's no ambiguity. A Content-Disposition/Content-Type disagreement is genuinely ambiguous: different real clients pick different ones, so it's a real risk but not a guaranteed failure.
Why doesn't the tool rename a file flagged by the double-extension check?
The pattern is a heuristic that can have false positives on legitimately double-extensioned files (a report literally named "summary.pdf.bak", for example). Renaming someone's actual attachment based on a guess is a judgement call this tool leaves to the recipient.
Does this tool decode or display attachment content?
No — it only inspects the Content-Disposition and Content-Type headers that declare each attachment's filename. It never decodes or displays the attachment's actual body content.