Mail Parser Laravel Package

Getting Started

1. Install the package via Composer: composer require opcodesio/mail-parser.
2. No heavy config required — the package works out-of-the-box, but optional Laravel service provider auto-registration handles integration.
3. First use case: Parse an .eml file (e.g., from storage) into a structured object:

   use Opcodes\MailParser\Parser;
   
   $parser = new Parser();
   $email = $parser->parse(file_get_contents('message.eml'));
   
   echo $email->subject;
   echo $email->from->email; // => 'sender@example.com'
   

4. Check the README in the GitHub repo for quick examples and API reference — despite low stars, it’s actively maintained (last release in 2026).

Implementation Patterns

• Batch inbound email processing: Parse .eml files dropped by MailTrap, Mailgun, or custom MX listeners into structured arrays/objects for database storage or job queues.
• Webhook integration: In Laravel, combine with routes/web.php or routes/console.php to parse uploaded .eml files via a controller:

  public function store(Request $request)
  {
      $email = (new Parser())->parse($request->file('eml')->get());
      DB::table('emails')->insert([
          'subject' => $email->subject,
          'from_email' => $email->from->email,
          'body_text' => $email->text,
          'body_html' => $email->html,
          'created_at' => now(),
      ]);
  }
  

• Attachment handling: Store or forward attachments programmatically:

  foreach ($email->attachments as $attachment) {
      Storage::put("attachments/{$email->message_id}/{$attachment->filename}", $attachment->content);
  }
  

• Laravel helpers: Optionally extend via macroable support to add custom parsing logic or integrate with domain models.

Gotchas and Tips

• MIME edge cases: Rare edge-case content types (e.g., text/calendar, multipart/related) may require fallback logic — always inspect $email->rawStructure when parsing fails silently.
• Encoding quirks: Non-UTF8 headers (e.g., iso-8859-1) are auto-decoded, but double-check $email->rawHeaders if subject/email addresses look garbled.
• Performance tip: For high-volume ingestion, reuse the parser instance ($parser = new Parser();) instead of instantiating per-message.
• Testing strategy: Use sample .eml fixtures (including multipart, empty attachments, and broken boundaries) in your unit tests — the package’s parsing is robust, but your fallback logic shouldn’t assume perfection.
• Extension point: You can extend Parser and override createMessage() to inject custom message classes for better type safety in your app.