=== Magic API Email ===
Contributors:      magicwpio
Tags:              email, smtp, resend, mailgun, postmark
Requires at least: 6.0
Tested up to:      7.0
Requires PHP:      8.0
Stable tag:        1.2.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Send WordPress emails through a transactional API provider: Resend, Mailgun, Postmark, or Mailtrap. No SMTP needed.

== Description ==

**Magic API Email** replaces the default WordPress email system (`wp_mail()`) with a direct API connection to your chosen transactional email provider. No SMTP configuration needed — just paste your API key and you're ready to go.

**Supported Providers:**

* [Resend](https://resend.com) — Modern email API for developers
* [Mailgun](https://mailgun.com) — Reliable transactional email
* [Postmark](https://postmarkapp.com) — Fast, deliverable transactional email
* [Mailtrap](https://mailtrap.io) — Email delivery platform with sandbox testing
* [Plunk](https://useplunk.com) — Email API for developers

**Features:**

* Per-provider settings — API key, From Email, and From Name are stored independently for each provider. Switching providers never overwrites another provider's credentials.
* Full `wp_mail()` support — attachments, Cc, Bcc, Reply-To, custom headers, and HTML bodies are all passed through to your provider.
* Fallback providers — if the selected provider fails, optionally try every other provider you have credentials for.
* Automatic retries — timeouts, rate limits and provider outages can be re-queued instead of losing the email.
* Background sending — optionally queue email so no page load waits for an API call.
* Logs and statistics — every attempt is recorded, with a retention window, a one-click purge, and full support for WordPress's privacy export/erase tools.
* Test email — Send a test email directly from the settings page to verify your configuration.
* Secure — All inputs are sanitized and validated. API keys can live in `wp-config.php` instead of the database and are never printed back into the page.
* Lightweight — No dependencies, no bloat, no build step.
* Developer-friendly — Falls back to default `wp_mail()` if no API key is configured, and still fires the `wp_mail` filter and `wp_mail_failed` action.

== Installation ==

1. Upload the `magic-api-email` folder to the `/wp-content/plugins/` directory, or install the plugin through the WordPress Plugins screen directly.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Navigate to **Magic API Email** in the WordPress admin sidebar.
4. Select your email provider, enter your API key, From Email, and From Name.
5. Click **Save Settings**.
6. Use the **Send Test Email** section to verify everything is working.

== External services ==

This plugin acts as a bridge between your WordPress site and your chosen transactional email provider. By design, instead of sending emails via standard `wp_mail()`, this plugin sends the content of your outgoing emails via an HTTPS API request to the provider you select in the settings.

Depending on your configuration, the plugin connects to one of the following APIs:
* **Resend** (api.resend.com) - [Terms of Service](https://resend.com/terms) | [Privacy Policy](https://resend.com/privacy)
* **Mailgun** (api.mailgun.net) - [Terms of Service](https://www.mailgun.com/terms) | [Privacy Policy](https://www.mailgun.com/privacy)
* **Postmark** (api.postmarkapp.com) - [Terms of Service](https://postmarkapp.com/terms-of-service) | [Privacy Policy](https://postmarkapp.com/privacy-policy)
* **Mailtrap** (api.mailtrap.io) - [Terms of Service](https://mailtrap.io/terms) | [Privacy Policy](https://mailtrap.io/privacy-policy)
* **Plunk** (api.useplunk.com) - [Terms of Service](https://useplunk.com/terms) | [Privacy Policy](https://useplunk.com/privacy)

**What data is sent and when?**
When any plugin or WordPress core feature attempts to send an email (e.g. password resets, contact form submissions, order confirmations), the data (including the recipient's email address, sender information, email subject, and email body content) is transmitted securely to your configured provider in order to deliver the email. No data is sent if you have not configured an API key for a provider.

== Frequently Asked Questions ==

= Which providers are supported? =

Resend, Mailgun, Postmark, Mailtrap, and Plunk are currently supported.

= Do I need to configure SMTP? =

No. Magic API Email sends emails directly through each provider's REST API, so no SMTP setup is required.

= Will switching providers erase my other provider's settings? =

No. Each provider's API key, From Email, and From Name are stored separately. You can switch between providers freely without losing any credentials.

= Where do I get an API key? =

* **Resend:** [resend.com](https://resend.com) — Create an account and generate an API key in the dashboard.
* **Mailgun:** [mailgun.com](https://mailgun.com) — Create an account, add a sending domain, and copy the API key.
* **Postmark:** [postmarkapp.com](https://postmarkapp.com) — Create a Server and copy the Server API Token.
* **Mailtrap:** [mailtrap.io](https://mailtrap.io) — Create an account and generate a sending API token.
* **Plunk:** [useplunk.com](https://useplunk.com) — Create a project and copy the secret API key.

= Can I keep my API key out of the database? =

Yes. Define it in `wp-config.php` and it takes precedence over anything saved on the settings page:

`define( 'MAGIC_API_EMAIL_RESEND_KEY', 're_xxx' );`
`define( 'MAGIC_API_EMAIL_MAILGUN_KEY', 'key-xxx' );`
`define( 'MAGIC_API_EMAIL_MAILGUN_DOMAIN', 'mg.example.com' );`
`define( 'MAGIC_API_EMAIL_POSTMARK_KEY', 'xxx' );`
`define( 'MAGIC_API_EMAIL_MAILTRAP_KEY', 'xxx' );`
`define( 'MAGIC_API_EMAIL_PLUNK_KEY', 'sk_xxx' );`

= Does it support attachments, Cc, Bcc and Reply-To? =

Yes, on every provider except Plunk, whose API has no attachment or Cc/Bcc support. When Plunk is selected, each Cc/Bcc address receives its own copy and any attachments are reported on the log entry instead of being dropped silently.

= What happens if a send fails? =

By default the failure is logged and `wp_mail_failed` is fired. Under **Settings → Delivery & Reliability** you can additionally enable fallback providers (try every other provider that has credentials saved) and retries (re-queue timeouts, rate limits and server errors, up to three attempts).

= What happens if I don't configure the plugin? =

If the API key or From Email is empty, the plugin falls back to WordPress's default email handling — no emails are lost.

= Does this plugin support HTML emails? =

Yes. If WordPress or another plugin sends an email with a `Content-Type: text/html` header, Magic API Email will send it as HTML to the provider.

= Where are errors logged? =

Every send attempt — successful or not — is recorded on the **Logs** tab of the plugin settings page, together with the provider's error message. API errors are additionally passed to `wp_trigger_error()`, so they appear in the WordPress debug log (`wp-content/debug.log`) when `WP_DEBUG_LOG` is enabled in `wp-config.php`.

= Can I stop the log table from growing forever? =

Yes. Choose a retention window under **Settings → Delivery & Reliability** and a daily job trims anything older. There is also a **Clear All Logs** button on the Logs tab. Logs are exported and erased through WordPress's own privacy tools.

== Screenshots ==

1. Resend API settings configuration.
2. Mailgun API settings configuration.

== Changelog ==

= 1.2.0 =
* Fix: A failed send could trigger a fatal error on WordPress 6.0–6.3, because `wp_trigger_error()` only exists from WordPress 6.4. The call is now guarded.
* Fix: Attachments were silently dropped. They are now delivered by Resend, Mailgun, Postmark and Mailtrap; Plunk has no attachment API, so the log entry says so instead of the file vanishing.
* Fix: Cc, Bcc, Reply-To and custom headers were discarded and are now passed to the provider.
* Fix: The `wp_mail` filter was never applied, silently disabling other plugins that hook it. It now runs before the message is sent.
* Fix: The `wp_mail_failed` action is now fired when a send fails, so error-monitoring plugins see failures again.
* Fix: Recipients written as `Name <user@example.com>` were rejected by Mailtrap. Addresses are now parsed consistently for every provider.
* Fix: Plunk silently discarded all recipients after the first. Each recipient now gets its own request.
* Fix: A non-UTF-8 `Content-Type` charset could produce an empty request body. Subject and body are now converted to UTF-8.
* Fix: Sending a test email registered a second `pre_wp_mail` callback, which could send and log other emails in that request twice.
* Fix: The Logs tab could show stale results for up to five minutes on sites using a persistent object cache.
* Feature: Fallback providers — on failure, optionally try every other provider that has credentials saved.
* Feature: Automatic retries for timeouts, rate limits and provider errors, up to three attempts.
* Feature: Optional background sending, so a page load never waits for the provider's API.
* Feature: Log retention window with a daily cleanup job, plus a "Clear All Logs" button.
* Feature: API keys and the Mailgun domain can be defined in `wp-config.php` and are no longer printed back into the settings page.
* Feature: Email logs are now covered by WordPress's personal data export and erase tools.
* Feature: The test email can now be sent as HTML.
* Feature: Logs can be searched by recipient or subject and filtered by status and provider.
* Feature: Export the log list — with your current search and filters applied — as a CSV file.
* Feature: Long provider errors expand in place instead of being cut off at 80 characters.
* Feature: Statistics can be viewed over the last 7, 30 or 90 days as well as all time, with a daily volume chart.
* Feature: Postmark's message stream is now configurable instead of always being `outbound`.
* Feature: Site Health check reporting an unconfigured provider or a run of delivery failures.
* Feature: WP-CLI commands — `wp magic-email status`, `test`, `logs` and `prune`.
* Enhancement: Admin interface redesigned to the MagicWP brand identity, and fully right-to-left aware.
* Enhancement: Network activation creates the log table on every site of a multisite install.
* Enhancement: Added `uninstall.php` — deleting the plugin now removes its table, options and queued messages.

= 1.1.1 =
* Compatibility: Tested with WordPress 7.0.

= 1.1.0 =
* Feature: Email logging — every outgoing email is now recorded in a custom database table with recipient, subject, provider, status, and error details.
* Feature: Logs tab — browse all email logs with a sortable, paginated WP_List_Table on the plugin settings page.
* Feature: Statistics tab — at-a-glance dashboard showing total emails sent, success/failure counts, and per-provider usage breakdown.
* Enhancement: Admin settings page refactored into a native WordPress tabbed interface (Settings, Logs, Statistics).
* Enhancement: Sender class now captures and stores error messages for failed API requests.

= 1.0.12 =
* Fix: Versioning conflict in the previous deployment package.

= 1.0.11 =
* Feature: Added plugin banner and screenshots to the repository.
* Tweak: Updated plugin icon.
* Tweak: Bumped version to 1.0.11.

= 1.0.10 =
* Feature: Added plugin icon.
* Tweak: Version bump for assets update.

= 1.0.9 =
* Fix: Removed unnecessary `mu-plugins` directory.
* Tweak: Updated readme file for better documentation.

= 1.0.8 =
* Fixed menu position to comply with WordPress.org guidelines (moved to Settings page).
* Added explicit documentation for external API services in README.
* Added `magicwpio` to contributors to verify plugin ownership.

= 1.0.7 =
* Added Plunk provider support.

= 1.0.6 =
* Fixed missing translators comment placement in test email handler.
* Replaced error_log() with wp_trigger_error() for production-safe logging.
* Removed discouraged load_plugin_textdomain() call (auto-loaded by WordPress.org).
* Added wp_unslash() before sanitize_email() on POST data.
* Deleted .DS_Store hidden file.

= 1.0.5 =
* Renamed plugin to Magic API Email.
* Added Author URI (https://magicwp.io).
* Added Text Domain and Domain Path headers for WordPress.org compliance.
* Added version and copyright footer to the settings page.
* Improved translators comments throughout for i18n compliance.

= 1.0.4 =
* Added Postmark provider support.

= 1.0.3 =
* Added Mailtrap provider support.

= 1.0.2 =
* Per-provider settings storage — API key, From Email, and From Name are now stored independently per provider.
* Fixed "Request failed" error when sending test emails after provider switch.
* Fixed fields being cleared when switching providers.
* Fixed "Settings saved." notice not appearing on top-level menu pages.

= 1.0.1 =
* Added Mailgun provider support.
* Fixed duplicate "Settings saved." notice.
* Moved plugin to top-level admin menu with email icon.

= 1.0.0 =
* Initial release with Resend provider support.
* Settings page with API Key, From Email, and From Name.
* Test email functionality.
* `wp_mail()` interception via `pre_wp_mail` filter.

== Upgrade Notice ==

= 1.0.5 =
Renamed from "MagicWP Email" to "Magic API Email". If upgrading from 1.0.4 or earlier, please re-enter your API credentials after activation as the settings storage key has changed.
