jord-jd/email-structure-parser

Email Structure Parser

v4.1.0 2026-07-18 09:28 UTC

Requires

• php: >=5.4
• ext-imap: *

Requires (Dev)

• phpunit/phpunit: ^4.8 || ^9.6

Replaces

• divineomega/email-structure-parser: v4.1.0

LGPL-3.0-only

• Jordan Hall

Published on Packagist.org on 2026-07-18 09:30 UTC

README

Given an IMAP stream and a message number, this library will parse the structure of multipart emails.

Installation

You can easily install the Email Structure Parser package using the following Composer command.

composer require jord-jd/email-structure-parser

Usage

To use this parser, you must have first connect to a mail server using PHP's built-in imap_open function. Once connected, you then need to retrieve a message number, via the imap_search function.

Once you have a message number, you can pass it, along with the IMAP stream object, into the EmailStructureParser. You can then call the getParts() method to retrieve an array of parsed email parts split up by mime type.

See the example usage code below.

use JordJD\EmailStructureParser\EmailStructureParser;

// Connect to mailbox
$imapStream = imap_open('{outlook.office365.com:993/ssl/novalidate-cert}INBOX', getenv('USERNAME'), getenv('PASSWORD'));

// Get a message number (in this example, just get the first)
$msgNums = imap_search($imapStream, 'ALL');
$msgNum = $msgNums[0];

// Load message into parser
$parser = new EmailStructureParser($imapStream, $msgNum);

// Get parsed multipart email parts - including plain text and/or HTML content, and any attachments
$parts = $parser->getParts();

// Output HTML email content
var_dump($parts['TEXT/HTML']);

// Save attached PNG images
foreach($parts['IMAGE/PNG'] as $image) {
    file_put_contents($image->name, $image->content);
}

Attachment names are read from both MIME name parameters and standard content-disposition filename parameters. Base64 and quoted-printable parts are decoded automatically. If the IMAP structure or a requested body cannot be fetched, the parser now throws a RuntimeException instead of returning partially corrupted data.

Testing without a mailbox

The existing two-argument constructor remains unchanged. For deterministic tests, you may optionally supply a pre-fetched IMAP structure and a body-fetching callback as the third and fourth arguments.

$parser = new EmailStructureParser(
    null,
    1,
    $structure,
    function ($stream, $messageNumber, $partNumber) use ($bodies) {
        return $bodies[$partNumber];
    }
);

Content IDs

Some emails embed images into the HTML content using cid: urls. These URLs link to the content ID of another part within the email, rather than being an absolute https:// URL that can be resolved normally.

If one exists, this content ID will be exposed via the contentId property of the Part:

foreach($parts['IMAGE/PNG'] as $image) {
    // Store the file as in the above example:
    file_put_contents($image->name, $image->content);
    // You would then want to store this relationship in your database:    
    echo "{$image->contentId} => {$image->name}\n";
}