README

Highlights

• setAddress() methods
• removeAddress() methods
• Set a default email domain
• Support multi-address add/set/remove methods
• addTO() synonym for addAddress()
• Advanced address parsing
• Original PHPMailer behavior is not disturbed; just enhanced

License

This software is distributed under the MIT License.

Installation & loading

PHPMailerQOL is available on Packagist (using semantic versioning), and installation via Composer is the recommended way to install PHPMailerQOL. Just add this line to your composer.json file:

"suny-upstate-cwt/phpmailerqol": "^1.0.0"

or run

composer require suny-upstate-cwt/phpmailerqol

Note that the vendor folder and the vendor/autoload.php script are generated by Composer; they are not part of PHPMailerQOL.

Adding and setting addresses

<?php
// Import PHPMailerQOL class into the global namespace
// These must be at the top of your script, not inside a function
use SUNYUpstateCWT\PHPMailerQOL\PHPMailerQOL;

// Load Composer's autoloader (created by composer, not included with PHPMailerQOL)
require 'vendor/autoload.php';

// Create an instance; passing `true` enables parent PHPMailer exceptions
$mail = new PHPMailerQOL(true);

try {
    // Server settings: see PHPMailer docs

    // Set default address domain
    // Append example.com when no domain is detected
    // Domain validation is not performed by PHPMailerQOL
    $mail->setDefaultAddressDomain('example.com');

    // Clear default domain
    // Pass in ANY "empty" or non-scalar value
    // $mail->setDefaultAddressDomain('');
    // $mail->setDefaultAddressDomain(null);
    // $mail->setDefaultAddressDomain([]);

    // Set FROM
    $mail->setFrom('no-reply', 'no-reply');    // Set From: no-reply <no-reply@example.com>

    // Add addresses
    $mail->addAddress([                        // Add TOs:
        'co-worker1'=>'John',                  //     John <co-worker1@example.com>
        'co-worker2'=>'Jim'                    //     Jim <co-worker2@example.com>
    ]);

    // Add addresses and vanity names in separate arrays
    $mail->addAddress([                        // Add TOs:
        ['email1', 'email2'],                  //     email1 <email1@example.com>
        ['Email1 Name', 'Email2 Name'],        //     email2 <email2@example.com>
    ]);

    // Remove previously added TOs and set anew
    $mail->setTO([                             // Set TO:
        'co-worker3',                          //    co-worker3@example.com
        'co-worker4',                          //    co-worker4@example.com
        'client1@otherdomain.com'              //    client1@otherdomain.com
    ]);

    // Add a CC
    $mail->addCC('Some Name <address>');             // This will FAIL; domain must be included
    $mail->addCC('Some Name <address@example.com>'); // Add CC: Some Name <address@example.com>

    // Juggle addresses
    $mail->JuggleAddressAdds = true;
    $mail->addAddress('co-worker3', 'myname');    // co-worker3@example.com is sent to the end of the TO list; with vanity name
    $mail->addBCC('client1@otherdomain.com');     // client1@otherdomain.com is moved to the BCC

    // Content
    $mail->isHTML(true);    //Set email format to HTML
    $mail->Subject = 'My subject';
    $mail->Body    = 'I am <b>bold!</b>';
    $mail->AltBody = 'I am bold!';
    
    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}

Removing addresses

$mail = new PHPMailerQOL(true);
$mail->setDefaultAddressDomain('example.com');

$mail->addAddress([
    'co-worker1'=>'John',
    'co-worker2'=>'Jim',
    'co-worker4'=>'Jack'
]);
$mail->addBCC('co-worker3');

$mail->removeAddress('co-worker1'); // Bye-bye co-worker1 from TOs
$mail->removeRecipient(['co-worker2','co-worker3@example.com']); // Bye-bye co-worker2 and 3 from TOs, CCs, and BCCs

$mail->Subject = 'My subject';
$mail->Body    = 'Some body';

$mail->send(); // Email sent to just co-worker4@example.com

Send individual emails

$mail = new PHPMailerQOL(true);
$mail->setDefaultAddressDomain('example.com');

$mail->Subject = 'My subject';
$mail->Body    = 'Some body';

// Everyone should get an individual email instead of cramming everyone into the BCC
foreach( $list_of_emails as $email ) {
    $mail->setTO($email);
    $mail->send();
}