InitPHP Mailer

A small, dependency-free PHP mailer. Compose a message with a fluent API and send it through PHP's native mail(), a local sendmail binary, or SMTP — with attachments, inline images, HTML + plain-text multipart bodies and RFC-compliant header encoding.

Upgrading from 1.x? Version 2.0 keeps the same fluent API but raises the PHP requirement, encapsulates state and replaces bool return values with exceptions. See UPGRADE-2.0.md.

Requirements

• PHP 8.1 or higher
• ext-mbstring, ext-iconv, ext-fileinfo

Installation

composer require initphp/mailer

Quick start

SMTP

use InitPHP\Mailer\Mailer;
use InitPHP\Mailer\Exception\MailerException;

$mailer = Mailer::newInstance([
    'protocol'   => 'smtp',
    'SMTPHost'   => 'smtp.example.com',
    'SMTPUser'   => '[email protected]',
    'SMTPPass'   => 'your-password',
    'SMTPPort'   => 587,
    'SMTPCrypto' => 'tls',
]);

try {
    $mailer->setFrom('[email protected]', 'Your Name')
        ->setTo('[email protected]')
        ->setSubject('Hello from InitPHP Mailer')
        ->setMessage('This is a plain-text message.')
        ->send();
} catch (MailerException $e) {
    // $e->getMessage(); for SMTP failures $e->getCode() holds the reply code.
}

Native mail()

$mailer = Mailer::newInstance(); // protocol defaults to "mail"

$mailer->setFrom('[email protected]', 'Your Name')
    ->setTo('[email protected]')
    ->setSubject('Hello')
    ->setMessage('Plain-text body')
    ->send();

HTML with a plain-text alternative

$mailer->setMailType('html')
    ->setFrom('[email protected]', 'Your Name')
    ->setTo('[email protected]')
    ->setSubject('Newsletter')
    ->setMessage('<h1>Hello</h1><p>This is an <strong>HTML</strong> message.</p>')
    ->setAltMessage('Hello — this is the plain-text fallback.')
    ->send();

Attachments and inline images

$mailer->setMailType('html')
    ->setFrom('[email protected]')
    ->setTo('[email protected]')
    ->setSubject('Invoice')
    ->attach('/path/to/invoice.pdf');             // a file on disk

// In-memory / generated content (no temp file needed):
$pdf = $generator->render();
$mailer->attachContent($pdf, 'invoice.pdf', 'attachment', 'application/pdf');

// Inline image referenced from the HTML with cid:
$mailer->attach('/path/to/logo.png', 'inline');
$cid = $mailer->setAttachmentCID('/path/to/logo.png');
$mailer->setMessage('<img src="cid:' . $cid . '"> Welcome!')
    ->send();

Error handling

send() returns void and throws on failure. Invalid input is rejected as soon as it is supplied (fail-fast), not deferred to send().

Exception	When
InvalidAddressException	A sender/recipient address fails validation.
ConfigurationException	A required value is missing (no sender, no recipient, empty SMTP host).
AttachmentException	An attachment cannot be read or its type detected.
TransportException	Delivery failed (the SMTP reply code is in getCode()).

All extend InitPHP\Mailer\Exception\MailerException, so a single catch can handle any failure.

Facade

For quick, one-off usage there is a static facade backed by a shared instance:

use InitPHP\Mailer\Facade\Mailer;

Mailer::setFrom('[email protected]')
    ->setTo('[email protected]')
    ->setSubject('Hi')
    ->setMessage('Body')
    ->send();

To configure the shared instance, build a Mailer and register it:

use InitPHP\Mailer\Mailer as MailerInstance;
use InitPHP\Mailer\Facade\Mailer;

Mailer::setInstance(MailerInstance::newInstance(['protocol' => 'smtp', /* … */]));

Documentation

Full developer documentation lives in docs/:

• Getting started
• Configuration
• Sending mail
• Attachments
• SMTP transport
• Encoding & headers
• Exceptions
• Facade

Contributing

Bug reports and pull requests are welcome on the issue tracker. New code should come with tests; run the full check bundle before opening a PR:

composer ci   # php-cs-fixer (dry-run) + phpstan + phpunit

Credits

• Muhammet ŞAFAK <[email protected]>

License

Released under the MIT License. Copyright © 2022 InitPHP.