=== Volanea SMTP ===
Contributors: volanea
Tags: smtp, email, wp_mail, transactional email, deliverability
Requires at least: 5.7
Tested up to: 7.0
Requires PHP: 7.2
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send WordPress email through the Volanea API instead of PHP mail(), with an automatic fallback so no message is ever lost.

== Description ==

Volanea SMTP hands every `wp_mail()` call to the Volanea HTTP API, so password
resets, order receipts, form notifications and everything else leave your site
over an authenticated API connection rather than the server's local `mail()`
binary.

Despite the name, the plugin does not speak SMTP. It uses Volanea's HTTPS API,
which means there is no port to unblock and no SMTP password stored on the site.

= Never silently dropped =

The plugin only takes over a message it can send faithfully. If the API refuses
the message, the key is wrong, the network fails, or the message uses something
the API cannot express, the plugin steps aside and WordPress delivers it the way
it always did. A failed send is never a lost send.

= What it handles =

* To, Cc, Bcc and Reply-To
* HTML and plain text bodies, including the `wp_mail_content_type` filter
* Attachments (up to 10 per message)
* Custom headers such as `X-` headers
* Headers passed as either a string or an array, in any combination
* Recipient lists longer than the API's 50-address limit, split automatically

= Known differences from the default mailer =

These are worth reading before you switch a busy site over.

* **Cc and Bcc.** The Volanea API has no Cc or Bcc field. The plugin gives each
  copied address its own message, which is exactly right for Bcc: the copy
  arrives and no one else can see it. A Cc recipient also receives the message,
  but no visible `Cc:` header is present on any copy. If you need a real Cc
  header, turn off "Deliver Cc and Bcc recipients as individual copies" and
  those messages will go through the default WordPress mailer instead.
* **One message per recipient.** A message addressed to several people is sent
  as a separate message to each, so recipients do not see one another.
* **Multiple Reply-To addresses.** The API accepts one; the first is used.
* **Plain-text messages.** The API renders a text-only body inside a `<pre>`
  block, so plain-text email looks a little different from `mail()` output.
* **Hand-built multipart messages.** A message that supplies its own MIME
  boundary is passed to the default mailer untouched.
* **A 200 response is not delivery.** The API accepts the message and delivers
  it afterwards. The recipient may still be skipped for being suppressed,
  unsubscribed or over quota. Skips are recorded in the log and, deliberately,
  are not retried through `mail()`.

= Storing the API key more safely =

By default the key is stored in the options table. To keep it out of the
database entirely, add this to `wp-config.php`:

`define( 'VOLANEA_SMTP_API_KEY', 'your-secret-key' );`

The constant wins over anything saved in the admin, and the settings page then
shows the key as read-only and masked.

= Filters for developers =

* `volanea_smtp_api_base` — change the API base URL, for staging.
* `volanea_smtp_request_args` — adjust the `wp_remote_post()` arguments.
* `volanea_smtp_payload` — modify the request body before it is sent.

== External services ==

This plugin sends your site's outgoing email to Volanea, a third-party email
delivery service, so that it can be delivered.

It contacts `https://api.volanea.com` only when you have saved an API key, and
only at these moments:

* Every time WordPress sends an email while the plugin is configured.
* When you press "Send test email" on the settings screen.

The data sent with each message is: the sender name and address, the recipient
addresses, the subject, the message body, any custom headers set by the code
that sent the mail, and any attachments. No data is transmitted before you
enter an API key.

Volanea's terms of service: https://volanea.com/terms
Volanea's privacy policy: https://volanea.com/privacy

== Installation ==

1. Upload the `volanea-smtp` folder to `/wp-content/plugins/`, or install the
   plugin through the Plugins screen.
2. Activate the plugin.
3. Go to **Settings > Volanea SMTP**.
4. Paste your Volanea secret key and set the From address. The From address must
   be on a domain you have already verified in Volanea, or the API will refuse
   the message.
5. Press **Send test email** to confirm the connection.

== Frequently Asked Questions ==

= What happens if Volanea is unreachable? =

The message goes out through the default WordPress mailer instead, exactly as it
would have if the plugin were not installed. Turn on the email log to see which
messages took that path and why.

= My test email says "test mode: nothing was delivered". =

You are using a test key. Test keys exercise the whole pipeline but never send
anything to a real inbox. Swap in a live key to send real email.

= The API says my From domain is not verified. =

Volanea only sends from domains you have verified. Add and verify the domain in
your Volanea dashboard, then set the From address to an address on it.

= Does the log store the contents of my email? =

No. It stores the recipient, the subject, the status and any error message for
the last 50 sends. Message bodies and attachments are never written to the log,
and the log is off until you turn it on.

= Can I use this alongside another SMTP plugin? =

It is not a good idea, but the plugin will not fight for the message: if another
plugin has already claimed a message, Volanea SMTP leaves it alone.

= Will a failed send ever be delivered twice? =

The one case where it can is a request that times out after the API has already
accepted the message. The plugin then treats the send as failed and lets
WordPress retry it, which can produce a duplicate. This is rare, and the
alternative — treating a timeout as a success — would risk losing mail instead.

== Screenshots ==

1. The settings screen, with the connection fields and the test email button.
2. The email log, showing recent sends and the reason for any fallback.

== Changelog ==

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.0 =
First release.
