You run MailPoet commands with WP-CLI from your server’s command line to import subscribers from a CSV file, manage MailPoet cron tasks, and run MailPoet database migrations. This guide lists each wp mailpoet command with its main options and an example.
About MailPoet WP-CLI commands
The wp mailpoet command group runs MailPoet tasks from the command line instead of the WordPress dashboard. Running wp mailpoet lists four subcommands: cron, email-editor, import, and migrations.
You need WP-CLI installed on your server and shell access to your WordPress installation. Run each command from your site’s WordPress directory.
MailPoet 5.33.1 and later separate the command and each subcommand with a space, for example wp mailpoet migrations run. The older colon-separated names, such as wp mailpoet:migrations:run, still work but are deprecated. See Deprecated colon-separated commands.
Import subscribers from a CSV file
The wp mailpoet import command imports subscribers from a CSV file stored on your server. It is available in MailPoet 5.31.0 and later. To import subscribers in the dashboard instead, see Importing Subscribers with CSV Files.
To import a CSV file, follow these steps:
- Upload the CSV file to your server.
- Check the file with a dry run:
wp mailpoet import subscribers.csv --dry-run. The dry run reports how many rows have a valid email address and writes nothing. - Run the import with the options you need:
wp mailpoet import subscribers.csv --segments="Weekly newsletter" --tags="Event signups". - Read the summary. It shows how many subscribers MailPoet created and updated, out of the rows it read.
The command takes the file path, then these options:
--segments: comma-separated list IDs or names to add subscribers to. MailPoet creates names that don’t exist.--status: the status for new subscribers:subscribed(default),unconfirmed,unsubscribed, orinactive.--update-existing: updates the details of subscribers that already exist.--existing-status: the status to set on existing subscribers:dont_update(default),subscribed,unsubscribed, orinactive. The default leaves each existing subscriber’s status unchanged.--tags: comma-separated tag names to assign to imported subscribers. MailPoet creates tags that don’t exist.--batch-size: how many subscribers MailPoet processes per batch. The default is 2,000.--dry-run: validates the file and reports what would be imported, without writing anything.
CSV file requirements
The first row of the CSV file must be a header row with an email column. Other columns can use these MailPoet field names: first_name, last_name, subscribed_ip, created_at, confirmed_at, confirmed_ip, tracking_consent, tracking_consent_method, and tracking_consent_copy. Columns can also use the name of an existing custom field, or the column labels that a MailPoet export writes.
- MailPoet stops the import if a column name isn’t recognized, or if two columns map to the same field.
- The
tracking_consentcolumn acceptsgranted,denied, orunknown. A blank cell keeps the stored value. - A
statuscolumn sets the status of new subscribers row by row. Rows with a blank or unusable status, such asbounced, use the--statusvalue. - MailPoet skips rows with a different number of columns than the header and lists each skipped line in the output.
- MailPoet ignores export-only columns, such as List. Use
--segmentsto choose lists.
Cron task commands
The wp mailpoet cron commands list, add, run, trigger, and cancel MailPoet cron tasks. For background on how MailPoet schedules tasks, see Newsletter Task Scheduler (cron). Each command uses a task type. Run wp mailpoet cron types to see the valid types.
wp mailpoet cron list: lists tasks. By default it shows scheduled, running, andclitasks. Use--status(scheduled,running,cli,completed,cancelled,paused,invalid, orall),--type,--limit(default 50), and--format(table,csv,json,ids, orcount). Example:wp mailpoet cron list --status=running.wp mailpoet cron types: lists every task type and its attributes. Example:wp mailpoet cron types --format=json.wp mailpoet cron trigger <type>: marks the next scheduled task of that type as due now. MailPoet’s cron runner starts it on its next tick. Add--task-id=<id>to target one task, including a paused one. Example:wp mailpoet cron trigger sending.wp mailpoet cron run <type>: runs the due tasks of that type inside your WP-CLI session, with the 20-second execution limit lifted. Add--task-id=<id>to run one task, or--timeout=<seconds>to set a limit. Batched tasks process one batch per run, so run the command again to continue. Example:wp mailpoet cron run log_cleanup.wp mailpoet cron run-daemon: runs one full pass over all cron workers. Add--timeout=<seconds>to set a limit. The command exits with an error if any worker fails. Example:wp mailpoet cron run-daemon --timeout=30.wp mailpoet cron add <type>: schedules a new task. By default, the task is due now at low priority. Use--ator--in=<seconds>to schedule it,--priority(high,medium, orlow),--forceto add it when a task of that type is already scheduled, and--runto run it immediately. Thesendingandstats_notificationtypes can’t be added. Example:wp mailpoet cron add bounce --in=3600 --priority=high.wp mailpoet cron cancel <task-id>: cancels a scheduled, paused, orclitask. Cancelling aclitask releases a task that is stuck in a CLI run. Running and completed tasks can’t be cancelled. Example:wp mailpoet cron cancel 42.
Run and check database migrations
MailPoet database migrations update MailPoet’s database tables. They are not the same as moving MailPoet to another site. For that, see How to Migrate MailPoet Database Tables.
To check and run migrations, follow these steps:
- Run
wp mailpoet migrations status. The output counts migrations that are new, completed, started, and failed, and lists any failed migration with its error. - Run
wp mailpoet migrations run. MailPoet runs each new migration and shows how long it took. If none are new, the command reports that there is nothing to run.
Email editor command
The wp mailpoet email-editor create-templates command creates one email in the new Email Editor, named “Testing Email With Core Blocks”. The email contains WordPress core blocks in different configurations. Each run creates another copy.
Deprecated colon-separated commands
MailPoet 5.33.1 replaced the colon-separated command names with space-separated ones. The old names print a deprecation warning, then run the new command. Switch scripts and scheduled jobs to the new names.
| Deprecated command | Use instead |
|---|---|
wp mailpoet:migrations:run | wp mailpoet migrations run |
wp mailpoet:migrations:status | wp mailpoet migrations status |
wp mailpoet:email-editor:create-templates | wp mailpoet email-editor create-templates |