# POP SMTP — Installation Guide

Version 1.0.1 · Free software · GPL-2.0-or-later

POP SMTP configures SMTP delivery for WordPress emails, including WooCommerce order notifications. The plugin interface, notices and test message are in English.

## Requirements

- WordPress 6.2 or later and PHP 7.4 or later are the implementation targets. Use currently supported versions for your site.
- PHP OpenSSL for encrypted password storage and TLS connections.
- An SMTP account or trusted relay that supports STARTTLS or implicit TLS (SMTPS).
- Administrator access and permission for your web server to connect to the SMTP service.

WooCommerce is optional. POP SMTP works through WordPress's `wp_mail()` function. Services that send directly through external APIs may bypass it. The plugin does not read or modify WooCommerce order storage.

## 1. Install the plugin

1. Sign in to your WordPress dashboard as an administrator.
2. Open **Plugins → Add New Plugin → Upload Plugin**.
3. Select **pop-smtp-1.0.1.zip** and click **Install Now**.
4. Click **Activate Plugin**.
5. Open **Settings → POP SMTP**.

Deactivate other SMTP or mail-routing plugins before enabling POP SMTP to avoid competing settings.

## 2. Configure SMTP

| Setting | What to enter |
| --- | --- |
| SMTP delivery | Select **Enable SMTP** when the required settings are ready. |
| SMTP host | Your provider's hostname, such as `smtp.example.com`. Do not include `https://` or a port. |
| Port | Your provider's port, typically `587` for STARTTLS or `465` for SMTPS. |
| Encryption | Select **STARTTLS** or **TLS / SMTPS** as instructed by the provider. |
| SMTP authentication | Leave enabled unless your trusted SMTP relay explicitly does not require it. |
| Username | The SMTP username, often the complete email address. |
| Password | The SMTP password or application password specified by the provider. |
| Sender email address | An address the provider permits you to send from. This overrides the From address for all WordPress emails. |
| Sender name | Optional. Leave blank to preserve the sender name set by WooCommerce or other plugins. |

Click **Save settings**. Changing encryption does not automatically change the port; set both values according to your provider's instructions.

POP SMTP preserves email content, attachments and Reply-To addresses. It sets the envelope sender to the configured sender address; your provider may apply its own return-path rules.

## 3. Test delivery

1. Save your SMTP settings and enable SMTP delivery.
2. Under **Send a test email**, enter an address you can check.
3. Click **Send test email**.
4. Check both the inbox and spam folder.
5. For WooCommerce, place a test order and verify both customer and administrator messages. Check WooCommerce's own email settings if a notification is disabled.

The success notice means the send request completed without an error; it does not guarantee delivery to the inbox. Tests use saved settings. Wait 30 seconds between test requests.

## Password handling

- A saved password is never displayed in the page. Leave the password field blank to keep the current value.
- Enter a new password to replace it.
- **Delete the saved password** takes priority over a newly entered value. Disable SMTP delivery or authentication before deleting a required password.
- Database passwords are encrypted with AES-256-GCM using a key derived from the WordPress authentication salt. If this salt changes, enter the password again. Encryption does not protect a fully compromised server.

Administrators who prefer configuration-based credentials can add the following to `wp-config.php` **before WordPress is loaded**, replacing the example value:

```php
define( 'POP_SMTP_PASSWORD', 'your-smtp-password' );
```

This constant takes precedence over the database password. While it is defined, the password field cannot be edited in the settings page. Save settings once to remove a previously stored database password. The plugin never edits `wp-config.php`; remove or update the constant yourself. Escape PHP string characters correctly or use your hosting environment's secret management.

## Troubleshooting

- **Connection failed:** Check the host, port, encryption method and hosting provider's outbound SMTP restrictions.
- **Authentication failed:** Verify the username and SMTP/application password. OAuth-only accounts are not supported.
- **Certificate problem:** Use the provider's correct hostname and a valid TLS certificate. Certificate checks cannot be disabled in this plugin.
- **Password stopped working after migration:** Re-enter it if the WordPress authentication salt changed.
- **Test succeeds but no message arrives:** Check spam, provider delivery records and sender verification. Configure SPF and DKIM according to your provider's documentation.
- **Order email is missing:** Verify the relevant notification and recipient in WooCommerce, then test a real order workflow in staging.
- **Need to return to default delivery:** Clear **Enable SMTP** and save, or deactivate POP SMTP.

## Scope and privacy

POP SMTP sends outgoing messages and credentials to your configured SMTP server over TLS. It includes no analytics, advertising, paid features, developer telemetry or message logs. Short-lived administrative notices and test cooldown records may be stored for up to 60 seconds; expired records can remain until WordPress cleans them up.

OAuth 2.0, email queues, automatic retries, plaintext SMTP and IPv6 address literals are outside this version's scope. Despite its name, POP SMTP does not retrieve mail using POP3.

Multisite settings are configured separately for each site. Deactivation keeps settings. Deleting the plugin removes database settings across the network, including encrypted passwords. Configuration-file constants remain untouched.

## Distribution

You may use, modify and redistribute POP SMTP under GPL-2.0-or-later. Keep the license and source code with the distribution, and identify changes and their dates in modified versions. See `LICENSE.txt` for the full terms. The plugin is provided without warranty.

The ZIP is suitable for direct distribution and WordPress upload. No WordPress.org listing has been submitted. Before a public directory submission, supply your own maintainer/support information, check name availability, and perform staging validation. POP SMTP is independent and is not endorsed by WooCommerce.

## Official references

- [WordPress SMTP initialization hook](https://developer.wordpress.org/reference/hooks/phpmailer_init/)
- [WordPress mail return values and delivery behavior](https://developer.wordpress.org/reference/functions/wp_mail/)
- [WordPress plugin license guidance](https://developer.wordpress.org/plugins/plugin-basics/including-a-software-license/)
