Skip to content

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

  1. A member connects their own mailbox, from their WordPress profile page, in two clicks and an OAuth consent screen. No admin involvement per member.
  2. Other code tags a message for that member. wp_mail() calls carrying an X-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 untagged wp_mail() call — is left alone.
  3. The site's admin registers an app per provider, once. Everything after that is self-service for members.
  4. 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 (bare localhost is 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() hooks pre_wp_mail at priority 20, after the member-mailbox divert at 10, and returns whatever an earlier handler returned. WordPress runs every pre_wp_mail callback 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 the wp_mail filter), 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 fires wp_mail_failed and returns false, as a failed wp_mail() would. The active transport's name goes to core on cpm_mail_transport_label.
  • Delivery feedback. A transport implementing Club_Mailer_Feedback_Transport registers its webhook route on rest_api_init — whether or not it is active, so feedback for mail already sent still lands — and reports outcomes with CPM_Platform::record_email_delivery(), mapped onto CPM_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 the club_mailer_transports filter. Club_Mailer_Message::from_atts() reads $atts the way wp_mail() does — the From address through the wp_mail_from filters included — so the class only builds its own request. Its settings live under its id in the club_mailer_transport option.

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 with function_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/