PPPHP

Email API – Email Class

The Email class sends emails via SMTP using app passwords or custom credentials. Provider presets for Gmail, Outlook, Yahoo, and Custom SMTP are built in. All sending is done through raw PHP sockets — zero external dependencies.

Contents

Configuring Email Settings

Email settings are stored in the Misc module (Email tab) and saved into project.json. You can also set them programmatically:

use PpPhp\Core\Email;

Email::setSettings([
    'provider'    => 'gmail',
    'host'        => 'smtp.gmail.com',
    'port'        => 587,
    'encryption'  => 'tls',
    'username'    => 'you@gmail.com',
    'password'    => 'your-16-char-app-password',
    'fromAddress' => 'you@gmail.com',
    'fromName'    => 'Your App',
]);

Sending an Email

$result = Email::send([
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'body'    => 'Thank you for registering!',
]);

if ($result['mailed']) {
    echo 'Sent!';
} else {
    echo 'Error: ' . $result['message'];
}

HTML Emails

$result = Email::send([
    'to'       => 'user@example.com',
    'subject'  => 'Your Order',
    'htmlbody' => '<h1>Order Confirmed</h1><p>Your order #1234 has been shipped.</p>',
]);

CC, BCC, and Reply-To

$result = Email::send([
    'to'      => 'user@example.com',
    'subject' => 'Project Update',
    'body'    => 'Here is the latest update...',
    'cc'      => 'manager@example.com',
    'bcc'     => 'archive@example.com',
    'replyTo' => 'support@example.com',
]);

Attachments

Attach files by path (a file your code already has on disk) or by content (bytes you already have in memory, such as a PDF you just generated). Both forms can be mixed in one list:

$result = Email::send([
    'to'          => 'user@example.com',
    'subject'     => 'Invoice',
    'body'        => 'Your invoice is attached.',
    'htmlbody'    => '<p>Your invoice is <b>attached</b>.</p>',   // optional: text + HTML alternative
    'attachments' => [
        $csvFile,                                                           // a plain path (a file you created)
        ['path' => $receiptFile, 'name' => 'Receipt.png'],                  // …with a friendly file name
        ['content' => $pdfBytes, 'name' => 'Invoice-42.pdf', 'mime' => 'application/pdf'],
    ],
]);

Emailing a generated PDF — render it in memory and attach the bytes; nothing is written to disk:

$pdf = \PpPhp\Core\PdfService::fromHtml($html, ['paper' => 'A4']);
Email::send([
    'to'          => $customer['email'],
    'subject'     => 'Invoice ' . $invoice['number'],
    'body'        => 'Please find your invoice attached.',
    'attachments' => [['content' => $pdf, 'name' => 'Invoice-' . $invoice['number'] . '.pdf']],
]);
KeyMeaning
pathAbsolute path of a readable file inside the application. Paths outside it (e.g. /tmp) are refused — copy such files into storage/ first, or pass content.
contentRaw bytes to attach instead of a path.
nameThe filename the recipient sees (defaults to the file’s name). Unicode names such as चलानी-१.pdf are encoded correctly.
mimeContent type; detected from the file or its extension when omitted.
A missing, unreadable or out-of-app attachment fails the whole send with a clear message ($result['mailed'] === false) before any server is contacted — an email never goes out without its file. Filenames are sanitised, so user-supplied names cannot inject headers.

In generated apps the author helper forwards extra keys, so attachments work there too:

pp_send_email($to, 'Statement', 'Your statement is attached.', [
    'attachments' => [['content' => $pdf, 'name' => 'Statement.pdf']],
]);

Need to see the exact message that would be sent (for a preview or a test)? Email::compose($params) returns the full MIME message without connecting to any server.

Priority

$result = Email::send([
    'to'       => 'user@example.com',
    'subject'  => 'Urgent: Action Required',
    'body'     => 'Please respond immediately.',
    'priority' => 1,   // 1 = highest, 5 = lowest
]);

Testing the Configuration

Use the Test Email button in the Misc module's Email tab, or programmatically:

// Send a quick test
$result = Email::send([
    'to'      => 'you@gmail.com',
    'subject' => 'Test from pp-php',
    'body'    => 'Your email configuration is working!',
]);

echo $result['mailed'] ? 'OK' : $result['message'];

Provider Presets

ProviderHostPortEncryptionNotes
Gmailsmtp.gmail.com587TLSRequires App Password (myaccount.google.com/apppasswords)
Outlooksmtp-mail.outlook.com587TLSOAuth 2.0 required for most accounts
Yahoosmtp.mail.yahoo.com465SSLApp Password under "External connections"
Custom—587TLSAny SMTP server

Troubleshooting


🔗 Related Help Topics

SMS API Notification API Database API