# Gmail delivery for SLPS

SLPS uses Gmail SMTP for student verification and HOD account emails. Internal chat stays inside SLPS and does not depend on email delivery.

## 1. Prepare a Gmail sender account

Use a dedicated university sender mailbox where possible. Turn on Google Account 2-Step Verification, then create an App Password for SLPS. Google requires 2-Step Verification for App Passwords and notes that some managed or Advanced Protection accounts may not offer them. If the university uses Google Workspace, ask its administrator whether App Passwords are allowed.

Google currently supports `smtp.gmail.com` with port `587` and STARTTLS, or port `465` with SSL. This project is set up for port `587` with STARTTLS.

## 2. Install the mail library

From the SLPS project root on the production server, run:

```bash
composer install --no-dev --optimize-autoloader
```

The repository's `composer.json` already requires PHPMailer. Keep the resulting `vendor` directory available to PHP in production.

## 3. Configure the sender

For production, configure these in the PHP/Apache hosting environment or the container's private environment settings. Do not put the real App Password into Git or a web-accessible `.env` file.

```text
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_ENCRYPTION=tls
SMTP_USERNAME=your-university-sender@gmail.com
SMTP_PASSWORD=your-16-character-app-password
AUTH_MAIL_FROM=your-university-sender@gmail.com
SMTP_FROM_NAME=Rockview University SLPS
APP_URL=https://your-real-university-domain
APP_BASE_PATH=/slps
```

Set `APP_BASE_PATH` to the actual URL path where SLPS is installed. If the app is hosted at the domain root, use an empty value only if the hosting environment supports empty variables; otherwise adjust the app's path configuration to `/`.

For Docker, add the values to the deployment's protected environment configuration and recreate/restart the PHP container. For Apache with PHP-FPM, add them to the PHP-FPM pool or the hosting control panel's PHP environment configuration and restart PHP-FPM. Do not expose the App Password through `phpinfo()`, a diagnostics page, or application logs.

For local XAMPP testing, open `authentication/api/emailsetup.php` and replace the `username` and `password` fallback values with your Gmail address and App Password. That folder contains an `.htaccess` rule to block browser requests to the setup and helper files, and the PHP files reject direct requests too. Keep real credentials out of Git and remove them before sharing the project ZIP. `APP_URL` defaults to `http://localhost`; the app derives its path from the URL, normally `/slps`.

## 4. Send a test email

After setting the variables and restarting PHP, register a test student with an email address you control. SLPS should return a successful account-created message and deliver the verification email. You can also create a test HOD from the management panel and confirm the account email arrives. Check the recipient's Spam folder.

If delivery fails, check the PHP error log for `SLPS SMTP delivery failed` and confirm:

- PHPMailer is installed under the project or its parent `vendor` directory.
- The SMTP username and `AUTH_MAIL_FROM` are the same Gmail address.
- The SMTP password is the App Password, with spaces removed.
- Port 587 outbound connections are allowed by the host firewall.
- The mailbox has 2-Step Verification enabled and the App Password has not been revoked.
- The hosting platform has restarted PHP after the environment values were changed.

Do not switch off TLS to work around a connection error. Ask the hosting provider to permit outbound SMTP or use its supported authenticated relay.

## 5. Rotate a compromised App Password

Revoke the App Password in Google Account settings, create a replacement, update the server secret, and restart the PHP service. Google revokes App Passwords after a Google Account password change.

References: [Google App Passwords](https://support.google.com/accounts/answer/185833) · [Google 2-Step Verification](https://support.google.com/accounts/answer/185839) · [Gmail SMTP server and ports](https://support.google.com/mail/thread/273918292/smtp-and-port-number)
