<h1>Email API – <code>Email</code> Class</h1>
<p>
    The <strong>Email</strong> 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.
</p>

<h2>Contents</h2>
<ul>
    <li><a href="#configure">Configuring Email Settings</a></li>
    <li><a href="#send">Sending an Email</a></li>
    <li><a href="#html">HTML Emails</a></li>
    <li><a href="#cc-bcc">CC, BCC, and Reply-To</a></li>
    <li><a href="#attachments">Attachments</a></li>
    <li><a href="#priority">Priority</a></li>
    <li><a href="#test">Testing the Configuration</a></li>
    <li><a href="#presets">Provider Presets</a></li>
    <li><a href="#troubleshooting">Troubleshooting</a></li>
</ul>

<!-- =========================================== -->
<h2 id="configure">Configuring Email Settings</h2>
<p>
    Email settings are stored in the Misc module (Email tab) and saved into <code>project.json</code>.
    You can also set them programmatically:
</p>
<pre><code>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',
]);</code></pre>

<!-- =========================================== -->
<h2 id="send">Sending an Email</h2>
<pre><code>$result = Email::send([
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'body'    => 'Thank you for registering!',
]);

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

<!-- =========================================== -->
<h2 id="html">HTML Emails</h2>
<pre><code>$result = Email::send([
    'to'       => 'user@example.com',
    'subject'  => 'Your Order',
    'htmlbody' => '&lt;h1&gt;Order Confirmed&lt;/h1&gt;&lt;p&gt;Your order #1234 has been shipped.&lt;/p&gt;',
]);</code></pre>

<!-- =========================================== -->
<h2 id="cc-bcc">CC, BCC, and Reply-To</h2>
<pre><code>$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',
]);</code></pre>

<!-- =========================================== -->
<h2 id="attachments">Attachments</h2>
<pre><code>$result = Email::send([
    'to'          => 'user@example.com',
    'subject'     => 'Invoice',
    'body'        => 'Your invoice is attached.',
    'attachments' => [
        ['path' => '/tmp/invoice.pdf', 'name' => 'Invoice_May.pdf'],
        ['path' => '/tmp/receipt.png', 'name' => 'Receipt.png'],
    ],
]);</code></pre>

<!-- =========================================== -->
<h2 id="priority">Priority</h2>
<pre><code>$result = Email::send([
    'to'       => 'user@example.com',
    'subject'  => 'Urgent: Action Required',
    'body'     => 'Please respond immediately.',
    'priority' => 1,   // 1 = highest, 5 = lowest
]);</code></pre>

<!-- =========================================== -->
<h2 id="test">Testing the Configuration</h2>
<p>Use the <strong>Test Email</strong> button in the Misc module's Email tab, or programmatically:</p>
<pre><code>// 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'];</code></pre>

<!-- =========================================== -->
<h2 id="presets">Provider Presets</h2>
<table>
<tr><th>Provider</th><th>Host</th><th>Port</th><th>Encryption</th><th>Notes</th></tr>
<tr><td>Gmail</td><td>smtp.gmail.com</td><td>587</td><td>TLS</td><td>Requires App Password (myaccount.google.com/apppasswords)</td></tr>
<tr><td>Outlook</td><td>smtp-mail.outlook.com</td><td>587</td><td>TLS</td><td>OAuth 2.0 required for most accounts</td></tr>
<tr><td>Yahoo</td><td>smtp.mail.yahoo.com</td><td>465</td><td>SSL</td><td>App Password under "External connections"</td></tr>
<tr><td>Custom</td><td>—</td><td>587</td><td>TLS</td><td>Any SMTP server</td></tr>
</table>

<!-- =========================================== -->
<h2 id="troubleshooting">Troubleshooting</h2>
<ul>
    <li><strong>"SMTP host is not configured"</strong> — you haven't set the SMTP host in the Email tab or via <code>setSettings()</code>.</li>
    <li><strong>"Connection failed"</strong> — check the host and port; ensure your server allows outbound connections on the chosen port.</li>
    <li><strong>"SMTP error: 535"</strong> — username or password is wrong. For Gmail/Yahoo, use an App Password, not your regular password.</li>
    <li><strong>Emails go to spam</strong> — set up SPF, DKIM, and DMARC DNS records for your sending domain.</li>
</ul>

<hr>
<h3>🔗 Related Help Topics</h3>
<p>
    <a href="SMS" class="btn btn-sm btn-outline-primary me-1">SMS API</a>
    <a href="Notification" class="btn btn-sm btn-outline-primary me-1">Notification API</a>
    <a href="DB" class="btn btn-sm btn-outline-primary">Database API</a>
</p>