Skip to main content

Understanding Multi-Part Emails

Because MSPintegrations provides email parsing capabilities, we often receive requests for help in understanding why certain emails processed by MSPintegrations don’t look as expected. Some emails may appear to contain unexpected HTML content, while others might seem to display different information than what is visible in a typical email client.

This document is designed to provide engineers with foundational information about multi-part emails to help them understand and troubleshoot these issues. It covers the structure of multi-part emails, explains why discrepancies may occur, and offers steps to analyze and address formatting inconsistencies effectively.

How Multi-Part Emails Evolved​

In the early days of email, all messages were sent in plaintext—simple, unformatted text that every email client could display. However, as email grew in popularity, users and organizations began to demand richer, visually enhanced communication, leading to the introduction of HTML-formatted emails. HTML allowed for colors, images, links, and custom layouts that made emails more visually appealing and functional.

To support these new capabilities, a new email RFC standard introduced multi-part email messages. This standard enabled emails to contain multiple "parts"—both plaintext and HTML—within a single message. This approach preserved backwards compatibility with older, plaintext-only email clients while allowing new, HTML-enabled clients to deliver enhanced formatting.

In practice, email clients that supported HTML would display the HTML version of an email, while older clients would default to showing the plaintext part. Today, most email clients default to HTML, but they still include a plaintext version of the message to ensure compatibility with security-conscious users and text-only clients. This approach has become the industry standard for email transmission, ensuring that all users, regardless of email client or preferences, can access email content.

Multi-Part Emails in Automated Systems​

In our experience, certain automated platforms—such as ticketing systems, RMM tools, and other alert-generating software—may handle multi-part emails in ways that can create confusion or inconsistencies. Some specific cases include:

  • Differing Content Between Plaintext and HTML Parts: Many automated systems include unique content in the plaintext and HTML versions of the same email. For example, a ticketing system might include additional diagnostic information in the HTML part that isn’t present in the plaintext, or vice versa.

  • HTML-Formatted Content in Plaintext: In some cases, automated emails contain HTML formatting embedded within the plaintext part. This results in a plaintext part that appears cluttered or improperly formatted if viewed directly, as it may display tags and formatting instead of pure text. In these cases, the plaintext version of the email does not serve as a true “plain” text alternative but rather an HTML-formatted message without the appropriate headers.

These variations in how multi-part emails are constructed by automated platforms can lead to compatibility and readability issues, especially in environments where plaintext email parsing or plain-text-only clients are used.

Viewing the Raw File to See Email Parts​

To understand the structure of a multi-part email, it can be helpful to view the raw email file. This raw view shows the full message with headers, boundaries, and the contents of each part, providing insights into how the email client will interpret and display the message. Here’s how to examine a multi-part email in detail:

  1. Accessing the Raw Email File:

    • MSPintegrations: If the email is listed in the History page of MSPintegrations, you can download the raw email file directly. While viewing the email, click the download button at the top-right corner of the screen to obtain the full message source.
    • Web-Based Email Clients (Gmail, Outlook.com): These often have options like “Show Original” (Gmail) or “View Source” (Outlook) in the email options menu.
    • Desktop Clients (Outlook, Thunderbird): Most desktop clients have an option such as “View Source” or “View Raw Message” that displays the email in its original MIME format.

  2. Open the Raw Email File using a Text Editor:

    • Once you have downloaded the raw email file, you can open the file using a regular text editor (Text Editor, Notepad++, etc).

  3. Identifying Headers:

    • The email headers appear at the very beginning of the raw file. They contain essential metadata fields such as From, To, Subject, Date, and Content-Type.
    • Headers are always separated from the main body of the email by a blank line. The first blank line after the headers signals the start of the email’s content.
    • Look for the Content-Type header within the email headers, as this specifies if the email is in multipart/alternative or multipart/mixed format, indicating it contains multiple parts. This header also includes the boundary string, a unique delimiter that separates each part of the email.

  4. Finding the Delimiter for Each Part:

    • Each part of a multi-part email begins with a boundary delimiter. The boundary string, found in the Content-Type header, will look like this: 
      Content-Type: multipart/alternative;
          boundary="_mimepart_2qkckb7nufiwrx1okno7";
          charset=UTF-8
      In this example, the boundary string is _mimepart_2qkckb7nufiwrx1okno7. We will use this boundary in the remaining examples on this page.
    • Within the raw file, each part is separated by a line starting with two dashes (--) followed by the boundary string. For example: 
      --_mimepart_2qkckb7nufiwrx1okno7
    • Each part also has its own Content-Type header, which specifies whether it’s text/plain (plaintext) or text/html (HTML).

  5. Examining Each Part:

    • Plaintext Part: Usually has a header Content-Type: text/plain and contains unformatted text.
    • HTML Part: Has a header Content-Type: text/html and may include HTML tags, styles, and other formatting elements.
    • By examining each part in the raw email file, you can identify any discrepancies between the plaintext and HTML versions and detect if HTML code is mistakenly included in the plaintext part.

  6. Closing Boundary:

    • The final boundary in a multi-part email will end with two additional dashes, like this: 
      --_mimepart_2qkckb7nufiwrx1okno7--
    • This closing boundary signals the end of the multi-part message.

Encoding Considerations for Plaintext Parts​

Some plaintext parts of emails are Base64-encoded, especially in cases where the content includes special characters. When a plaintext part is Base64-encoded, it will not be immediately readable in a standard text viewer.

To decode the Base64-encoded contents of a plaintext part:

  1. Copy the encoded content from the raw email file.
  2. Use a Base64 decoder, such as https://www.base64decode.org/, to convert it to readable text.
  3. Paste the decoded output back into a text viewer to examine the plaintext part accurately.

Identifying and decoding Base64 can be crucial for troubleshooting and ensuring consistency between plaintext and HTML parts.

Nested Parts in Multi-Part Emails​

In some complex multi-part emails, there can be nested parts, each with its own boundary string. This nested structure allows emails to contain parts within parts, such as embedded attachments or additional content variations. For example, an email could contain:

  • A multipart/mixed container as the main body, which includes:
    • A multipart/alternative part (containing plaintext and HTML parts),
    • Attachments, each separated by a unique boundary string.

In these cases:

  1. Each nested part will have its own Content-Type header, which specifies the boundary string for that part.
  2. New boundaries are introduced within the nested parts to separate them further. These boundaries are independent and are only used within the scope of the specific part.

By examining the Content-Type headers and their respective boundaries at each nesting level, engineers can trace the structure of complex multi-part emails and troubleshoot formatting or display issues more accurately.

Handling Discrepancies in Multi-Part Emails Received by MSPintegrations​

If you encounter discrepancies or other issues with multi-part emails received by MSPintegrations, follow these best practices to resolve them:

  1. Contact the Email Sender or Software Vendor:

    • The ideal solution is to work with the email sender or the vendor that generated the email. Request that the plaintext part contains only plaintext (no HTML formatting) and that both the plaintext and HTML parts convey consistent content.

  2. Check Notification Templates in Configurable Systems:

    • If the email originates from a system that allows users to create notification templates (such as ticketing systems, RMM platforms, monitoring tools, or automation platforms), double-check the configuration. Ensure that:
      • The plaintext part is in plaintext format.
      • The HTML part contains properly formatted HTML.
      • Both parts share consistent content.

  3. Consider Sending Only One Part:

    • It’s acceptable to omit one part entirely. For instance, if MSPintegrations receives only an HTML part, it will automatically strip the HTML tags and convert the content to plaintext for compatibility.

  4. Use the email.bodyparts.html_to_plaintext Variable:

    • If consistency or configuration limitations make the above options unfeasible, you can configure MSPintegrations to convert the HTML part to plaintext by using the email.bodyparts.html_to_plaintext variable. This variable allows MSPintegrations to automatically remove HTML tags from the HTML part, creating a plaintext equivalent.
    • For further information, refer to MSPintegrations documentation on email body properties.

By following these steps, you can ensure multi-part emails are processed accurately, maintaining compatibility and clarity in MSPintegrations workflows.

References​