Flexa Unsubscribe

Flexa Unsubscribe intercepts every email WordPress sends through wp_mail() and adds a one-click, cryptographically signed unsubscribe link. Once a recipient opts out, the plugin can hard-block any future mail to that address and log every blocked attempt for audit. Recipients can also re-subscribe themselves.

All admin screens - Dashboard, Unsubscribes, Blocked Emails, Re-subscribed, Reasons, Settings and Appearance - are a single-page React app (Vite + TypeScript + shadcn/ui + Tailwind v4) talking to a namespaced REST API. The public-facing unsubscribe and re-subscribe pages are fully themable from the Appearance screen.

The plugin hooks the wp_mail filter twice. Order matters: blocking runs first so a fully-blocked send is dropped before any footer work happens.

Both callbacks honour the exclude keywords list: if the subject contains any configured keyword (case-insensitive), that email skips both blocking and auto-append - the escape hatch for transactional mail (orders, password resets, invoices).

On the front end the plugin watches the home URL for a flexa_action query parameter (unsubscribe or resubscribe) plus an email and HMAC token, then renders the themed public page.

1. Upload the flexa-unsubscribe folder to wp-content/plugins/ (or install the .zip from the Plugins screen).
2. Activate the plugin through the WordPress “Plugins” menu.
3. On activation the plugin provisions three database tables and seeds the reasons table with three default opt-out reasons. A versioned schema upgrade then runs once per request whenever the stored schema version is behind the code.
4. Open Unsubscribe → Settings and enable auto-append and/or blocking as needed.

Persisted as flexa_tech_su_* options and exposed at GET|PUT /settings/general. Booleans travel the wire as real JSON true/false but persist as '1'/'' strings for back-compat with legacy comparisons.

Themes the public unsubscribe / re-subscribe / error pages. Exposed at GET|PUT /settings/appearance. Colours are normalised to lowercase 6-char hex; font_family is an enum; font_size must match ^\d+(\.\d+)?(px|em|rem|%)$.

Colours

Typography

Text content

Every link carries a token derived from the recipient’s address and the site’s AUTH_KEY. There is no per-link database row - the token is the proof, verified with a constant-time hash_equals() comparison.

$token = hash_hmac('sha256', $email, AUTH_KEY);

add_query_arg([
    'flexa_action' => 'unsubscribe', // or 'resubscribe'
    'email'        => urlencode($email),
    'token'        => $token,
], home_url('/'));

At the public read site $_GET['email'] and $_GET['token'] are unslashed and sanitised (sanitize_email / sanitize_text_field) before the HMAC is recomputed and compared. The HMAC token is the CSRF protection for these intentionally public links, so a WordPress nonce is deliberately not used here.

All routes are registered under /wp-json/flexa-unsubscribe/v1/. Every route uses a permission_callback of current_user_can('manage_options') - the sole exception is POST /reason, which is the public feedback submission and authenticates with the same HMAC scheme as the unsubscribe links. Authenticated requests need the WordPress auth cookie plus the X-WP-Nonce header from wp_create_nonce('wp_rest').

Shared list query parameters

The list endpoints (/unsubscribes, /blocked, /resubscribed) share a paging contract and return a uniform envelope:

{
  "items":    [ /* rows */ ],
  "total":    137,
  "page":     1,
  "per_page": 20
}

Lists & records

Reasons

Analytics & settings

The supported developer extension point is a single filter that lets you augment the config object handed to the React admin app:

add_filter('flexa_unsubscribe_js_config', function (array $config) {
    // $config carries the REST root, nonce and CSV-export nonces
    // consumed by the admin SPA. Extend it for custom UI add-ons.
    return $config;
});

The two wp_mail filter callbacks (flexa_tech_su_block_unsubscribed_emails at priority 5 and flexa_auto_append_unsubscribe_link at priority 10) are internal but documented under How it works so integrators understand ordering against their own wp_mail hooks.

Text domain flexa-unsubscribe. Both PHP strings (.mo) and the React admin’s JS strings (script-translation .json consumed via wp_set_script_translations) are localised. Seven locales ship in the box:

Regenerate the catalog with wp i18n make-pot and wp i18n make-json --no-purge --pretty-print. The JS translation files are keyed by the md5 of the built admin bundle, so re-running make-json after a rebuild is required for the admin UI to stay translated.

Export

Each list screen offers a CSV download handled via admin-post.php. There are three exports - unsubscribes, blocked emails and re-subscribed - each guarded by its own nonce (flexa_export_csv, flexa_export_blocked_csv, flexa_export_resubscribed_csv) verified with check_admin_referer(). Streaming is keyset-paginated on the primary key so memory stays flat regardless of total row count.

Import

The Unsubscribes screen accepts a CSV upload via POST /unsubscribes/import. The endpoint takes a multipart/form-data body with field file, requires manage_options plus the standard X-WP-Nonce header, and returns a per-row outcome summary.

A header row is auto-detected (case-insensitive matching on Email / Reason / Date with a few aliases). Headerless files are accepted too: if the first cell parses as an email, columns are read by position.

Dedup & safety

• Skip-on-duplicate: implemented as INSERT IGNORE on the email UNIQUE key. Existing rows are never modified - their original unsubscribed_at and reason stand. Counted under skipped_duplicate in the response.
• Limits: 2 MiB file size, 10,000 rows per import, first 100 row-level errors returned in failed[] (the failed_count field keeps climbing past 100).
• Streaming: rows are read with fgetcsv one at a time; the full file is never materialized in PHP memory.

{
  "imported":          138,
  "skipped_duplicate": 12,
  "failed_count":      2,
  "failed": [
    { "row": 7,   "email": "not-an-email", "error": "Invalid email address." },
    { "row": 142, "email": "",             "error": "Missing email." }
  ],
  "total":             152
}

Three tables are provisioned on activation:

A re-subscribe does not delete the unsubscribe row; it stamps resubscribed_at, which is what separates the “Unsubscribes” and “Re-subscribed” admin lists. The “Blocked Emails” list is an independent audit log of send attempts that were stopped - not the opt-out list itself.