Vora SMTP documentation

Install

WordPress sends mail with PHP’s mail() function by default. Most hosts send it from an address the receiving server cannot verify, so password resets, order receipts and contact form notifications quietly land in spam or vanish. This plugin replaces that with a real authenticated connection to a mail service you already control.

1. 1Upload the plugin to /wp-content/plugins/ and activate it from the Plugins screen.
2. 2Go to Vora SMTP → Providers and choose your sending method.
3. 3Enter the credentials for your SMTP server, or connect a Gmail account over OAuth.
4. 4Set your From name and address under Vora SMTP → Settings.
5. 5Send a test message from Vora SMTP → Dashboard and confirm it arrives.

The four screens

Everything lives under one top-level menu, and every screen needs the capability an administrator has.

Dashboardvora-smtp

Delivery statistics — sent today, failed today, and the last seven days — the ten most recent messages, and the test-email tool.

Providersvora-smtp-providers

Choose the active sending method and configure it. The fallback method is armed here too.

Settingsvora-smtp-settings

Sender identity, whether to force it site-wide, logging options and failure alerts.

Email Logvora-smtp-log

Every message the plugin handled, filterable by status, provider, recipient or subject, with per-message detail, preview and resend.

Sending methods

Three, chosen on the Providers screen. Only the one you select is used, and the plugin makes no outbound request to any third party at all while Generic SMTP or PHP Mail is active.

Generic SMTPsmtp

Any provider that gives you a host, port, username and password, over TLS, SSL or unencrypted. The default active method.

Gmail and Google Workspacegmail

Connect over OAuth 2.0 with your own Google app. No password is stored and no app password is needed.

PHP Mailphpmail

The server's own mail() function, with nothing to configure. Deliverability is the weakest of the three, which is why it exists mainly as a safety net rather than a first choice.

Generic SMTP

Six fields, and your provider documents all of them. The setting key beside each name is what it is stored as, should you ever need to set it in code.

SMTP hostsmtp_host

Your provider's outgoing server, for example smtp.example.com.

Portsmtp_port · default 587

587 for TLS (submission), 465 for implicit SSL, 25 for unencrypted. 587 is the right answer almost everywhere.

Encryptionsmtp_encryption · default tls

TLS, SSL or none. Match it to the port: a TLS setting on port 465 fails to connect, and so does the reverse.

Authenticationsmtp_auth · default on

Leave it on unless your provider explicitly relays without credentials — an internal relay on port 25, typically.

Usernamesmtp_username

Usually the full mailbox address. Some providers issue a separate API username instead.

Passwordsmtp_password

Stored in your own database, in the single vora_smtp_settings option, and transmitted only to the server you configured.

Connecting Gmail

Gmail connects over OAuth 2.0 using an app you register, so no password is ever stored and the connection stays strictly between your site and Google.

1. 1In Google Cloud Console, create a project and enable the Gmail API for it.
2. 2Create an OAuth 2.0 Client ID of type Web application.
3. 3Add the plugin's Redirect URI to Authorized redirect URIs — the Providers screen shows it with a copy button, and it is your own site's admin.php?page=vora-smtp.
4. 4Copy the Client ID and Client secret into the Gmail form on the Providers screen and save.
5. 5Press Connect Google Account, approve the consent screen, and Google returns you to the Providers screen showing Connected as your address.

The plugin requests exactly three scopes: https://www.googleapis.com/auth/gmail.send, openid and email. The send scope permits sending only — it does not allow reading, listing, searching, modifying or deleting anything in the mailbox. The other two are used once, to read back which account you connected and to seed your sender identity.

PHP Mail

Nothing to configure: it hands the message to the server’s own mail(). It is worth understanding as the fallback rather than as a choice — it is the one route that needs no credentials and no third-party call, so it is still available when the configured provider is not.

Automatic fallback

A mail provider can stop accepting messages for reasons that have nothing to do with your site: an expired credential, a rate limit, an outage, a DNS failure. Normally the message is simply lost, and nobody finds out until a customer says they never got their receipt.

What happens on a failure

The message is immediately retried through a second sending method of your choice. Fallback covers every method, including Generic SMTP.

The defaultfallback_provider = phpmail · enable_fallback = on

PHP Mail, armed by default. It needs no credentials and no connection to a third party, so it is still there when the configured provider is not — and a message in a spam folder beats one that was never sent.

What the log says

The entry records the method that actually delivered the message, so a send rescued by the fallback is never credited to the provider that failed.

Turning it off

Switch it off, or point it at a different method, on the Providers screen. Existing sites keep whatever they already stored rather than being moved onto the new default.

Sender identity

Set the From name and address once, on the Settings screen, and optionally force every message on the site to use them.

From address and From namefrom_email · from_name

Used when the sending code does not specify its own.

Reply-Toreply_to

Optional, and useful when you send from a no-reply address but want replies to reach a real mailbox.

Force themforce_from_email · force_from_name · both off

On, your values override whatever any other plugin sets. This is how you stop a contact form or WooCommerce quietly sending as its own address — which, if that address is not one your provider can send as, is a rejection every time.

Broken defaults are repaired

Addresses such as wordpress@localhost cause outright send failures on local and staging installs. The plugin substitutes a usable address rather than letting the send fail.

The email log

Every message the plugin handles is recorded, so you can prove what was sent, see exactly what it looked like, and send it again without asking the customer to trigger it a second time.

Preview

Open any logged message and read it as the recipient saw it. HTML is rendered in a sandboxed frame, so a message can be inspected without its markup, styles or scripts touching your admin screen. Bodies are only available when body storage is switched on.

Resend

Send any logged message again in one click, to the original recipient, using your current sending method — useful when a receipt failed while a provider was down, or a password reset never arrived.

Filters

Narrow the history by status (Sent, Failed, Queued), by provider, or by searching recipient and subject. Statuses display translated while still filtering on the stored English key.

The real error

A failed entry records the actual text the mail server returned, not a generic failure notice — which is usually the whole answer to why a message did not arrive.

Which method delivered it

Each entry records the method that actually delivered the message, so a send rescued by the fallback is never credited to the provider that failed.

Delete and Clear All

Remove a single entry, or empty the log entirely. Both are permanent and both ask first.

Three settings control what it keeps:

Enable logginglog_enabled · default on

Turn the log off entirely and the plugin still sends; it simply records nothing.

Retentionlog_retention_days · default 30

Entries older than this are pruned on a schedule, so the log cannot grow without limit.

Store message bodieslog_store_body · default off

Off, the log keeps metadata only — recipient, subject, sender, provider, status, message ID, error and timestamp. On, it also keeps the body, which is what makes Preview useful and which noticeably increases database size.

Failure alerts

Optionally email a chosen address whenever a message cannot be delivered. The alert names the recipient, the sending method used and the error the mail server returned.

Alert on failurealert_on_failure · default off

Switches alerting on.

Alert email addressalert_email

Where alerts go. Point it at a mailbox on a different domain from the site where you can — an alert about your mail being broken is not much use if it goes through the thing that is broken.

Alerts cannot loop

A failing alert never triggers another alert.

Testing and diagnostics

The Dashboard summarises messages sent, failures and success rate, and lists the ten most recent messages. Two tools sit alongside it:

Test Connection

On the Providers screen. Performs a real handshake with the configured server — for SMTP, an actual PHPMailer connection with a five-second timeout — and reports exactly what came back. It proves the credentials work; it does not prove your sender is accepted.

Send a test message

On the Dashboard. Sends a real message to any address you type, through the full pipeline including fallback, and shows what the mail server said if it does not arrive.

Still going to spam?

Authenticated sending fixes the connection. Receiving servers also check your domain’s DNS, and that part is outside any plugin: add SPF and DKIM records for whichever service you send through, and a DMARC record once those two are in place. Your provider documents the exact values. A correctly configured SMTP connection sending from a domain with no SPF record will still land in spam.

External services

The plugin contacts only the services required by the sending method you configure, and nothing at all under Generic SMTP or PHP Mail.

Google OAuth 2.0oauth2.googleapis.com/token

Exchanges the authorisation code for an access token, and refreshes that token when it expires. Sends your app's client ID and secret, the code returned by Google's consent screen, and your refresh token — when you press Connect, and afterwards whenever a stored token has expired.

Gmail APIgmail.googleapis.com

Transmits outgoing mail while Gmail is the active method. Sends the message itself: recipients, subject, body, headers and attachments.

Microsoft identity platformlogin.microsoftonline.com · graph.microsoft.com

Never contacted by the free plugin, which offers no Microsoft sending method. The OAuth code ships here and is used when the Pro add-on supplies the Microsoft 365 provider; it is declared because the requests are made by this plugin's code.

Hooks for developers

The extension points an add-on uses — and the same ones are available to a site’s own code.

vora_smtp_register_providersaction

Fires where a provider should register itself. An add-on adds a sending method here, and its settings keys are picked up automatically.

vora_smtp_delivery_failedaction

Fires when a message could not be delivered, after any fallback has also failed.

vora_smtp_maybe_fallbackfilter

Last word on a failed send, after the built-in fallback has been tried.

vora_smtp_phpmailer_providersfilter

Which providers are considered PHPMailer-based, and so configured through phpmailer_init rather than an API call.

vora_smtp_oauth_refreshfilter

Lets an add-on take over refreshing an access token — how Pro renews a connection made through its hosted relay.

vora_smtp_oneclick_available · vora_smtp_oneclick_start_urlfilters

How an add-on advertises a one-click connection the free plugin has no credentials for. Both are what Vora SMTP Pro uses to add its relay-backed setup.

vora_smtp_derive_from_email_candidatesfilter

The addresses considered when the plugin repairs an unusable default sender.

Uninstalling

Deactivating hands sending back to WordPress’s default mail() and preserves your settings and logs. Deleting the plugin drops its tables and options — including the whole email log — so export anything you need to keep first.

Troubleshooting