Why does an email download instead of displaying in the inbox?

You click an email, and instead of reading it in your inbox, your browser or client starts downloading a PDF. You're not alone — this happens when the email’s Content-Disposition: attachment header is set incorrectly.

This isn’t a bug. It’s how email clients are supposed to work. The header signals the client: “This is a file, not a message.” It’s defined in RFC 2183, the standard that governs MIME content handling.

Automated systems — especially those generating PDFs or reports — often miss the mark here. A poorly configured template or email engine might tag every file as an attachment, even when it should be inline. The result? Users see a download prompt rather than the content.

Key takeaways

  • The Content-Disposition: attachment header forces email clients to download a file rather than display it in the inbox.
  • This behavior is defined in RFC 2183 and is not a bug — it’s standard, expected, and consistent across clients.
  • Automated systems generating reports or documents often set this header incorrectly, leading to poor user experience when intended content doesn’t display inline.

How does the Content-Disposition header cause this behavior?

The Content-Disposition header tells the email client how to handle the content: if set to inline, it displays the content directly in the viewer; if set to attachment, it forces the client to prompt the user to download it instead. This behavior applies to any part of the email—whether it’s an HTML body, plain text, or an attached file—meaning even simple text may be downloaded if misconfigured.

Inline vs. Attachment: What the values mean

When the Content-Disposition header is set to inline, the client treats the content as part of the message itself—the user sees it in the email window, just like the rest of the body. But when it’s set to attachment, the client treats it like a file, regardless of its type or size. This is why a simple HTML message might not render in the inbox and instead trigger a download prompt.

Even if the content is HTML and intended to be displayed, incorrectly using attachment will override the default behavior. This isn’t a bug—it’s the standard, intended functionality defined in RFC 6266, the widely accepted specification for handling content disposition in HTTP and email.

Common causes and real-world impact

You’ll often see this issue when generating or forwarding emails programmatically. For example, using a template engine without properly setting content types and disposition headers can result in a legitimate email body being labeled as an attachment. Similarly, some email platforms or automated message builders apply default attachment behavior to all content that doesn’t explicitly state otherwise.

For marketers and developers, this can hurt deliverability and user experience. If a transactional email or newsletter shows up as a download instead of being read in the inbox, open rates drop and users may assume it’s a phishing attempt or a corrupted file.

It’s not just about attachments. Even a simple piece of text in a multipart email with a Content-Disposition: attachment header will be treated as a file. This behavior is consistent across major clients—Gmail, Outlook, Apple Mail—so it’s not client-specific.

Fixing it starts with validating the full MIME structure before sending. Tools like MailTester’s email checker can help you verify if a single address is valid and check how content might be interpreted before it hits the inbox.

When is Content-Disposition: attachment appropriate?

Use Content-Disposition: attachment when sending a file the user is expected to save—like a PDF report, invoice, or spreadsheet—rather than view inline. It's appropriate for non-visual content (e.g., .csv, .json, .xml) where rendering in the email client isn't useful. Never use it for the primary content of the message; that confuses clients and blocks inbox placement. The standard exists to signal intent: download, not display.

When the user should save the file

You should only use attachment for content meant to be stored or processed after delivery. Sending a PDF invoice this way ensures users don’t accidentally interact with the file in the email; they recognize it as a file to save. This applies to any document or data file not designed to render inline.

When inline is better

If the content is meant to be read directly—like an HTML email body or a simple text note—use Content-Disposition: inline. That’s how web clients render content in the inbox. Using attachment for text or HTML makes the message appear as a file, reducing engagement and increasing bounce rates.

According to RFC 2183, the Content-Disposition header exists to control how content is handled, with attachment specifically meant for "downloadable" content. The MIME standard explicitly separates inline content (intended for reading) from attached files (intended for saving). Misusing the header breaks client expectations and can trigger spam filters looking for suspicious behavior.

Think about it: if you’re sending marketing content, a newsletter, or even a summary email, you don’t want it as an attachment. That kills open rates. It also harms sender reputation if mail clients associate your brand with poor inbox placement.

For teams that send bulk emails, ensuring proper headers is part of deliverability hygiene. Tools like MailTester’s inbox placement tester can help verify that your emails render correctly across providers—identifying whether a file is being mislabeled as an attachment when it shouldn’t be.

When in doubt, check your email client’s behavior. If a document opens in the body, it should be inline. If it prompts a download, attachment is correct—but only if that’s the intended user experience.

How to fix emails that download instead of display

If your email triggers a download instead of rendering inline, the issue likely lies in the Content-Disposition header. You’re probably sending the body as an attachment with Content-Disposition: attachment. Fix it by ensuring the main content uses Content-Disposition: inline or no header at all, and structure multipart emails correctly. Use tools to inspect the full MIME layout and verify behavior across clients.

Diagnose the root cause with the right tools

Start by examining the raw email structure. Open the message in a tool like Mailtrap or use a library like MimeKit to analyze the MIME headers. Look for Content-Disposition directives on the main body part. If you see Content-Disposition: attachment applied to the text/html or text/plain part, that’s your problem.

Fix the MIME structure step by step

  1. Inspect every part’s Content-Disposition header — The body content must not be marked as an attachment. If the HTML or plain text part has Content-Disposition: attachment, change it to inline or remove the header entirely. The standard for display is no header or inline.
  2. Verify multipart/alternative structure — If your email has both text/plain and text/html parts, ensure they’re wrapped in multipart/alternative. The text/html part should explicitly use Content-Disposition: inline to signal rendering preference.
  3. Don’t inline large or complex files — If you’re embedding a PDF or image directly, consider linking to it instead. Browsers and clients may default to download if they perceive the body as a large file, even with inline tagging.
  4. Use embedded content only when necessary — If you must embed, ensure the file is small and correctly referenced via Content-Type and Content-ID. Large inlined files often trigger download behavior, especially in older clients.
  5. Test across real clients — Use a service like MailTester’s inbox placement test to send to Gmail, Outlook, and Apple Mail. Behavior can vary based on client-specific handling of MIME, especially for embedded content.

Remember: the Content-Disposition header is a hint, not a hard rule. Clients decide whether to display or download based on a mix of MIME types, size, and context. But when you get the header wrong, the decision gets flipped automatically. Correcting it restores expected behavior.

The RFC 2183 specification defines Content-Disposition as a way to hint at the intended interaction — display or download — but clients are free to ignore it in favor of their own heuristics. IETF RFC 2183

Real-world example: a weekly newsletter causing downloads

When a marketing team sent their weekly digest, recipients saw the email open as a downloadable PDF instead of readable content. The root cause was a misplaced Content-Disposition: attachment header on the embedded PDF, which forced the email client to treat it as a file to download rather than inline content. This happened because their email template used an outdated renderer that defaulted to treating all attachments as downloads.

How the outdated template created the issue

Many legacy email systems — especially older ESPs or internal templates — still assume that any file embedded with Content-Disposition: attachment should not be rendered inline. If your email includes a PDF or document with this header, even when meant to be part of the message body, mail clients like Gmail and Outlook will prompt a download instead of displaying the content in the browser.

Let’s say you’re using a template that auto-embeds a PDF via Content-Disposition: attachment. That header tells the client: “This is an attachment, not part of the message.” Even if the PDF contains the newsletter content, it’ll be treated as a file. This is defined in RFC 2183, which specifies how content disposition headers should be interpreted by email clients.

Fix: separate content from delivery method

Instead of embedding the PDF with attachment, use Content-Disposition: inline for the primary message body — especially for HTML emails. For a printable version, link to the PDF separately using a clear button like “Download the PDF” or “Read in your browser.” This way, the main message displays directly in the inbox, and the PDF is only retrieved when desired.

That change alone resolved the issue. Now users see the newsletter content right away, and the PDF remains available for download if needed. The fix was a shift in how content types are declared, not a redesign of the workflow.

You can test these changes before sending. Use MailTester’s Inbox Placement tool to see how your email renders across major clients and check if headers like Content-Disposition are interpreted correctly.

How to test email rendering before sending

You can prevent emails from downloading instead of displaying by testing rendering across real clients before sending. Use inbox-placement tools to mimic how Gmail, Outlook, and Apple Mail actually process your message. Verify the content-disposition header isn’t set to attachment on inline content, and ensure attachments are marked correctly. Catch these issues early with automated checks on your entire list using a real-time verification API.

Test rendering across real email clients

  • Run a deliverability test with tools like MailTester’s inbox tester to see how your email appears in actual client environments—Gmail, Outlook, Apple Mail, and more—before sending to live recipients.
  • Check that your email body renders inline. If content displays as a download, the Content-Disposition: attachment header is likely set on HTML or text parts instead of just actual attachments.
  • Use inbox-placement testing to simulate real-world behavior, including filters, formatting, and rendering quirks unique to each client’s rendering engine.
  • Verify that only actual file attachments (PDFs, images, spreadsheets) use Content-Disposition: attachment. Any inline content—like HTML or plain text—must use Content-Disposition: inline.

Automate checks at scale

  • Use a real-time verification API to scan entire email lists before sending, catching malformed headers, incorrect disposition types, and other delivery risks before they cause bounces or inbox placement issues.
  • Integrate with platforms like Mailchimp, HubSpot, or SendGrid via MailTester’s integration suite to validate emails automatically during campaign setup.
  • Check each email individually with the email checker if you’re sending to a single address or debugging a single issue.
  • Review how different email clients handle embedded images, inline CSS, and text formatting—especially in Outlook, which has historically strict rules about content-disposition and embedded content.

For reliable results, follow standards like RFC 2183, which defines the Content-Disposition header behavior. Misuse here is a common cause of downloads instead of display, especially in automated campaigns. Let’s fix it before it reaches the inbox.

Common causes of incorrect Content-Disposition headers

Incorrect Content-Disposition headers usually result from email templates or systems built for attachments, not inline content. When a header says attachment; filename="document.pdf" instead of inline, the email client downloads the file instead of displaying it in the browser. This often happens in legacy templates, automated systems, or poorly configured tools that don’t account for context.

Legacy templates and outdated assumptions

Many email templates were originally designed for sending PDFs or documents as attachments. If they still use hardcoded Content-Disposition: attachment with a filename, they'll trigger downloads even when the content should be shown inline. This is common in older marketing platforms or archived templates that haven’t been updated.

Modern email clients expect inline rendering for HTML content, but older systems assume all non-text parts are attachments. This mismatch causes the client to treat rich content as a file, not a message. You can avoid this by reviewing your template structure and ensuring that inline content uses Content-Disposition: inline and Content-Type: text/html or appropriate MIME types.

Automated systems and default behaviors

Automated systems—like document generators or transactional email engines—often default to attachment mode without checking how the content is meant to be consumed. They may not recognize that HTML content from a web app or CRM should appear in the email body, not as a download.

Some libraries and frameworks don’t differentiate between display and file types, so they apply the same MIME headers regardless of context. You might see this in PHP's mail() function, or with older SMTP libraries that lack fine-grained control over headers. Let’s be clear: a system that doesn’t let you specify inline or attachment behavior at runtime is fundamentally limited for sending displayable content.

Even email service providers (ESPs) can intervene. Some third-party platforms reprocess email headers during delivery. If they default to attachment for any file-like content—even a well-structured HTML attachment—they override your intent. This is especially common when using APIs that don’t expose full MIME header control.

For better control, test your emails in real environments using tools that simulate inbox rendering. MailTester’s inbox placement test checks how your email renders across major clients, including whether inline content displays correctly rather than downloading. It’s particularly useful for debugging header issues before sending to real users.

For more insight into how email clients interpret MIME headers, refer to the official RFC 2183, which defines the Content-Disposition header and its proper usage. Understanding the specification helps you avoid common misconfigurations.

How MailTester helps prevent delivery and display issues

MailTester catches content-disposition attachment header problems before they cause emails to download unexpectedly. Its inbox-placement testing checks how your messages render across real email clients, flagging incorrect MIME structure, malformed headers, and improper Content-Disposition settings that break display behavior. This prevents sends from being treated as attachments when they should be shown inline.

Real-world rendering testing detects display bugs early

Let’s be clear: just because an email sends doesn’t mean it will display correctly. MailTester’s inbox-placement tester simulates how your content appears in Gmail, Outlook, Apple Mail, and other major clients. It doesn’t just check for bounces — it verifies whether the email renders as intended. If a Content-Disposition: attachment header misfires due to incorrect MIME boundaries or wrong media type, it shows up as a red flag in the report.

Standard email specifications, like those defined in RFC 2045, define how content should be structured. A malformed Content-Type or missing boundary can cause a client to treat the entire message as an attachment. MailTester's checks include parsing raw email payloads to spot these structural flaws before sending.

Prevent display issues with data hygiene and AI-assisted diagnosis

Even the cleanest content fails if sent to invalid or poorly configured addresses. MailTester’s bulk list verification removes addresses that bounce, are role-based, or belong to disposable domains — reducing exposure to clients that handle attachments unpredictably. You’re not just improving deliverability; you’re preventing rendering issues caused by misconfigured recipient mail servers.

If you’re debugging a complex email, use the in-app AI assistant to upload a raw MIME message. It analyzes the structure, identifies problematic headers like Content-Disposition in attachment mode when inline is expected, and suggests fixes. This isn’t guesswork. It’s a direct look into what’s breaking rendering.

For ongoing workflows, integrate MailTester with platforms like Mailchimp, HubSpot, or Klaviyo to catch issues before every batch send. Whether you’re using the bulk verification tool or the real-time API, the goal remains the same: send only emails that appear as designed, not as accidental downloads.

Best practices to avoid display misfires in email campaigns

If your HTML email is downloading instead of displaying inline, it’s likely due to a wrongly set Content-Disposition: attachment header. Always use inline for message content, never override it unless you’re intentionally attaching a file. Test across inboxes, use clean templates, and validate your structure—these steps prevent display misfires before they happen. Let’s break down how.

How to handle Content-Disposition correctly

  • Set Content-Disposition: inline for any HTML or plain-text email body—this ensures the message renders in the inbox, not as a download.
  • Avoid setting the header at all unless you're attaching a file. Unnecessary headers can confuse email clients.
  • If you're sending a file, always use Content-Disposition: attachment with a descriptive filename and ensure the file type is clearly communicated.

Proactive validation and testing

  • Test all content types—including HTML, plain text, and embedded assets—in at least three major inboxes (Gmail, Outlook, Apple Mail) before sending.
  • Use structured templates where the message body and attachments are clearly separated. This reduces the risk of misinterpretation during rendering.
  • Validate your email’s HTML structure using tools like the W3C Markup Validation Service to catch syntax errors that can trigger download behavior.
  • Run inbox placement tests with real email clients via tools like MailTester’s inbox tester to confirm messages display correctly across environments.
  • Verify your sender setup with a service like MailTester’s email checker to catch invalid or malformed addresses early.
One incorrectly set header can break rendering on 30% of recipients—validating structure is not optional.

There’s no substitute for testing. Even with perfect headers, email clients sometimes deviate from specs. The best defense is a combination of proper headers, clean templates, and real-world validation. Use tools that simulate real email traffic and catch issues before they impact your deliverability.

What happens when you ignore the Content-Disposition issue?

If your email sends with a Content-Disposition: attachment header, recipients see it as a file download instead of a readable message. This means they may skip it entirely, not open it, or even mark it as spam out of confusion. Over time, this harms your sender reputation and inbox placement.

Why users skip your emails

When an email appears as a download, people assume it's a file—like a PDF or document—and often don’t open it. You’re not just losing the message; you’re losing the user’s attention entirely. The more often this happens, the higher the chance they’ll treat your emails as irrelevant or even malicious.

How bad UX hurts deliverability

Email clients and filters track engagement signals. If your emails consistently get ignored or downloaded without being opened, that behavior looks suspicious. You’re signaling inconsistency—sometimes a message, sometimes a file. That kind of pattern can trigger spam filters. According to RFC 6376, inconsistent message handling during transmission can lead to delivery anomalies. Clients use these signals to assess sender reliability.

Even if the email reaches the inbox, poor UX leads to low open rates. If recipients don’t understand why a message downloads instead of displaying, they may mark it as spam. That feedback loop damages your reputation. High spam complaints directly impact your sender score, especially with major ISPs like Gmail or Outlook. Spamhaus tracks sender reputation and lists senders with poor engagement patterns.

Let’s be clear: sending a plain-text or HTML message as an attachment isn’t a feature—it’s a technical misstep. The correct disposition is inline for content meant to be displayed, not downloaded. If you're unsure whether your email will render properly, test it with a real inbox placement tool.

Before you send your next campaign, run a quick check. Verify your email headers using our inbox placement tester to catch issues like Content-Disposition: attachment before they impact deliverability.

Fixing misdirected content disposition improves engagement

Properly configured MIME headers ensure emails render as intended—displaying content inline instead of prompting downloads. This eliminates a common user friction point.

When attachments are mistaken for the primary content, recipients miss the message entirely. Correcting the Content-Disposition header ensures visibility, increases engagement, and supports conversion goals.

Consistent rendering across email clients builds sender credibility. Misclassified content can trigger spam filters or lead to automatic rejection, especially when combined with poor sender reputation.

Keep reading

Ready to put this into practice? MailTester verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What does Content-Disposition: attachment mean in an email?

It tells the email client to treat the content as a file to download, not a message to display. This can cause HTML-based emails to open as a downloadable file.

Can a PDF in an email be displayed inline instead of downloaded?

Yes, if the Content-Disposition header is set to 'inline' or omitted. Most email clients can display PDFs inline when properly configured.

Why does my newsletter download instead of showing up in Gmail?

The email’s main content has Content-Disposition: attachment, forcing Gmail to download it. Check the MIME structure and ensure the HTML body is marked as inline.

How do I test if an email will display or download?

Use inbox-placement testing tools like MailTester to simulate real inboxes and verify how the email renders across clients.

Do all email clients treat Content-Disposition the same way?

Most do, but behavior can vary slightly. Gmail and Apple Mail usually respect inline/attachment settings reliably, while some older clients may ignore them.

Can an email have both inline and attachment parts?

Yes. A multipart message can include one part as inline (e.g., HTML body) and another as attachment (e.g., a PDF report). Proper MIME structure is critical.

Is there a way to force an email to display without downloading?

Only if the message body has correct MIME settings — specifically, Content-Disposition: inline for HTML or text parts and proper multipart structure.

How does MailTester detect incorrect Content-Disposition headers?

It analyzes the raw email’s MIME structure during inbox-placement tests and flags issues that cause unintended download behavior.

Why does my automated email system always send attachments?

The system may default to Content-Disposition: attachment for all payloads. Check the code or configuration and explicitly set inline for message bodies.

Can I use MailTester to test my entire email workflow?

Yes. MailTester's inbox-placement testing simulates real client behavior, including how emails are displayed or downloaded, helping catch delivery and rendering issues early.

Does setting Content-Disposition affect spam filtering?

Not directly, but poor rendering behavior (like automatic downloads) can lead to user complaints and lower engagement, which indirectly impacts spam scores.

Can I send an HTML email without any attachment headers?

Yes. HTML content should not have any Content-Disposition header unless it’s meant as an attachment. Omitting it defaults to inline display.