MailPoet Documentation

MailPoet is an email marketing solution for WordPress that allows you to create, send, and manage email campaigns directly from your dashboard.

Core Capabilities:

• Newsletter Management: Build responsive newsletters using a drag-and-drop builder and manage subscriber lists.
• Subscription Forms: Add signup forms to your site via shortcodes, popups, fixed bars, slide-ins, or exit intent.
• Automations: Set up automatic blog post notifications, welcome emails, and advanced behavior-based automations (requires paid plan).
• WooCommerce Integration: Automate emails for abandoned carts, first purchases, specific products/categories, and order status changes. You can also customize WooCommerce transactional emails.
• Segmentation: Segment subscribers based on behavior, interests, or WooCommerce data (country, order count, spend, etc.).
• Email Delivery: Use the MailPoet Sending Service for high-speed, reliable delivery (up to 50,000 emails per hour) with built-in SPF/DKIM authentication.

The server facilitates communication between an AI agent and the local MailPoet development environment using three main components:

1. AI Agent (Claude/etc.): Communicates via stdio with the TypeScript MCP server.
2. TS MCP Server: Executes shell commands and HTTP calls to interact with the environment.
3. Local Environment:
   • WordPress: Runs on :8888 with the mailpoet-dev-companion mu-plugin.
   • Mailpit: Runs on :8082 for capturing outgoing mail.
   • MailPoet Core: Used for tests and QA.

Authentication is handled by a shared secret file (.wp-env/.mailpoet-dev-companion-secret) which is mapped into the WordPress container via .wp-env.json. The mu-plugin reads this secret to authorize requests sent to the /wp-json/mailpoet-dev/v1/ endpoints.

┌────────────────────┐     stdio     ┌─────────────────────┐
│   Claude / agent   │ ───────────▶  │  TS MCP server      │
└────────────────────┘               │  (this package)     │
                                     └──────┬──────────────┘
                                            │ shell-out (pnpm/Robo, docker)
                                            │ HTTP (Mailpit, companion)
                              ┌─────────────┼─────────────────────┐
                              ▼             ▼                     ▼
                         mailpoet/       Mailpit :8082      WordPress :8888
                         (tests, QA)     (captured mail)    + companion mu-plugin
                                                            (DI → repositories)

When using wp mailpoet cron run, run-daemon, or add --run, tasks are executed directly inside the WP-CLI process instead of the site's web-request daemon.

Key behaviors:

• Execution Limits: The standard 20-second web-triggered execution limit is lifted. Tasks run to completion in a single invocation. You can restore a cap using the --timeout flag.
• Task Claiming: When a task is run via CLI, it is assigned a dedicated cli status. This status makes the task invisible to the site daemon, preventing the web worker from picking up or rescheduling the same task simultaneously.
• Task Outcomes:
  • Completed: Status becomes completed. A meta.cli breadcrumb containing the pid and started_at time is recorded.
  • Partial/Error: If the worker throws an error or fails to finish, the task is handed back to the site cron with a scheduled status (due now) so the daemon can retry it.
  • Requirements not met: The task is removed.

This mechanism ensures that long-running CLI tasks are not 'rescued' or stolen by the daemon's stuck-task recovery logic.

When processing a subscription form submission (e.g., from $_POST data), follow this workflow to handle both new and existing subscribers:

1. Instantiate the API: Use \MailPoet\API\API::MP('v1').
2. Map Data: Map your input data (like $_POST) to the subscriber field IDs retrieved via getSubscriberFields().
3. Check Existence: Attempt to retrieve the subscriber using getSubscriber($email).
4. Handle Logic:
   • If the subscriber does not exist (the call throws an exception or returns null), use addSubscriber($subscriber, $list_ids) to create them.
   • If the subscriber already exists, use subscribeToLists($email, $list_ids) to add them to the requested lists.
5. Error Handling: Wrap the process in a try/catch block to capture exceptions thrown by the API.

<?php

add_action('init', function () {
  if (!class_exists(\MailPoet\API\API::class)) {
    return;
  }

  try {
    // Get MailPoet API instance
    $mailpoet_api = \MailPoet\API\API::MP('v1');

    // Fill subscribed data from $_POST
    $subscriber = [];
    $subscriber_form_fields = $mailpoet_api->getSubscriberFields();
    foreach ($subscriber_form_fields as $field) {
      if (!isset($_POST[$field['id']])) {
        continue;
      }
      $subscriber[$field['id']] = $_POST[$field['id']];
    }
    $list_ids = $_POST['list_ids'];

    // Check if subscriber exists. If subscriber doesn't exist an exception is thrown
    try {
      $get_subscriber = $mailpoet_api->getSubscriber($subscriber['email']);
    } catch (\Exception $e) {
      $get_subscriber = false;
    }

    if (!$get_subscriber) {
      // Subscriber doesn't exist let's create one
      $mailpoet_api->addSubscriber($subscriber, $list_ids);
    } else {
      // In case subscriber exists just add him to new lists
      $mailpoet_api->subscribeToLists($subscriber['email'], $list_ids);
    }
  } catch (\Exception $e) {
    $error_message = $e->getMessage();
  }
});