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
- Sending an Email
- HTML Emails
- CC, BCC, and Reply-To
- Attachments
- Priority
- Testing the Configuration
- Provider Presets
- Troubleshooting
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']],
]);
| Key | Meaning |
|---|---|
path | Absolute 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. |
content | Raw bytes to attach instead of a path. |
name | The filename the recipient sees (defaults to the file’s name). Unicode names such as चलानी-१.pdf are encoded correctly. |
mime | Content type; detected from the file or its extension when omitted. |
$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
| Provider | Host | Port | Encryption | Notes |
|---|---|---|---|---|
| Gmail | smtp.gmail.com | 587 | TLS | Requires App Password (myaccount.google.com/apppasswords) |
| Outlook | smtp-mail.outlook.com | 587 | TLS | OAuth 2.0 required for most accounts |
| Yahoo | smtp.mail.yahoo.com | 465 | SSL | App Password under "External connections" |
| Custom | — | 587 | TLS | Any SMTP server |
Troubleshooting
- "SMTP host is not configured" — you haven't set the SMTP host in the Email tab or via
setSettings(). - "Connection failed" — check the host and port; ensure your server allows outbound connections on the chosen port.
- "SMTP error: 535" — username or password is wrong. For Gmail/Yahoo, use an App Password, not your regular password.
- Emails go to spam — set up SPF, DKIM, and DMARC DNS records for your sending domain.