MailerPress adds commands to WP-CLI (the WordPress command-line tool) under wp mailerpress. Use them to check the IMAP bounce mailbox, recover database migrations and repair contact access tokens, for example when the WordPress admin is not available. You need SSH access to the server. The commands are part of MailerPress (free); MailerPress Pro is not required.
Before you start
- Install WP-CLI on your server and run the commands from your WordPress root folder, or add
--path=/path/to/wordpress. On multisite, add--url=to target a site. - Run
wp help mailerpressto list the commands. They have no built-in help text: use this page as the reference. - Some diagnostic commands print their messages in French, whatever the language of your site.
- Back up your database before running a command that changes data (migrations, tokens, marking contacts as bounced).
Bounce mailbox commands
These commands work with the IMAP bounce mailbox (the mailbox that receives undeliverable emails) you set up with Enable bounce tracking (IMAP) in the Custom SMTP settings, under MailerPress > Integrations > Email Service Providers. If no mailbox is configured, they stop with a message saying the bounce configuration is missing or invalid.
Once configured, MailerPress checks the mailbox every 12 hours through Action Scheduler (scheduled action mailerpress_check_bounces). Each check connects over SSL, reads the unread messages of the INBOX folder, finds the original recipient of each bounce, marks the matching contact as bounced and marks the message as read.
| Command | What it does |
|---|---|
wp mailerpress bounce status | Shows the mailbox settings (email, host, port, username), whether the automatic check is scheduled and when it runs next. |
wp mailerpress bounce check | Clears the bounce log, runs a check now and prints the new log entries. |
wp mailerpress bounce logs [--limit=<number>] | Prints the most recent bounce log entries, newest first. Default: 100 entries. |
wp mailerpress bounce clear-logs | Empties the bounce log. |
wp mailerpress bounce:parse | Runs a bounce check now, without clearing or printing the log. |
wp mailerpress bounce:schedule-run-now | Runs a bounce check now and prints the error details if it fails. |
wp mailerpress bounce:schedule-status | Checks the configuration, the scheduled action, the next run and the interval, then lists the last 10 bounce-check actions with their status and the error message of failed ones. |
wp mailerpress bounce:schedule-reset | Deletes every scheduled bounce-check action and its logs, then schedules a new recurring check that starts now and runs every 24 hours. |
wp mailerpress bounce:stats | Shows how many contacts you have per subscription status and the 10 most recently bounced contacts. |
wp mailerpress bounce:test [--debug] [--yes] | Tests the IMAP connection, lists the mailbox folders, analyzes each unread INBOX message and shows the detected recipient and whether that contact exists. It then asks for confirmation before marking the detected contacts as bounced. --debug also prints the headers and the first 2,000 characters of each message; --yes answers the confirmation automatically. |
wp mailerpress bounce:dump | Prints the subject, all headers, the full body and every email address found in each unread INBOX message. |
wp mailerpress bounce:mark-unseen | Marks every message of the INBOX folder as unread, so the next check processes them again. |
bounce:dump and bounce:test --debug display the content of real emails, including personal data. bounce:mark-unseen changes every message of the mailbox, not only bounces. Use them on a dedicated bounce mailbox only.
Troubleshoot bounce detection
- Run
wp mailerpress bounce statusto confirm that the mailbox is configured and the check is scheduled. - Run
wp mailerpress bounce:testto check the connection and see which recipients MailerPress detects in the unread messages. - If no check is scheduled or the scheduled actions keep failing, run
wp mailerpress bounce:schedule-reset. - Run
wp mailerpress bounce check, thenwp mailerpress bounce:statsto see the result.
Database migration commands
MailerPress updates its database tables with migrations (update scripts) that run after a plugin update. In most cases, fix the database with MailerPress > Tools > Database Repair (see Repair your MailerPress database). Use the commands below when the admin is not reachable or when our support team asks you to.
| Command | What it does |
|---|---|
wp mailerpress migrations:status | Shows whether migrations are locked, the number of failed and running migrations, and the error message of each failed migration. |
wp mailerpress migrations:unlock | Releases the migration lock, for example after a migration was interrupted by a timeout. |
wp mailerpress migrations:reset-failed | Sets failed migrations back to pending and releases the lock. It does not run them. |
wp mailerpress migrations:force-run | Resets failed and stuck migrations, releases the lock and runs all pending migrations. |
wp mailerpress migrations:force-reexecute <file> | Marks one migration as pending so that it runs again with the next migrations:force-run. Pass the migration file name exactly as stored, including .php. |
wp mailerpress migrations:add-file-hash-column | Adds the file_hash column to the migration tracking table if it is missing on an older installation. |
A typical recovery sequence:
wp mailerpress migrations:status
wp mailerpress migrations:force-run
wp mailerpress migrations:statusTo run a single migration again, use the file name shown by our support team or in the migration error:
wp mailerpress migrations:force-reexecute 2026_09_15_100000_fix_legacy_anonymous_tracking_index.php
wp mailerpress migrations:force-runAccess token commands
Each contact has a unique access token (a secret key) that MailerPress uses in personal links, such as the link to manage a subscription.
| Command | What it does |
|---|---|
wp mailerpress tokens:generate | Creates a unique access token for every contact that does not have one, by batches of 200 contacts. If the access_token column does not exist yet, run the migrations first. |
wp mailerpress tokens:cleanup-scheduler | Removes the leftovers of the former background token generation: the mailerpress_access_tokens_scheduled option and the mailerpress_generate_access_tokens scheduled actions. |
Internal commands
wp help mailerpress also lists make:migration, fixtures:generate and debug:container. These development tools are for the MailerPress team: make:migration writes a new file into the plugin folder, fixtures:generate creates test users and enabled test automations, and debug:container inspects the plugin’s internal service container. Do not run them on a production site.
To run background tasks from the command line, see How to Set Up a WordPress Cron Job from Your Server.