Run MailPoet commands with WP-CLI

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:

  1. Upload the CSV file to your server.
  2. 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.
  3. Run the import with the options you need: wp mailpoet import subscribers.csv --segments="Weekly newsletter" --tags="Event signups".
  4. 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, or inactive.
  • --update-existing: updates the details of subscribers that already exist.
  • --existing-status: the status to set on existing subscribers: dont_update (default), subscribed, unsubscribed, or inactive. 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_consent column accepts granted, denied, or unknown. A blank cell keeps the stored value.
  • A status column sets the status of new subscribers row by row. Rows with a blank or unusable status, such as bounced, use the --status value.
  • 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 --segments to 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, and cli tasks. Use --status (scheduled, running, cli, completed, cancelled, paused, invalid, or all), --type, --limit (default 50), and --format (table, csv, json, ids, or count). 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 --at or --in=<seconds> to schedule it, --priority (high, medium, or low), --force to add it when a task of that type is already scheduled, and --run to run it immediately. The sending and stats_notification types can’t be added. Example: wp mailpoet cron add bounce --in=3600 --priority=high.
  • wp mailpoet cron cancel <task-id>: cancels a scheduled, paused, or cli task. Cancelling a cli task 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:

  1. Run wp mailpoet migrations status. The output counts migrations that are new, completed, started, and failed, and lists any failed migration with its error.
  2. 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 commandUse instead
wp mailpoet:migrations:runwp mailpoet migrations run
wp mailpoet:migrations:statuswp mailpoet migrations status
wp mailpoet:email-editor:create-templateswp mailpoet email-editor create-templates

Related articles