# wp-mail-from: a real From address for every WordPress email

wp-mail-from is a must-use WordPress plugin that sets a real From address, From name and envelope sender on every wp_mail() message. It is for site operators whose notifications leave from wordpress@ and whose bounces go nowhere. The code is at [https://github.com/IndianOpinion/wp-mail-from](https://github.com/IndianOpinion/wp-mail-from), under the MIT licence, and v0.1.0 was released on 12 November 2026.

It never sends mail itself, never opens a connection and never replaces wp_mail(). We wrote it from scratch. It is independent of and not affiliated with any third-party plugin it integrates with.

## The problem

Out of the box, WordPress sends every message as wordpress@<your domain> with the display name "WordPress". On almost every site that mailbox does not exist. Two things follow.

- Bounces vanish. Delivery failures, out-of-office replies and complaints go to an address nobody reads, so the operator never learns that password resets are not arriving.

- Receiving servers distrust the domain. A sender that cannot receive mail, an envelope sender that does not match the From header and a generic name all count against the message in spam scoring. Once SPF and DMARC are added, an unaligned envelope sender can turn "spam folder" into "rejected".

We have no delivery figures to offer. The usual answers are a ten-line wp_mail_from filter that gets some cases wrong, or a full SMTP plugin that does far more than this job.

## What it does

- Replaces the core default From address and name on every message with a configured identity.

- Sets the envelope sender, which becomes the SMTP MAIL FROM and the Return-Path the receiver records.

- Adds a Reply-To when a message has none and its own From was moved.

- Handles mail that sets its own From, such as contact forms, in three modes: respect (the default), align and override.

- Reads settings from constants in wp-config.php, then a per-site option, then a network option on multisite, then a derived default.

- Offers a dry-run mode that logs decisions and changes nothing, and WP-CLI commands show, set and reset.

## How it works

Inside one wp_mail() call:

- On the wp_mail filter at priority 1000, the plugin reads the headers the way core will: string or array, CRLF or LF, any case, last From wins. It resolves the identity and decides. The arguments are returned unchanged.

- On pre_wp_mail, if another plugin short-circuits the message, the plugin's state is dropped.

- On wp_mail_from and wp_mail_from_name at priority 5, the decision is applied. It runs early, so later code, including an SMTP plugin's forced From, still wins.

- On phpmailer_init at priority 999, Reply-To and the envelope sender are set, the wpmf_decision action fires and, in dry run, one log line is written.

- On wp_mail_succeeded or wp_mail_failed, state is dropped and a failure is logged.

The modes, in short: respect keeps any explicit From. align keeps one on your domain and replaces one on another domain with your identity. override replaces all, and in both of the replacing modes the original address moves to Reply-To.

WordPress reuses one PHPMailer object for every message in a request and never resets its Sender. The plugin remembers the value it set and treats it as empty on the next message, so a sender from message one never leaks into message two. It never adds a Return-Path header, because receiving servers set that from the envelope.

The quick start from the README:

define( 'WPMF_FROM', 'mail@example.org' );
define( 'WPMF_FROM_NAME', 'Example News' );

wp mail-from show
wp mail-from show --message-from="Visitor <visitor@example.net>"

## Guard rails

- Every failure fails open, towards working mail. An invalid configured address falls to the next source. If every source is invalid, core values are kept and an error is logged. An unknown mode uses the default. A logging failure is ignored.

- An address is used only if it passes is_email(), has no line breaks, is at most 254 characters, has a domain with a dot and is not an IP literal. Names lose control characters and are capped at 255 characters. Filter results go through the same checks.

- An explicit From that is not a valid address is replaced, because passed through it would make PHPMailer throw and the message would be lost.

- Logs never contain recipients, subjects or bodies, and a visitor's address is masked.

- On multisite, a super admin can lock fields. A site administrator can save only an address on the site's own domain, or on a domain the network allows, so one site cannot send as another.

- Must-use installation is the recommended route, because a mail identity that can be deactivated from wp-admin will be, by accident, on the day it matters.

- An SMTP plugin in the default defer mode wins on From. stand-aside changes nothing and only reports.

## What review changed

The reviewer's comment lists these fixes before the merge, each with a test:

- An escaping gap. settings_errors() prints messages as HTML, and the site settings error quoted the rejected input unescaped. The message is now escaped first.

- Network locks were silently dropped. Saving Network Settings replaced the whole locked list with the ticked boxes, so a lock on a field with no box on the screen was lost. Off-screen locks are now kept.

- wp mail-from set now warns when the network has locked the field, since the site value is then ignored.

- The README now calls the SMTP plugin markers best effort, because they were not checked against those plugins' source.

## Limits and what is next

- Mail sent outside wp_mail(), through direct PHPMailer use, PHP mail() or external APIs, is not touched.

- A replacement wp_mail() may ignore the From filters. The plugin reports it but cannot change it.

- Alignment is relaxed and uses no public suffix list, so on a co.uk site an address at co.uk would count as aligned.

- The plugin cannot know that a mailbox exists. A derived address is flagged so you can check.

- It does not touch DNS. You still need SPF, DKIM and DMARC at your relay.

- The reviewer flagged an open question. In respect mode, a kept visitor From also becomes the envelope sender when none is set, as the PRD says. With the PHP mail() transport that sends bounces to the visitor. A later release may fall back to the configured address for the sender.

- Must-use plugins have no uninstall hook, so the README gives a wp mail-from reset --yes step to run before removing the files.

Test status: this is v0.1.0, tested on stubs and mocks. At review, 131 tests passed with PHPStan level 8 and phpcs clean. They ran against stubs, not a live WordPress, and the readme file's "Tested up to" line has not been confirmed on a real install. CI has not yet run on GitHub, because the token lacked the scope to push it. There are no open issues.

## Install

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/wp-mail-from.

composer require indianopinion/wp-mail-from

It needs WordPress 6.4 or later and PHP 8.1 or later, on a single site or multisite. The package type is wordpress-muplugin. For a must-use install, put the plugin directory in wp-content/mu-plugins/ and copy the one-file loader from mu-loader/ next to it. It also works as a normal plugin from the release zip.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [wp-mail-from on GitHub](https://github.com/IndianOpinion/wp-mail-from)

Canonical: https://indianopinion.org/blog/open-source/wp-mail-from/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
