Club Mailer¶
Lets each WordPress user connect their own mail provider — Outlook / Microsoft 365 or Gmail /
Google Workspace — and send tagged wp_mail() messages as themselves, through the provider's own
API — not through the site's SMTP or transactional-mail account. A member connects one provider
at a time; connecting a second one replaces the first.
It also sends the rest of the site's mail through a delivery service, when one is chosen: a
site-wide transport. Elastic Email is the one built in. Club Player Manager itself is
provider-neutral — it hands everything to wp_mail() — so this is where its Elastic Email sending
lives now.
It is a companion to Club Player Manager, not part of it. It stores nothing about players, guardians or squads — only which mailbox each WordPress user has connected — and works whether or not the calling code is Club Player Manager itself.
What it does¶
- A member connects their own mailbox, from their WordPress profile page, in two clicks and an OAuth consent screen. No admin involvement per member.
- Other code tags a message for that member.
wp_mail()calls carrying anX-Club-Mailer-Send-As: <user id or email>header are diverted through that member's mailbox, sent from their address, and land in their own Sent Items. Everything else — core, WooCommerce, MailPoet, and every untaggedwp_mail()call — is left alone. - The site's admin registers an app per provider, once. Everything after that is self-service for members.
- Everything else can go through a site-wide transport. With one chosen, every
wp_mail()the member-mailbox divert did not send goes out through that service's HTTP API instead of default WordPress mail — over HTTPS on port 443, so it works on hosts that block outbound SMTP. See Site-wide transports.
Requirements¶
- WordPress 6.9+, PHP 8.2+
- Pretty permalinks (Settings → Permalinks, anything but "Plain") — each OAuth redirect URI is a clean, query-free URL
- HTTPS — both Entra and Google Cloud Console reject
http://redirect URIs for a web app (barelocalhostis the one exception) - No Composer dependencies, and no build step
Setup¶
Settings → Club Mailer walks through registering a Microsoft Entra app (tenant, client ID,
client secret) and/or a Google Cloud OAuth client (client ID, client secret), and gives the exact
redirect URI each one needs pasted into it. A club only using one provider can leave the other's
fields blank — members are only offered a connect button for a provider the admin has configured.
Credentials can be stored on the settings screen, or pinned outside the database with
CLUB_MAILER_TENANT, CLUB_MAILER_CLIENT_ID, CLUB_MAILER_CLIENT_SECRET (Outlook) and
CLUB_MAILER_GOOGLE_CLIENT_ID, CLUB_MAILER_GOOGLE_CLIENT_SECRET (Gmail) constants in
wp-config.php — any of these overrides its stored value and the settings screen says so.
Client secrets, the Elastic Email API key and the Elastic Email webhook secret are encrypted
before they are stored, with the site's WordPress security keys. If a host changes those keys, the
saved values can no longer be decrypted: the settings screen says so, and they must be entered
again. The webhook secret can't be entered, so the screen offers Create a new URL when I save
instead, and the new URL then has to be pasted into Elastic Email. Until then the webhook answers
503 rather than 498. Secrets defined in wp-config.php are never copied into the database.
Once that is done, a member connects from Users → Profile → Send mail as yourself.
The Site-wide sending card at the top of the same screen chooses the transport — Default WordPress mail or Elastic Email — and holds Elastic Email's API key and its delivery feedback webhook URL. Club Player Manager's Email Settings → Sending shows which one is active and links here.
Site-wide transports¶
A transport is a delivery service that sends the whole site's mail with one set of credentials — unlike a provider, which sends one member's tagged messages through their own OAuth-connected mailbox. At most one is active.
- Order.
Club_Mailer_Transports::send()hookspre_wp_mailat priority 20, after the member-mailbox divert at 10, and returns whatever an earlier handler returned. WordPress runs everypre_wp_mailcallback whatever the earlier ones answered, so this is what stops a diverted message going out twice. By then Club Player Manager has logged the message and applied its logging-only and test-mode redirects (both on thewp_mailfilter), so a transport sends the redirected copy. - Reporting back. The message id the service returns is stamped on the message's email-log row
(
CPM_Platform::current_email_log_id()/stamp_email_message_id()); a failure fireswp_mail_failedand returns false, as a failedwp_mail()would. The active transport's name goes to core oncpm_mail_transport_label. - Delivery feedback. A transport implementing
Club_Mailer_Feedback_Transportregisters its webhook route onrest_api_init— whether or not it is active, so feedback for mail already sent still lands — and reports outcomes withCPM_Platform::record_email_delivery(), mapped ontoCPM_Platform::EMAIL_DELIVERY_STATUSES. Core keeps the strongest outcome per row. - Adding one (SendGrid, Postmark, Brevo…) is one class implementing
Club_Mailer_Transport, added on theclub_mailer_transportsfilter.Club_Mailer_Message::from_atts()reads$attsthe waywp_mail()does — the From address through thewp_mail_fromfilters included — so the class only builds its own request. Its settings live under its id in theclub_mailer_transportoption.
Elastic Email¶
Sends through the v4 transactional endpoint with the X-ElasticEmail-ApiKey header, keeping To,
Cc and Bcc roles and base64-encoding attachments, and returns the TransactionID. Its notification
webhook is cpm/v1/ee-webhook/<secret> — the route and secret Club Player Manager used to serve, so
the URL already in the Elastic Email dashboard keeps working. Turn on all six notification channels
there: Bounce/Error, Complaints, Unsubscribed, Sent, Opened and Clicked.
Moving over from Club Player Manager¶
Club Player Manager used to send through Elastic Email itself (mail_method = 'api' with an
api_key, and an ee_webhook_secret). On its first load against platform 3.12+, this plugin
copies those three values once (Club_Mailer_Transports::migrate_legacy(), also run on
activation), choosing Elastic Email only if core was actually sending through it, never overwriting
a value already stored here, and then answers cpm_legacy_mail_transport_claimed so core drops its
"sending has moved" notice. Core keeps carrying its own copy through every settings save, so
whichever plugin updates first, the key is never lost.
Admin¶
Settings → Club Mailer, gated on manage_options — deliberately not widened toward
cpm_manage_all the way most other satellite screens are, because the page stores OAuth client
secrets capable of sending mail as any member who connects a mailbox.
Using it from another plugin¶
wp_mail(
'recipient@example.com',
'Subject line',
'Message body',
array( 'X-Club-Mailer-Send-As: ' . $user_id )
);
Two functions exist only while this plugin is active, so function_exists() doubles as the "is
the mailer available?" check:
club_mailer_user_connected( $user_id )— whether that user has a connected mailbox, on whichever provider they connected.club_mailer_user_address( $user_id )— the address a tagged send will come from. Often not the user's WordPress profile email; returns''when not yet known rather than falling back to it. Check withfunction_exists()separately — an older copy of this plugin may lack it.
Data model¶
No custom tables. Per member: _club_mailer_active_provider (outlook or google), and for
whichever provider that names, _club_mailer_{provider}_refresh (the encrypted OAuth refresh
token) and _club_mailer_{provider}_address (the mailbox address, best-effort, backfilled on
the next token refresh if unknown) user meta. A member connected before this plugin supported more
than one provider has no _club_mailer_active_provider meta; club_mailer_user_connected() and
club_mailer_user_address() treat that as outlook, since that was the only provider then.
Site-wide: the club_mailer_settings option, holding one sub-array of credentials per provider,
and the club_mailer_transport option — transport (the chosen id, or wp_mail), settings
(one sub-array per transport: Elastic Email's api_key and webhook_secret) and migrated.
Development¶
Everything runs from the repository root, where the shared dev tooling lives:
composer test # every plugin's suite
composer test:mailer # this plugin only
composer lint # every plugin's phpcs ruleset
composer lint:mailer # this plugin only
composer build -- club-mailer # dist/club-mailer/club-mailer-<version>.zip
Layout¶
club-mailer.php Bootstrap: constants, require order, hooks
uninstall.php Deletes the option and every member's meta
includes/
public-api.php club_mailer_user_connected()/user_address()
interface-club-mailer-provider.php The provider contract
class-club-mailer-outlook-provider.php Microsoft Graph: auth URL, token exchange,
send, mailbox address lookup
class-club-mailer-gmail-provider.php Gmail API: auth URL, token exchange, MIME send,
mailbox address lookup
class-club-mailer-settings.php Options: get() (merged over defaults, wp-config
constants win), save() — one sub-array per provider
class-club-mailer-connections.php Profile UI, connect/disconnect, each provider's OAuth
callback, the pre_wp_mail divert
interface-club-mailer-transport.php The site-wide transport contract
interface-club-mailer-feedback-transport.php Optional: delivery-feedback routes
class-club-mailer-message.php wp_mail() $atts read the way wp_mail() reads them
class-club-mailer-elastic-email-transport.php Elastic Email send + webhook
class-club-mailer-transports.php Registry, choice, pre_wp_mail send, core migration
admin/ The one settings screen, plus the orchestrator
templates/admin-settings.php
assets/css/ assets/js/
tests/Unit/ tests/Integration/ tests/Support/