Building Email Systems 📧

<?php
// The OLD way: PHP's built-in mail() function.
// It hands your message to the server's local "sendmail" program.
// It looks simple, but it is the #1 reason emails land in spam.

$to      = "alice@example.com";
$subject = "Welcome!";
$body    = "Thanks for signing up.";
$headers = "From: noreply@yoursite.com\r\n";

// mail() returns true only if the message was HANDED OFF locally —
// NOT if it was actually delivered. There is no authentication,
// no encryption, and no error detail. That is the whole problem.
if (mail($to, $subject, $body, $headers)) {
    echo "Handed to the local mail system (delivery NOT guaranteed).\n";
} else {
    echo "mail() failed.\n";
}
?>

Handed to the local mail system (delivery NOT guaranteed).

<?php
// The RIGHT way: PHPMailer talks SMTP directly to a real mail server,
// with a username/password (auth) and TLS (encryption).
// Install once:  composer require phpmailer/phpmailer

require __DIR__ . "/vendor/autoload.php";        // Composer's autoloader

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

$mail = new PHPMailer(true);   // true = throw an Exception when something fails

try {
    // 1) Connect to an AUTHENTICATED, ENCRYPTED SMTP server.
    $mail->isSMTP();                                      // use SMTP, not mail()
    $mail->Host       = "smtp.sendgrid.net";             // your provider's host
    $mail->SMTPAuth   = true;                            // turn on login
    $mail->Username   = "apikey";                        // provider username
    $mail->Password   = getenv("SMTP_PASSWORD");         // 👈 from the environment
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;  // upgrade to TLS
    $mail->Port       = 587;                             // 587 = submission + STARTTLS

    // 2) Who it's from and who it's going to.
    $mail->setFrom("hello@yoursite.com", "Your App");
    $mail->addAddress("alice@example.com", "Alice");     // call again for more

    // 3) Send BOTH an HTML version and a plain-text fallback.
    $mail->isHTML(true);
    $mail->Subject = "Welcome to Your App";
    $mail->Body    = "<h1>Welcome!</h1><p>We're glad you're here.</p>";
    $mail->AltBody = "Welcome! We're glad you're here.";  // shown if HTML is blocked

    $mail->send();
    echo "Email sent.\n";        // only printed if delivery to SMTP succeeded
} catch (Exception $e) {
    // ALWAYS handle the failure — log it, don't crash the request.
    echo "Email NOT sent: {$mail->ErrorInfo}\n";
}
?>

Email sent.

<?php
require __DIR__ . "/vendor/autoload.php";
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host       = "smtp.sendgrid.net";
$mail->SMTPAuth   = true;
$mail->Username   = "apikey";
$mail->Password   = getenv("SMTP_PASSWORD");
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port       = 587;

$mail->setFrom("billing@yoursite.com", "Billing");
$mail->addAddress("alice@example.com");
$mail->addCC("manager@yoursite.com");        // visible copy
$mail->addBCC("audit@yoursite.com");         // hidden copy

$mail->isHTML(true);
$mail->Subject = "Your invoice #1001";
$mail->Body    = "<p>Your invoice is attached.</p>";
$mail->AltBody = "Your invoice is attached.";

// Attach a file from disk — give it a clean name the recipient will see.
$mail->addAttachment("/var/invoices/1001.pdf", "invoice-1001.pdf");

try {
    $mail->send();
    echo "Invoice emailed with attachment.\n";
} catch (Exception $e) {
    echo "Failed: {$mail->ErrorInfo}\n";
}
?>

Invoice emailed with attachment.

<?php
// Sending email is SLOW (an SMTP round-trip is ~1–3 seconds). If you do it
// during the web request, the user stares at a spinner. Instead, QUEUE it:
// save the job now (fast), and let a separate worker send it later.

// --- During the web request: just enqueue and return immediately ---
function queueEmail(PDO $db, string $to, string $subject, string $body): void {
    $stmt = $db->prepare(
        "INSERT INTO email_queue (recipient, subject, body, status)
         VALUES (?, ?, ?, 'pending')"
    );
    $stmt->execute([$to, $subject, $body]);   // a quick DB write, not an SMTP call
}

// Sign up 1,000 users to a newsletter without blocking anyone:
$recipients = ["a@example.com", "b@example.com", "c@example.com"]; // ...1000 of them
foreach ($recipients as $email) {
    queueEmail($db, $email, "Our newsletter", "<p>Hello!</p>");
}
echo "Queued " . count($recipients) . " emails. Request done.\n";

// --- A separate worker (php worker.php, run on a schedule) does the sending ---
// while ($job = fetchNextPending($db)) {
//     sendWithPHPMailer($job);              // the slow part runs in the background
//     markSent($db, $job['id']);
// }
?>

Queued 3 emails. Request done.

<?php
// 🎯 YOUR TURN — finish the SMTP setup so the email can authenticate.
require __DIR__ . "/vendor/autoload.php";
use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = "smtp.sendgrid.net";

// 1) Turn ON SMTP authentication (the server requires a login):
$mail->SMTPAuth = ___;          // 👉 use the boolean  true

// 2) Read the password from the environment, NEVER hardcode it:
$mail->Password = ___;          // 👉 getenv("SMTP_PASSWORD")

// 3) Use the standard submission port for STARTTLS:
$mail->Port = ___;              // 👉 the number 587

echo "Auth: " . ($mail->SMTPAuth ? "on" : "off") . ", port " . $mail->Port . "\n";

// ✅ Expected output:
//    Auth: on, port 587
?>

Auth: on, port 587

<?php
// 🎯 YOUR TURN — give this HTML email a plain-text fallback.
// Some clients (and spam filters) reject HTML-only mail, so ALWAYS set AltBody.
require __DIR__ . "/vendor/autoload.php";
use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isHTML(true);
$mail->Subject = "Order confirmed";
$mail->Body    = "<h1>Order confirmed</h1><p>Thank you!</p>";

// Add a plain-text version of the same message:
$mail->AltBody = ___;     // 👉 "Order confirmed. Thank you!"

echo "HTML body set, plain-text fallback: " . $mail->AltBody . "\n";

// ✅ Expected output:
//    HTML body set, plain-text fallback: Order confirmed. Thank you!
?>

HTML body set, plain-text fallback: Order confirmed. Thank you!