=== Tempmails ===
Contributors: neosmartapps,neoparker007
Tags: temporary email, disposable email, IMAP, email privacy, temp mails
Requires at least: 5.8
Tested up to: 6.9
Stable tag: 1.0.7
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Donate link: https://paypal.me/growmify

White-label temporary email platform. Let visitors generate disposable
inboxes on your site — powered by your own IMAP server.

== Description ==

> **Self-hosted. Privacy-first. Fully yours.**

Tempmails turns your WordPress site into a **self-hosted temporary email
service**. Visitors generate a random disposable email address, receive
messages in a real-time inbox, and discard them when done — all without
leaving your site.

Unlike third-party services, Tempmails runs entirely on **your own server
and IMAP mailbox**. You own the data, the domain, and the brand.

---

🔒 **No third-party email APIs**
📬 **Real IMAP inbox — not a simulation**
🎨 **Material Design 3 UI — beautiful out of the box**
⚡ **AJAX-powered — no page reloads**

---

= 🚀 Quick Links =

Everything you need to get started, get help, and stay connected:

* 🌐 **Official Website** — [tempmails.cv](https://tempmails.cv/) — docs,
  roadmap, and addon announcements
* 🎬 **Installation Tutorial** — Watch the step-by-step video guide below
* 📺 **YouTube Channel** — [NeoSmartApps on YouTube](https://www.youtube.com/@NeoSmartApps101)
  — tutorials, walkthroughs, and new release demos
* ☕ **Support the Project** — [Buy us a coffee via PayPal](https://paypal.me/growmify)
  — Tempmails is free forever; your support keeps development alive
* 🖥️ **Need Hosting?** — Tempmails works best on a VPS or shared host with
  catch-all IMAP support. We recommend [Hostinger](https://www.hostinger.com/in?REFERRALCODE=neoparker)
  *(affiliate link — we earn a small commission at no extra cost to you)*

= 🎬 Watch: Full Installation Tutorial =

https://youtu.be/8SKRdyEUrog?si=KHfUT0KicbYphO1M

---

= Core Features =

**📨 Email Engine**

* IMAP Email Fetching — connects to any catch-all IMAP mailbox
* Auto Email Generation — random disposable addresses on your own domains
* Real-time Inbox — AJAX-powered message viewer with configurable
  auto-refresh
* Attachment Support — download files with 40+ allowed extensions

**🎨 Design & UI**

* Material Design 3 UI — modern, responsive inbox with Inter & Poppins fonts
* White-labeled — fully rebrandable, no third-party branding in the UI
* Design Panel — live color picker and label customization in admin

**🛡️ Privacy & Data**

* Soft Delete — messages are never hard-deleted; safe for compliance
* Cookie-based sessions — no user accounts or registration required
* Zero external data transmission — all data stays on your server

**⚙️ WordPress Native**

* Uses WP database, cron, options, nonces, and security APIs throughout
* Settings API compliant admin panel
* Full i18n/l10n support with `.pot` file included

= Shortcode =

Place the inbox anywhere on your site with one shortcode:

`[tempmails_inbox]`

This renders the full inbox UI — email generation, copy button,
auto-refresh, message list, and message viewer modal.

= Addon Ecosystem =

Tempmails Core is **frozen infrastructure**. All new functionality is
delivered via addons using a documented, stable hook system — your site
never breaks on Core updates.

Available addon hooks cover: email generation, message routing, inbox
access control, multi-domain support, billing integration, and more.
See the **Hooks** section below for the full reference.

= Privacy =

Tempmails stores temporary email addresses in **browser cookies** to
maintain inbox sessions between page loads. No personal data is collected,
stored against user accounts, or transmitted to any external service.
See **External Services** below for details on the optional GitHub
ecosystem feed.

---

== Installation ==

= Minimum Requirements =

* WordPress 5.8 or higher
* PHP 7.4 or higher
* PHP extensions: `imap`, `mbstring`, `json`
* A mail server with catch-all forwarding configured on your domain

= Step-by-Step Installation =

1. Upload the `tempmails` folder to `/wp-content/plugins/` or install via
   **Plugins → Add New → Upload Plugin**
2. Activate the plugin through **Plugins → Installed Plugins**
3. Go to **Tempmails → Settings → IMAP** and enter your mail server
   credentials:
   * **Host:** `mail.yourdomain.com`
   * **Port:** `993` (SSL) or `143` (TLS)
   * **Encryption:** SSL or TLS
   * **Username:** `catch-all@yourdomain.com`
   * **Password:** your IMAP mailbox password
4. Click **Test Connection** to verify the credentials
5. Click **Save Settings**
6. Create a new WordPress page and add `[tempmails_inbox]`
7. Publish — visitors can now generate and use temporary email addresses
   instantly

= IMAP Catch-All Setup =

Your mail server must have **catch-all email enabled** so that messages
sent to any address `@yourdomain.com` land in the single mailbox
Tempmails reads from.

In cPanel, set the Default Address for your domain to deliver to your
catch-all inbox:

`*@yourdomain.com → catch-all@yourdomain.com`

Hostinger users: enable catch-all under **hPanel → Email → Default
Address**. New to Hostinger? [Get started here](https://www.hostinger.com/in?REFERRALCODE=neoparker)
*(affiliate link)* — their hPanel makes IMAP catch-all setup
straightforward even for beginners.

= Server Cron (Recommended for Reliable Fetching) =

WordPress cron only fires when your site receives traffic. For consistent
email delivery, add a real server cron job in cPanel → Cron Jobs:

`* * * * * wget -q -O - https://yoursite.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1`

Or using WP-CLI:

`* * * * * cd /path/to/wordpress && wp cron event run --due-now >/dev/null 2>&1`

---

== Frequently Asked Questions ==

= Does this plugin require a third-party email service? =

No. Tempmails connects directly to your own IMAP mailbox. You need a mail
server with catch-all forwarding — Hostinger, any cPanel-based host, or
any standard IMAP server works.

= What PHP extensions are required? =

The `imap`, `mbstring`, and `json` extensions must be enabled on your
server. Most shared hosting providers include these by default. The plugin
will display a clear error and refuse to activate if any are missing.

= Can I use my own domain names for generated addresses? =

Yes. Go to **Tempmails → Settings → Domains** and add one domain per line.
All listed domains must route their catch-all to your IMAP mailbox.

= How is message deletion handled? =

Tempmails uses **soft delete**. When a user deletes a message, the
`to_address` field is changed to an internal tombstone value rather than
removing the database row. Deleted messages never appear in inbox queries.
This behavior is permanent and guaranteed across all versions.

= Can I white-label the inbox UI? =

Yes. All user-facing text is translation-ready and overridable via filters.
The **Design Panel** under **Tempmails → Design** lets you change colors,
button labels, empty state text, and border radius — with a live preview.

= How do I build an addon? =

Register your addon using the `tempmails_registered_addons` filter, then
hook into any documented action or filter. Core is frozen — all new
functionality must be delivered via addons. See the **Hooks** section for
the full reference.

= Emails are not appearing in the inbox =

1. Go to **Tempmails → Settings → IMAP** and click **Test Connection**
2. Verify catch-all forwarding is active on your mail server
3. Confirm WordPress cron is running — use the free **WP Crontrol** plugin
   to inspect scheduled events
4. Check **Tempmails → Addon Health** for any logged errors

= How do I enable debug logging? =

Add these two lines to `wp-config.php`:

`define('WP_DEBUG', true);`
`define('WP_DEBUG_LOG', true);`

Tempmails logs all errors to the standard WordPress debug log at
`/wp-content/debug.log` and to the **Addon Health** page in admin.

---

== Screenshots ==

1. Frontend inbox — email generation, copy button, and real-time message
   list
2. Message modal — full email content with attachment download support
3. Admin dashboard — statistics cards, IMAP status, and quick action
   buttons
4. Settings — General tab with fetch interval and retention controls
5. Settings — IMAP tab with connection credentials and live test button
6. Design panel — live preview with color pickers and label customization
7. Addon Health page — per-addon error log and hook status

---

== Hooks ==

Tempmails exposes a complete hook system for addon developers. All hooks
below are **stable and frozen** — they will not be renamed, removed, or
have their signatures changed in any minor version.

= Action Hooks =

* `tempmails_loaded` — Core fully initialized; safe for addon bootstrap
* `tempmails_core_ready` — fires after DB integrity check; passes Core
  version string
* `tempmails_activated` — fires on plugin activation; safe for addon setup
* `tempmails_deactivated` — fires on plugin deactivation
* `tempmails_email_generated` — new address generated; params: `$email`,
  `$ip`
* `tempmails_inbox_accessed` — user opened inbox; params: `$email`, `$ip`
* `tempmails_message_received` — new message stored; params: `$message_id`,
  `$to_address`
* `tempmails_message_marked_seen` — message read; params: `$message_id`
* `tempmails_message_deleted` — soft delete triggered; params: `$message_id`,
  `$email`
* `tempmails_cleanup_completed` — cron cleanup finished; params:
  `$deleted_count`
* `tempmails_fetch_completed` — fetch cycle finished; params: `$results`
  array

= Filter Hooks =

* `tempmails_registered_addons` — register your addon for the Addons admin
  page
* `tempmails_generated_email` — modify a generated address before returning
  it
* `tempmails_available_domains` — modify the domain list available for
  generation
* `tempmails_can_fetch_messages` — allow/block a fetch cycle; params:
  `$bool`, `$engine`
* `tempmails_can_process_message` — allow/block a single message; params:
  `$bool`, `$message`
* `tempmails_can_store_message` — allow/block DB insert; params: `$bool`,
  `$data`
* `tempmails_can_read_inbox` — allow/block inbox access; params: `$bool`,
  `$email`
* `tempmails_message_content` — filter body before display; params:
  `$content`, `$message_id`
* `tempmails_default_settings` — modify default option values on activation
* `tempmails_inbox_attributes` — modify shortcode default attributes
* `tempmails_admin_dashboard_stats` — extend dashboard stat cards
* `tempmails_settings_tabs` — add custom tabs to the Settings page

---

== External Services ==

= Ecosystem Feed (Optional — Default On) =

Tempmails fetches a public JSON file from GitHub to display addon and
ecosystem information inside the WordPress admin panel.

**What this connection does:**

* Fires only when viewing Tempmails admin pages
* Retrieves only public, non-personal JSON content
* Transmits no user data, site URL, or any identifiable information
* Results are cached locally for 1 hour to minimize requests

Remote endpoint:
https://raw.githubusercontent.com/ubermensch-site/tempmails-ecosystem/main/ecosystem.json

Service provider: GitHub
Privacy policy: https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement

To **disable this connection entirely**, uncheck **Ecosystem Feed** under
**Tempmails → Settings → General**. Hardcoded fallback content is shown
instead — no requests are made.

= Google Fonts =

The frontend inbox loads the **Inter** and **Poppins** typefaces and the
**Material Symbols** icon font from Google Fonts CDN.

**What this connection does:**

* Fires only on pages where `[tempmails_inbox]` is rendered
* Transmits the visitor's IP address to Google as part of a standard font
  request

Service provider: Google Fonts
Privacy policy: https://developers.google.com/fonts/faq/privacy

To avoid this (e.g. for GDPR compliance), dequeue `tempmails-google-fonts`
and load self-hosted font copies instead.

---

== Changelog ==

= 1.0.7 - 2026-04-04 (Security Patch) =
* Security: ajax_delete_message() — $_POST['message_id'] now wrapped with
  sanitize_text_field( wp_unslash() ); phpcs:ignore suppression comment
  removed

= 1.0.7 - 2026-04-02 (Security Patch) =
* Security: Removed raw `<style>` echo in Design admin page — static CSS
  moved to assets/css/admin.css
* Security: inject_css_variables() now uses wp_add_inline_style() instead
  of echo; all CSS custom property values wrapped with esc_attr()
* Security: inject_frontend_css_variables() now escapes all CSS values with
  esc_attr() and passes the CSS string through wp_strip_all_tags() before
  calling wp_add_inline_style()
* Security: wp_footer fallback in inject_frontend_css_variables() replaced
  raw `<style>` echo with a registered dummy style handle using
  wp_register_style() + wp_add_inline_style() — no more unescaped output
* Security: Inline `<script>` in shortcode output replaced with
  wp_add_inline_script('tempmails-frontend', ...)
* Security: Inline `<script>` in ecosystem admin block replaced with
  wp_add_inline_script('tempmails-admin', ...)
* Security: ajax_mark_seen() — $_POST['message_id'] now wrapped with
  sanitize_text_field() in addition to wp_unslash()
* Security: save_settings() — raw $_POST no longer passed directly to
  do_action(); sanitized via array_map('sanitize_text_field',
  wp_unslash($_POST)) before reaching tempmails_before_save_settings and
  tempmails_before_save_imap_settings hooks
* Security: get_emails() in Email Generator — cookie emails now sanitized
  with array_filter(array_map('sanitize_email', $raw)) after
  maybe_unserialize()

= 1.0.7 - 2026-03-15 =
* Fixed: IMAP fetch now uses imap_search('UNSEEN') instead of last-N
  sequence range — stops the infinite re-fetch loop
* Fixed: Added synthetic Message-ID generation (synthetic-{md5}) for emails
  with no Message-ID header
* Fixed: Added Delivered-To / X-Original-To / X-Forwarded-To raw header
  fallback when To: addresses cannot be parsed
* Fixed: Added last-resort raw body fallback with FT_PEEK for complex MIME
  structures
* Changed: Renamed "Messages Received" dashboard stat card label to
  "All-Time Received"

= 1.0.7 - 2026-03-07 =
* Fixed: All action hooks now fully integrated into Core
* Fixed: `tempmails_email_generated` fires correctly on every email creation
* Fixed: `tempmails_inbox_accessed` fires on every inbox view
* Fixed: `tempmails_message_received` fires when a new message is stored
* Fixed: `tempmails_message_marked_seen` fires correctly on message read
* Fixed: `tempmails_message_deleted` now correctly passes `$email` parameter
* Fixed: `tempmails_cleanup_completed` now passes deleted message count
* Fixed: Admin JS (`admin.js`) now correctly enqueued on all Tempmails
  admin pages
* Fixed: Dashboard stats now increment correctly
* Added: Ecosystem Feed opt-out toggle in Settings → General

= 1.0.6 - 2026-01-05 =
* Fixed: Modal z-index conflicts with some themes
* Fixed: Message list rendering in certain theme layouts
* Fixed: Attachment download failing for some file types
* Changed: Improved CSS specificity for modal overlay
* Changed: Enhanced frontend.css for broader theme compatibility

= 1.0.5 - 2026-01-04 =
* Added: Material Design 3 UI components
* Added: Inter and Poppins font integration
* Added: Material Symbols icon library
* Fixed: Frontend styling conflicts with page builders
* Fixed: Button hover states

= 1.0.4 - 2026-01-03 =
* Added: Addon Health monitoring page in admin
* Added: Error logging for addon hook callbacks
* Added: `Tempmails_Addon_Handler` — wraps all addon hooks in try/catch
* Fixed: PHP errors from misbehaving addons no longer crash Core

= 1.0.3 - 2026-01-02 =
* Fixed: Nonce verification on all AJAX endpoints
* Fixed: Message-ID sanitization now preserves `<>` characters
* Fixed: Attachment unserialization on frontend display
* Security: Stricter AJAX security checks across all endpoints
* Security: Proper SQL escaping in all database queries

= 1.0.2 - 2026-01-01 =
* Added: Ecosystem communication layer UI in admin
* Added: ecosystem.css for addon discovery panel
* Added: Visual addon cards in admin

= 1.0.1 - 2025-12-31 =
* Added: IMAP email fetching engine
* Added: Auto-refresh inbox via AJAX
* Added: Attachment download support
* Fixed: Database table creation on plugin activation
* Fixed: Cron scheduling on activation

= 1.0.0 - 2025-12-30 =
* Initial release
* Core email generation engine
* Message storage with soft delete
* Admin dashboard with statistics
* Frontend shortcode
* Basic IMAP integration

---

== Upgrade Notice ==

= 1.0.7 =
Security release. Fixes input sanitization in ajax_delete_message() and
ajax_mark_seen(). Resolves an infinite IMAP re-fetch loop. All addon
hooks retain identical signatures — no breaking changes. Update immediately.

---

== Developers ==

This section documents internal implementation details, security practices,
and notes for addon developers.

= Security Hardening Log =

All security changes are tracked here for auditing purposes.

**2026-04-04 — Security Review Pass (v1.0.7 patch)**

10. **class-core.php** — `ajax_delete_message()`: `$_POST['message_id']`
    was `wp_unslash()`-ed but not sanitized, with a `phpcs:ignore`
    suppression comment masking the warning. Now wrapped with
    `sanitize_text_field( wp_unslash( ... ) )`. Suppression comment removed.

**2026-04-02 — Security Review Pass (v1.0.7 patch)**

1. **class-design.php** — Removed raw `<style>` echo from `render_page()`.
   Static CSS moved to `assets/css/admin.css`.
2. **class-design.php** — `inject_css_variables()` refactored: replaced
   `echo "<style>..."` with `wp_add_inline_style('tempmails-admin', ...)`.
   All `$v()` return values now pass through `esc_attr()`.
3. **class-design.php** — `inject_frontend_css_variables()` refactored:
   all CSS values escaped with `esc_attr()`, `wp_strip_all_tags()` applied.
4. **class-design.php** — `wp_footer` fallback replaced raw `echo '<style>'`
   with a dummy registered style handle.
5. **class-tempmails-shortcodes.php** — Inline `<script>` replaced with
   `wp_add_inline_script('tempmails-frontend', ...)`.
6. **class-ecosystem.php** — Inline `<script>` replaced with
   `wp_add_inline_script('tempmails-admin', ...)`.
7. **class-core.php** — `ajax_mark_seen()`: sanitized with
   `sanitize_text_field( wp_unslash( ... ) )`.
8. **class-admin.php** — `save_settings()`: Raw `$_POST` replaced with
   `$clean_post = array_map('sanitize_text_field', wp_unslash($_POST))`.
9. **class-email-generator.php** — `get_emails()`: Cookie data sanitized
   with `array_values(array_filter(array_map('sanitize_email', $raw)))`.

= Addon Development Notes =

**Hook Stability Guarantee**

All hooks listed in the `== Hooks ==` section are frozen. Signatures will
not change in any 1.x release. Breaking changes will only occur in a major
version bump with a migration guide.

**$clean_post in save_settings hooks**

As of the 2026-04-02 security patch, both `tempmails_before_save_settings`
and `tempmails_before_save_imap_settings` receive a sanitized copy of
`$_POST`. If your addon previously relied on raw values via these hooks,
retrieve those fields directly from `$_POST` with appropriate sanitization.

**CSS Variable Injection**

`inject_css_variables()` now attaches inline CSS to the `tempmails-admin`
style handle. If your addon dequeues `tempmails-admin`, Design color
variables will not be applied on admin pages.

`inject_frontend_css_variables()` uses a priority waterfall:
1. Attaches to `tempmails-frontend` if registered/enqueued
2. Falls back to `tempmails-frontend-css`
3. Registers a dummy handle `tempmails-design-vars` in `wp_footer` at
   priority 1

= File Structure =

tempmails/
├── assets/
│   ├── css/
│   │   ├── admin.css
│   │   ├── frontend.css
│   │   └── ecosystem.css
│   └── js/
│       ├── admin.js
│       ├── admin-design.js
│       └── frontend.js
├── core/
│   ├── class-core.php
│   ├── class-admin.php
│   ├── class-design.php
│   ├── class-ecosystem.php
│   ├── class-email-generator.php
│   └── class-addon-handler.php
├── includes/
│   ├── class-tempmails-shortcodes.php
│   ├── class-tempmails-database.php
│   ├── class-tempmails-settings.php
│   ├── class-tempmails-imap.php
│   └── class-tempmails-fetcher.php
└── tempmails.php