hitraa/openforge-mailer

Lightweight PHP SMTP Mailer with HTML, attachments, tracking pixel, and read receipt support.

v1.0.0 2025-06-15 14:42 UTC

Requires

• php: >=8.2

MIT

• Harshal Khairnar

• mail
• mailer
• php
• email
• html
• smtp
• tracking
• openforge

README

A lightweight, dependency-free PHP SMTP Mailer with support for:

• 📤 Sending plain text and HTML emails
• 📎 Attachments
• 👁️‍🗨️ Tracking pixel (read/open tracking)
• ✅ SMTP-level read receipt requests (RCPT NOTIFY)
• 🛡️ TLS / SSL / STARTTLS support
• 🛠️ Fallback to native mail() on failure
• 🐞 Debug mode for troubleshooting

🚀 Features

• ✅ Simple API, single class
• 📦 No external dependencies
• 💬 Rich content: Plain text & HTML
• 📎 Attach multiple files
• 🔒 Secure with SSL, TLS, or STARTTLS
• 👁️ Tracking pixel integration with your server
• 📨 Read receipt notification via SMTP RCPT TO NOTIFY
• ⛑️ Fallback to native mail() if SMTP fails (optional)
• 🧪 Debug output for SMTP commands

📘 Example Use Cases

• ✅ Transactional email sending (invoices, alerts)
• 📢 Email marketing campaigns (with tracking)
• 📩 Application-based notifications
• 🧪 Development/testing mail delivery
• 👁️ Track when an important email is read

📦 Installation

Copy the Mailer.php file to your project.

Alternatively, if you're using Composer:

composer require hitraa/openforge-mailer

📁 Directory Structure

openforge-mailer/
├── src/
│   └── Mailer.php
├── examples/
│   ├── basic-send.php
│   └── track.php
├── composer.json
├── LICENSE
└── README.md

🚀 Usage

1. Basic email

require_once 'vendor/autoload.php';

use OpenForge\Mailer\Mailer;

$mail = new Mailer('smtp.yourhost.com', '[e-mail]', 'password');

$mail->setFrom('Your Name <[e-mail]>')
     ->setRecipient('[e-mail]')
     ->setSubject('Hello!')
     ->setBody('This is the plain-text version.')
     ->setHTMLBody('<h1>Hello!</h1><p>This is the HTML version.</p>');

echo $mail->send();

2. With attachments

$mail->setAttachment('/path/to/file.pdf');

3. With tracking pixel

$mail->enableTrackingPixel('https://yourdomain.com/track.php');

Your endpoint should log or store open events using query params like ?message_id=...&email=...

4. SMTP read receipt (SMTP DSN) behavior

Enabling read receipts:

$mail->requestReadReceipt(true);

This adds NOTIFY=SUCCESS,FAILURE,DELAY in RCPT TO, and the recipient's mail server will notify (if supported).

Also adds optional headers:

• Disposition-Notification-To
• Return-Receipt-To
• X-Confirm-Reading-To

Note: Behavior depends on recipient's server & client.

5. Fallback to PHP mail() if SMTP fails

$mail->allowFallbackToMail(true);

6. With custom message id prefix

$mail->setMessageIdPrefix('track-');

7. With multiple recipients

$mail->setRecipient(['[e-mail]', '[e-mail]']);

Parse RFC email formats

Supports:

• Name <[e-mail]>
• "Name" <[e-mail]>
• [e-mail]

🐞 Debugging

Enable SMTP-level debug messages:

$mail->enableDebug(true);

This will print the SMTP command flow.

📂 Example File

• 📄 examples/basic-send.php — Full example with HTML, text, attachment.
• 📄 examples/track.php — Tracking pixel handler.

🔐 SMTP Security Options

Default port	Option	Description	Mailer constant
587	tls	Default (STARTTLS)	Mailer::SECURE_TLS
465	ssl	SSL connection	Mailer::SECURE_SSL
587	starttls	Explicit STARTTLS	Mailer::SECURE_STARTTLS

🛡 License

Released under the MIT License

👨‍💻 Author

Made with ❤️ by Harshal Khairnar Founder, Hitraa Technologies 📧 [e-mail]

🤝 Contributions

Feel free to fork and submit pull requests. All improvements are welcome!

⚠️ Disclaimer

This library is designed for educational and production-ready purposes. Use responsibly when tracking user interactions.