Send Email with WordPress SMTP and Volanea

WordPress SMTP with Volanea lets your site send password resets, form notifications, order updates, and account emails through an authenticated SMTP relay instead of relying on PHP’s default mail transport. This guide configures the WP Mail SMTP plugin with credentials supplied through environment variables, then sends a real transactional email with WordPress’s native wp_mail() function.

What this integration does

WordPress sends most application email through wp_mail(). Core, WooCommerce, membership plugins, contact-form plugins, and custom code all commonly use that function rather than communicating with an email provider directly. The function is useful because it gives WordPress one mail-sending interface, but the transport behind it depends on your server configuration unless you explicitly configure SMTP.

With this setup, WP Mail SMTP becomes the mail transport layer. It intercepts outgoing wp_mail() calls and delivers them through Volanea’s SMTP relay using the SMTP values and credential format shown in your Volanea account’s current SMTP setup information.

That distinction matters:

• Your WordPress code sends with wp_mail(), not a made-up Volanea WordPress SDK.
• WP Mail SMTP handles the SMTP connection, authentication, encryption, and handoff.
• Volanea handles the message after handoff, including the normal sending pipeline associated with your account and authenticated sending domain.
• Your API key is treated as a secret, loaded from the server environment rather than committed to a theme, plugin, repository, or WordPress database field.

This is the right pattern when the email originates from WordPress itself: a password-reset request, a completed checkout, a new-user notification, a submitted form, or a custom plugin action. It preserves compatibility with existing WordPress plugins because they can continue calling wp_mail() normally.

Before you begin

Complete these prerequisites before adding code. The test send later in this guide is intentionally simple, but successful SMTP authentication does not replace sender-domain authentication or permission to send from a particular address.

You need:

1. A WordPress site where you can install and activate plugins. This guide uses WP-CLI for the installation command, but you can install the same plugin from the WordPress admin if WP-CLI is unavailable.
2. The WP Mail SMTP plugin.
3. A Volanea API key or SMTP credential that your account’s SMTP setup instructions identify as the SMTP password.
4. The exact SMTP host, port, encryption setting, and username provided for your Volanea account. Do not guess these values or copy hostnames from another email provider.
5. A verified sending domain and a From address that belongs to that domain.
6. Shell, hosting-panel, container, or secret-manager access to set environment variables for the PHP process that runs WordPress.

The Volanea send API accepts transactional sends and templates, but this guide deliberately uses SMTP because WordPress plugins are built around wp_mail() and SMTP transports. If you are building a standalone service or a custom application instead, consult the email API reference and setup guides and choose the REST API when direct request and response handling is the better fit.

Why use environment variables

Do not put a live API key in a theme’s functions.php, a custom plugin committed to Git, a public code snippet, or a configuration export. Those locations are routinely copied between environments, backed up, reviewed by multiple people, and occasionally exposed through deployment mistakes.

Environment variables keep secret values outside application source. In this guide, WordPress reads VOLANEA_API_KEY at runtime and provides it to WP Mail SMTP as the password for the Other SMTP mailer. The key never needs to appear in your repository.

Environment variables are not magical encryption. Anyone with sufficient operating-system, container, deployment, or hosting-panel access may still be able to read them. The goal is disciplined separation: code describes which configuration values are required; infrastructure supplies the values themselves.

Install WP Mail SMTP

WP Mail SMTP is the dependency for this integration. It supplies the WordPress SMTP transport; you do not need a fictional Volanea-specific PHP package to send through a standard SMTP relay.

From the WordPress installation directory, run this exact WP-CLI command:

wp plugin install wp-mail-smtp --activate

Confirm that WordPress sees the plugin as active:

wp plugin status wp-mail-smtp

A successful result should report the plugin as active. If WP-CLI is not installed, open the WordPress admin area, go to Plugins, add WP Mail SMTP, install it, and activate it. The rest of this guide still applies, but the command-line test examples require WP-CLI.

Avoid installing multiple SMTP plugins at the same time. Two plugins attempting to configure PHPMailer can produce inconsistent settings, intermittent delivery failures, or a situation where the last-loaded plugin silently wins. Disable other SMTP or mail-routing plugins before testing this configuration.

Confirm PHP can read environment variables

How you set environment variables depends on where WordPress runs:

• On a managed host, use the host’s environment-variable or secret-management feature.
• In Docker Compose, set them under the WordPress service’s environment or env_file configuration.
• In Kubernetes, provide them through a Secret and inject them into the WordPress container.
• With PHP-FPM, configure the service or pool so environment variables are passed through to PHP.
• For a one-time local test, export them in the same shell session that runs WP-CLI.

Do not assume that a variable visible in SSH is automatically visible to PHP-FPM or a web request. CLI PHP and web PHP can run under different users, services, and process managers. Test both contexts before treating the configuration as complete.

Set Volanea SMTP credentials as environment variables

Create these values in your infrastructure configuration. Replace the placeholder values with the current SMTP settings shown for your Volanea account. The SMTP host, port, username, and TLS mode are account/provider configuration—not values to infer from an API endpoint or another vendor’s documentation.

export VOLANEA_API_KEY='replace-with-your-volanea-api-key'
export VOLANEA_SMTP_HOST='replace-with-the-volanea-smtp-host'
export VOLANEA_SMTP_PORT='replace-with-the-volanea-smtp-port'
export VOLANEA_SMTP_USERNAME='replace-with-the-volanea-smtp-username'
export VOLANEA_SMTP_ENCRYPTION='tls'
export VOLANEA_FROM_EMAIL='notifications@example.com'
export VOLANEA_FROM_NAME='Example App'

The example uses tls because it is a common submission mode, but you must set VOLANEA_SMTP_ENCRYPTION to the encryption mode supplied in your Volanea SMTP configuration. If your account instructions specify another supported combination of port and encryption, use that exact combination together.

For example, a Docker Compose deployment can keep the secret outside the compose file by using an environment file that is excluded from Git:

VOLANEA_API_KEY=replace-with-your-volanea-api-key
VOLANEA_SMTP_HOST=replace-with-the-volanea-smtp-host
VOLANEA_SMTP_PORT=replace-with-the-volanea-smtp-port
VOLANEA_SMTP_USERNAME=replace-with-the-volanea-smtp-username
VOLANEA_SMTP_ENCRYPTION=tls
VOLANEA_FROM_EMAIL=notifications@example.com
VOLANEA_FROM_NAME=Example App

Add the file to .gitignore before entering a real key:

.volanea.env

The SMTP username and password are separate settings. Some SMTP services use a fixed username while using an API key as the password; others issue a unique SMTP username. Use exactly what your Volanea account provides. Do not replace the username with the sender address unless the account instructions explicitly say to do so.

Initialize WP Mail SMTP from wp-config.php

WP Mail SMTP supports configuration constants, which is useful when SMTP credentials should not be editable from the WordPress dashboard or stored as normal site options. Put the following code in wp-config.php above the line that says /* That's all, stop editing! Happy publishing. */.

This is the complete configuration block. It reads the API key from VOLANEA_API_KEY, configures WP Mail SMTP’s Other SMTP mailer, forces the authenticated sender, and avoids hard-coding the credential in PHP source.

<?php
/**
 * WP Mail SMTP configuration for Volanea SMTP.
 * Place this above: /* That's all, stop editing! Happy publishing. */
 */

define( 'WPMS_ON', true );
define( 'WPMS_MAILER', 'smtp' );

define( 'WPMS_MAIL_FROM', getenv( 'VOLANEA_FROM_EMAIL' ) );
define( 'WPMS_MAIL_FROM_FORCE', true );
define( 'WPMS_MAIL_FROM_NAME', getenv( 'VOLANEA_FROM_NAME' ) );
define( 'WPMS_MAIL_FROM_NAME_FORCE', true );
define( 'WPMS_SET_RETURN_PATH', true );

define( 'WPMS_SMTP_HOST', getenv( 'VOLANEA_SMTP_HOST' ) );
define( 'WPMS_SMTP_PORT', (int) getenv( 'VOLANEA_SMTP_PORT' ) );
define( 'WPMS_SSL', getenv( 'VOLANEA_SMTP_ENCRYPTION' ) );
define( 'WPMS_SMTP_AUTH', true );
define( 'WPMS_SMTP_USER', getenv( 'VOLANEA_SMTP_USERNAME' ) );
define( 'WPMS_SMTP_PASS', getenv( 'VOLANEA_API_KEY' ) );
define( 'WPMS_SMTP_AUTOTLS', true );

The block initializes the plugin configuration as WordPress loads. It does not send a message on every request. Sending remains the responsibility of WordPress code, WordPress core, or a plugin that calls wp_mail().

Validate configuration before sending

Before sending a production message, make sure PHP resolves every required variable. A missing variable can turn into an empty SMTP host, a port of 0, an empty username, or an empty password. Those failures often look like authentication or connection errors even though the root cause is environment configuration.

Run the following command from the WordPress directory:

wp eval '
$names = [
    "VOLANEA_API_KEY",
    "VOLANEA_SMTP_HOST",
    "VOLANEA_SMTP_PORT",
    "VOLANEA_SMTP_USERNAME",
    "VOLANEA_SMTP_ENCRYPTION",
    "VOLANEA_FROM_EMAIL",
    "VOLANEA_FROM_NAME",
];
foreach ( $names as $name ) {
    $value = getenv( $name );
    printf( "%s: %s\n", $name, $value === false || $value === "" ? "MISSING" : "SET" );
}
'

This command intentionally reports only SET or MISSING; it never prints the API key. Treat secret-safe diagnostics as a default practice. Debug logs, support tickets, terminal scrollback, and CI logs are all places where a copied credential can persist longer than intended.

Send one transactional email

Once WP Mail SMTP is active and the environment variables are available to WordPress, send a test transactional email through wp_mail(). This is a complete, copy-pasteable WP-CLI command. It loads WordPress, constructs an HTML message, sets explicit headers, and returns a non-zero exit code if WordPress reports that it could not hand the message to the configured mailer.

Replace recipient@example.net with an inbox you control.

wp eval '
$to = "recipient@example.net";
$subject = "Volanea SMTP test from WordPress";
$message = "<!doctype html><html><body><h1>SMTP is connected</h1><p>This transactional message was sent by WordPress through WP Mail SMTP.</p></body></html>";
$headers = [
    "Content-Type: text/html; charset=UTF-8",
    "From: " . getenv( "VOLANEA_FROM_NAME" ) . " <" . getenv( "VOLANEA_FROM_EMAIL" ) . ">",
];

$sent = wp_mail( $to, $subject, $message, $headers );

if ( ! $sent ) {
    fwrite( STDERR, "wp_mail() returned false. Check WP Mail SMTP configuration and logs.\n" );
    exit( 1 );
}

echo "WordPress accepted the message for SMTP delivery.\n";
'

A true result from wp_mail() means WordPress successfully passed the message to its configured mailer. It is not proof that the recipient received the email in the inbox. SMTP acceptance, provider processing, delivery to the recipient’s mailbox server, inbox placement, and user-visible rendering are separate stages.

Check the recipient inbox and spam folder after the test. Then review the event or sending activity available in your Volanea account to confirm that the message entered the provider pipeline. If the email reaches spam, do not respond by repeatedly sending the same test. First verify the sender domain, sender alignment, message content, recipient address, and authentication records.

Use the same pattern in a custom plugin

Production WordPress code should normally send only in response to a real application event. The following plugin example sends an account-welcome message when you explicitly call example_send_welcome_email() from your own workflow. It does not create a new SMTP connection or read the API key itself; WP Mail SMTP has already initialized the transport from wp-config.php.

Create wp-content/plugins/example-volanea-mail/example-volanea-mail.php:

<?php
/**
 * Plugin Name: Example Volanea Transactional Mail
 * Description: Sends a transactional message through the WordPress mail transport.
 * Version: 1.0.0
 */

function example_send_welcome_email( $recipient_email, $first_name ) {
    $subject = 'Welcome to Example App';

    $message = sprintf(
        '<!doctype html><html><body><h1>Welcome, %s</h1><p>Your account is ready.</p><p>If you did not create this account, contact support.</p></body></html>',
        esc_html( $first_name )
    );

    $headers = [
        'Content-Type: text/html; charset=UTF-8',
        'From: ' . getenv( 'VOLANEA_FROM_NAME' ) . ' <' . getenv( 'VOLANEA_FROM_EMAIL' ) . '>',
    ];

    return wp_mail( $recipient_email, $subject, $message, $headers );
}

Activate it:

wp plugin activate example-volanea-mail

Then test the function with a controlled recipient:

wp eval 'var_dump( example_send_welcome_email( "recipient@example.net", "Ada" ) );'

Keep transactional sending separate from bulk promotional sending. A password reset, purchase receipt, or security alert is an event-driven message expected by a specific user. It should be sent immediately and include only the information necessary for that transaction. Campaigns, newsletters, and lifecycle marketing have different consent, suppression, cadence, and audience-selection requirements.

Sender identity and deliverability checks

SMTP credentials authenticate your WordPress application to the relay. They do not, by themselves, establish that the From domain is authorized or trusted by receiving mailbox providers.

Use a sender such as notifications@example.com only after the domain is verified in Volanea and its required DNS records are published. Keep the sender consistent across application email categories where practical. Switching between unrelated addresses or consumer-mailbox domains can confuse recipients and complicate authentication alignment.

Before enabling real production traffic, confirm these items:

• The VOLANEA_FROM_EMAIL domain is a verified sending domain in your Volanea account.
• DNS authentication records supplied for that domain are published exactly as given.
• You have one valid SPF record for the domain rather than several competing SPF TXT records.
• Your From address is a valid address on the authenticated domain.
• The reply address, if you use one, is monitored by a team or process able to handle recipient replies.
• Test messages reach multiple mailbox providers, not only one internal inbox.
• Your plugin or application does not send mail in a loop after errors or repeated form submissions.

For forms that accept email addresses from users, validate input before using it as a recipient. WordPress’s is_email() checks basic email formatting, but a syntactically valid address can still be mistyped, inactive, disposable, or unable to receive mail. For high-value signup and invite flows, use an email address verification tool before generating repeated transactional sends to an unconfirmed address.

Use a fixed From address

The configuration forces the From address and From name so other plugins cannot replace them with an unverified address. That is generally safer than allowing every form or ecommerce extension to construct arbitrary sender identities.

Do not set the visitor’s email address as From for a contact form. That can break authentication alignment and makes reply handling unpredictable. Use your verified address as From, then set the visitor as Reply-To when your workflow needs staff to reply to the person who submitted the form.

For example:

$headers = [
    'Content-Type: text/html; charset=UTF-8',
    'Reply-To: visitor@example.net',
];

Only add a Reply-To value after validating it. Header injection protections and proper sanitization are especially important when an address originates from form input.

Common errors

Authentication failed or SMTP authentication error

Authentication failures usually mean the SMTP username, API key, or both do not match the values expected by the Volanea SMTP configuration. First verify that VOLANEA_API_KEY is present in the PHP process, then confirm the SMTP username from the account setup details.

Do not use your Volanea dashboard login password. Use the API key or SMTP credential designated for SMTP authentication. Check for whitespace introduced by secret-management templates, stale rotated keys, or quotation marks accidentally included as part of the stored value.

If the key was rotated, update the infrastructure secret and restart or reload the relevant service. PHP-FPM workers, containers, and long-running processes may retain their inherited environment until restarted.

Connection timed out, connection refused, or could not connect to host

These errors happen before authentication. Verify the host and port against your account’s SMTP setup information, then check outbound network rules from your WordPress host.

Shared hosts, cloud firewalls, container network policies, and hosting providers may restrict outbound SMTP connections. Do not switch ports at random. Use the exact host, port, and encryption pair your Volanea configuration provides, then ask the host to permit outbound traffic to that destination if necessary.

Also confirm that web PHP can see the environment variables. A shell export used for a WP-CLI test does not automatically configure PHP-FPM serving browser requests.

TLS, SSL, or encryption mismatch

A port and encryption setting are a pair. If Volanea’s SMTP instructions specify STARTTLS/TLS, set VOLANEA_SMTP_ENCRYPTION=tls and use the matching submission port. If they specify a different mode, use that mode and its matching port.

A mismatch can produce errors such as TLS negotiation failure, unexpected EOF, connection reset, or a server greeting that PHPMailer cannot interpret. Do not set encryption to none merely to make a test pass; that weakens credential protection and is not an appropriate production workaround.

wp_mail() returns false

A false return means WordPress could not hand the message to the configured mailer. Check that WP Mail SMTP is active, that no second SMTP plugin is overriding it, and that the constants are located above WordPress’s stop-editing line in wp-config.php.

Enable diagnostic logging only long enough to identify the error, and avoid storing full message content in logs unless your privacy and retention requirements permit it. Transactional messages can contain password-reset links, billing context, account details, or personal data.

The email sends, but it is plain text or HTML appears as markup

Set the MIME content type correctly. The Content-Type header must be included exactly once and must match the body you provide:

'Content-Type: text/html; charset=UTF-8'

If a plugin independently changes headers, it may override your intended format. Test with a minimal HTML body first, then add templates, inline styles, images, attachments, or plugin-generated markup one piece at a time.

The From address is replaced or rejected

The forced sender constants are intentional. WordPress plugins can otherwise inject their own From address, which may be unverified or outside your authenticated domain.

If a sender is rejected, confirm that VOLANEA_FROM_EMAIL is set, uses the verified domain, and is not being overwritten by a must-use plugin, an ecommerce extension, or another mail plugin. Use Reply-To for user-generated addresses instead of changing From.

The test works in WP-CLI but fails from the website

This nearly always points to environment scope. WP-CLI often runs as your SSH user and inherits your shell variables; the website usually runs through PHP-FPM, Apache, or a container under another process and user.

Set the variables in the service that runs web PHP, restart that service, and rerun the test from an actual browser-triggered workflow such as a password reset or contact-form submission. Treat CLI success as evidence that the credentials are valid, not as proof that the web runtime is configured.

Async or background job mistakes

WordPress’s wp_mail() is synchronous from the caller’s perspective: it returns after the configured mailer has accepted or rejected the handoff. Do not write JavaScript-style await wp_mail() code in PHP, and do not assume a true return guarantees inbox delivery.

If your plugin schedules email through WP-Cron, Action Scheduler, or another background queue, make the job idempotent. A worker can retry after a timeout even when the original SMTP handoff completed. Store an application-level message or event identifier before retrying so one purchase, invite, or password-reset action does not create duplicate email.

Production guidance

Start with a controlled production test: one verified sender, one recipient you control, one simple message, and one clear application trigger. Once that works, test the high-value messages your users depend on most: password resets, verification emails, receipts, and administrative alerts.

Use separate environment values for local development, staging, and production. A staging site should not accidentally send customer-facing email from the production identity. Prefer a staging sender domain or a non-delivering test workflow where available, and clearly label test messages in the subject line.

Monitor failures at two layers. WordPress logs and WP Mail SMTP diagnostics reveal whether the application could authenticate and hand off a message. Volanea’s sending activity and event data reveal what happened after the provider accepted it. A message can be accepted by SMTP but subsequently bounce, be suppressed, or be rejected by a recipient server.

Build for recipient safety as well as delivery. Honor unsubscribe and suppression state for non-essential messages, avoid retry loops against invalid recipients, and keep send volume proportional to real user actions. Authentication records, correct SMTP configuration, and low error rates support deliverability; none of them justify sending mail a recipient did not request.

Next steps

After the basic WordPress SMTP with Volanea connection works, improve the integration in two directions.

First, use webhooks to receive event notifications in your application. Webhooks let a server receive information about events such as delivery outcomes, bounces, complaints, or engagement where those events are available for your account. Verify webhook signatures, return a fast successful response after validating the request, and process longer work asynchronously. This lets you update customer records, stop retries to bounced addresses, or create support tasks without relying on inbox checking.

Second, use templates for reusable transactional content. Templates separate email presentation from WordPress business logic, reduce repeated HTML strings in plugins, and make versioned copy changes easier to review. Keep variables narrowly scoped, provide safe fallback values, and test the rendered output for real recipient data before enabling it for password resets, receipts, or account notifications.

For direct REST sends, template operations, and event-handling implementation details, use the Volanea documentation rather than inventing a WordPress-only API method. SMTP is ideal for preserving existing wp_mail() integrations; the API is a better choice when your custom application needs explicit request bodies, response handling, templates, or webhook-driven workflows.

FAQ

Do I need a Volanea WordPress SDK?

No. This integration uses the standard SMTP path supported by WP Mail SMTP. WordPress plugins continue using wp_mail(), while WP Mail SMTP delivers the message through the configured Volanea SMTP relay.

Is the Volanea API key safe in wp-config.php?

The code only reads the key with getenv( 'VOLANEA_API_KEY' ); the secret should live in your host, container, or secret manager environment configuration. Do not paste the live key directly into wp-config.php or commit it to source control.

Can I use this with WooCommerce or contact form plugins?

Usually, yes. Most WordPress plugins send through wp_mail(), which WP Mail SMTP routes through the configured SMTP transport. Test each critical email type after setup because individual plugins can set their own headers, sender values, or queue behavior.

Does wp_mail() returning true mean the email reached the inbox?

No. It means WordPress successfully handed the message to its configured mailer. Check Volanea’s sending activity and the recipient mailbox to distinguish SMTP handoff, provider processing, delivery, and inbox placement.

Should I use SMTP or the REST API?

Use SMTP when you want existing WordPress code and plugins to keep using wp_mail() without rewrites. Use the REST API when you are building custom application workflows that need direct response handling, explicit payloads, reusable templates, or event-driven integrations.