Use Royal MCP with MailPoet
MailPoet sends newsletters from inside WordPress. From Royal MCP 1.5.15, an AI agent such as Claude or ChatGPT can do the routine work with you: check your lists, add or update a subscriber, write a draft from your latest posts, send you a test, schedule the newsletter and read how it performed afterwards. Sending real email to real people is the one step that cannot be taken back, so it sits behind a confirmation step that shows you the exact number of recipients and the subject before anything goes out. This guide explains the twelve tools, walks through a complete newsletter, and covers safety, privacy and troubleshooting.
The twelve MailPoet tools
The tools appear when MailPoet is active. Six read, and six make changes. They fall into three groups.
Lists and subscribers
| Tool | What it does | Changes the site? |
|---|---|---|
mailpoet_list_lists | Every list with its subscribed, unconfirmed, unsubscribed, inactive and bounced counts. | No |
mailpoet_list_subscribers | Pages through subscribers, optionally of one list and one status, up to 100 at a time. | No |
mailpoet_get_subscriber | One subscriber by ID or email address: status, lists, custom fields, tags and dates, as asked for. | No |
mailpoet_save_subscriber | Adds a subscriber or updates one: email, name, custom fields and the lists they belong to. | Yes, with undo |
mailpoet_set_subscriber_lists | Subscribes one person to lists, unsubscribes them from lists, or both. | Yes, with undo |
Newsletters
| Tool | What it does | Changes the site? |
|---|---|---|
mailpoet_list_newsletters | Your emails, newest change first, filtered by type and status (draft, scheduled, sending, sent). | No |
mailpoet_get_newsletter | One email: subject, preview text, sender, lists, status, a short summary of the content, and recipient_count, the number of subscribers it would go to right now. | No |
mailpoet_save_draft | Creates a standard newsletter draft or edits one: subject, preview text, sender, reply-to, lists and content. | Yes, with undo |
Testing, sending and results
| Tool | What it does | Changes the site? |
|---|---|---|
mailpoet_send_test | Sends a test of a draft to you or your team, the way MailPoet’s own preview does. | Sends a test email |
mailpoet_schedule_newsletter | Sends a draft to its lists now, or schedules it for later, behind the confirmation step. | Sends email |
mailpoet_cancel_scheduled | Cancels a scheduled newsletter before it starts. It becomes a draft again and nothing is sent. | Yes |
mailpoet_get_newsletter_stats | Results of a sent newsletter: sent count, opens, clicks, unsubscribes, bounces, rates, the ten most clicked links, and WooCommerce revenue when MailPoet tracks it. | No |
A worked example: from posts to a scheduled newsletter
Say you ask: “Draft a newsletter from this week’s posts, send me a test, then schedule it for Tuesday 9am.” Here is what happens, and where you stay in control.
The draft
The AI client reads this week’s posts with Royal MCP’s post tools, writes a subject, preview text and a short summary of each post with a link, and saves it with mailpoet_save_draft. The content goes into MailPoet’s blank one-column template, which keeps MailPoet’s unsubscribe footer. Nothing is sent, and the reply includes an undo token.
The test
It sends a test with mailpoet_send_test to the site’s admin email. Read it in your inbox and ask for changes; each edit is another draft save. You can also open the draft in MailPoet and finish it there.
The confirmation
Before scheduling, the client reads the draft with mailpoet_get_newsletter and should show you what will go out, for example: “‘This week on the blog’ will go to 1,248 subscribers on the Customers list, on Tuesday at 9:00. Shall I schedule it?” Check the number and the subject. If either looks wrong, say so and nothing is scheduled.
The schedule
When you agree, the client calls mailpoet_schedule_newsletter with confirm: true, the recipient count you saw (expected_recipients), the subject you saw (expected_subject) and the send time. Royal MCP counts the recipients again and compares the subject. Only when both match exactly is the newsletter scheduled. The reply gives the scheduled time and how to cancel.
If three people joined the list between the two steps, the count is now 1,251, not 1,248. The call is refused, nothing is scheduled, and the reply carries the new number so the client can ask you again. The same happens if the subject was changed in the meantime. That is the point of the confirmation step: it protects against mistakes such as the wrong list, a stale subject or an unexpectedly large audience, because you approve exact figures rather than a vague “send it”.
The send time is a full date and time with a time zone, such as 2026-11-10T09:00:00+01:00. The client turns “Tuesday 9am” into one, so say which time zone you mean if it is not obvious. A send can be scheduled from a minute ahead up to 30 days ahead; leave the time out to send now.
Working with subscribers
Royal MCP follows MailPoet’s own sign-up rules and never works around them:
- Confirmation (double opt-in). When your site asks new subscribers to confirm, anyone added to a list gets MailPoet’s confirmation email and stays unconfirmed until they click it. Royal MCP never marks anyone as confirmed.
skip_confirmationis accepted only when MailPoet’s sign-up confirmation is switched off. Royal MCP sends at most three confirmation emails to the same address per day. - No re-subscribing. Someone who unsubscribed or bounced is never put back on a list, and nor is anyone who unsubscribed from that list, is inactive or is in the trash. They can sign up again through one of your MailPoet forms.
- Ordinary lists only. MailPoet keeps its WordPress Users and WooCommerce Customers lists in step with your site itself, so the tools only change membership of the lists you created. For a WordPress user, MailPoet takes the name and email from the user account; the reply tells you if a change was not kept.
- Exact list sets. When
mailpoet_save_subscriberis given lists, those become the subscriber’s lists and they are unsubscribed from the others. To add or remove one list without touching the rest, ask formailpoet_set_subscriber_lists.
Drafts, tests and the two MailPoet editors
MailPoet has a classic drag-and-drop editor and a newer block editor. Royal MCP writes content for the classic editor: headings, paragraphs, links, lists and images, with scripts and unsafe markup removed. MailPoet shortcodes such as [subscriber:firstname | default:there] work. A draft that already has content is only replaced when the request says so, and undo can put the earlier content back.
An email made in the new block editor can still have its subject, preview text, sender and lists changed, but its content can only be edited in MailPoet. The AI client will tell you so rather than overwrite it.
Tests can be sent for standard newsletter drafts only, to up to five addresses at a time: the site’s admin email (the default) or the email address of a user on this site who can edit posts. Other addresses are refused, so a test cannot be used to send your newsletter to outsiders. Each site can send up to 20 test emails per hour. Personalisation in a test, such as the first name, is filled with your own details as the admin who asked for it.
Safety controls
Before a newsletter is sent or scheduled, Royal MCP refuses when:
- the email is not a standard newsletter draft;
- it has no subject, no lists or no content;
- its lists have no subscribed members;
confirmis nottrue, or the recipient count or subject differs from what you confirmed;- MailPoet’s sending is paused or no sending method is set up;
- the site is in read-only mode.
MailPoet then runs its own checks before it queues the send. A send that starts now reports the number of recipients MailPoet actually queued. For a newsletter scheduled through Royal MCP, MailPoet counts the recipients again when sending starts; if there are more than 10% above the number you confirmed (at least 5 more), Royal MCP pauses the send before any email goes out, and mailpoet_get_newsletter shows the reason. If an administrator resumes it in MailPoet > Emails, it continues to everyone. Newsletters scheduled outside Royal MCP are not touched. A scheduled send can be cancelled with mailpoet_cancel_scheduled until it starts. A send that has started can only be paused, in MailPoet > Emails.
Undo. Subscriber changes and draft saves return an undo token that works once and lasts 72 hours by default. Undo restores the subscriber’s earlier details and lists, or deletes a subscriber the change added, and restores a draft, or deletes a draft the change created. Undo never re-subscribes someone who has since unsubscribed, bounced or gone inactive. If the subscriber or draft changed again after your change, undo stops and explains why; you can then ask to undo anyway, and even then nobody who unsubscribed, bounced or went inactive is re-subscribed. Sends and tests cannot be undone, and neither can confirmation emails already sent.
Who may send at all. The confirmation step guards against mistakes; your settings decide which agents may send in the first place. Read-only mode and a Read-only access level for a connection refuse all six MailPoet tools that change something, while the six read tools keep working. Drafts only and a Drafts only access level still allow mailpoet_save_draft, because a draft reaches nobody until it is sent, and refuse the other five. Undoing a draft save works there too, but asking to undo anyway does not. For browser agents, you can leave tools such as mailpoet_schedule_newsletter out under Tools browser agents can use. Royal MCP Pro adds per-tool AI permissions, and many AI clients let you turn individual tools off in their own settings. If you manage sites through Royally, its approvals apply to these tools too.
Privacy and permissions
Only administrators who can also manage MailPoet can use these tools, whatever your “who can connect” settings allow. MailPoet’s own permissions apply on top: managing lists, managing subscribers, or managing emails.
Subscriber email addresses are returned to that administrator’s AI client when it asks for them, and subscriber reads return only the field groups requested. IP addresses and subscription tokens are never returned. Email addresses are kept out of Royal MCP’s activity log and its Recent Changes screen, which show “email hidden” where an address changed. Newsletter statistics are totals only and never name a subscriber.
Troubleshooting
“MailPoet’s sending is paused” or “sending method is not set up”
Open MailPoet > Emails and resume sending, or finish the sending setup under MailPoet > Settings > Send With. Then ask the client to try again.
“Nothing was sent: the newsletter would go to N subscriber(s)”
The recipient count changed between confirming and sending, usually because people joined or left a list, or the draft’s lists were changed. Check the new number the client shows you and confirm again if it is right.
“Paused by Royal MCP”
MailPoet counted clearly more recipients when the send started than you confirmed, so Royal MCP paused it before sending. Check the lists in MailPoet, then resume the send in MailPoet > Emails to send to everyone, or cancel it there.
“This email was made in MailPoet’s new block editor”
Its content can only be edited in MailPoet. Ask the client to change the subject, preview text, sender or lists, or to create a new draft, which uses the classic editor.
“This is not supported on MailPoet” and a version number
The newsletter, test, scheduling and statistics tools use parts of MailPoet that change between releases, so they run only on MailPoet 5.44 up to, but not including, 6.0. They are tested with MailPoet 5.44. The list and subscriber tools use MailPoet’s public interface. Update Royal MCP when a newer MailPoet is out.
A send on a staging site never goes out
MailPoet holds its queue on sites it does not treat as production until sending is allowed in its settings. The reply mentions this when it applies.
“You do not have permission to use this MailPoet tool”
Connect the AI client from an administrator account that can manage MailPoet.
Frequently asked questions
Can the AI agent send a newsletter without my approval?
A send needs confirm: true plus the exact recipient count and subject you were shown, and Royal MCP checks both against the live newsletter. That protects against mistakes. To stop an agent from sending at all, use read-only mode or a Read-only or Drafts only access level; Royal MCP Pro’s per-tool AI permissions can also switch the scheduling tool off.
Can a test email go to anyone?
No. Tests go to the site admin email or to users of the site who can edit posts, up to five addresses at a time and 20 test emails per site per hour.
Will Royal MCP add someone who unsubscribed?
No. People who unsubscribed, bounced, are inactive or are in the trash are never added back to a list, and undo never re-subscribes them. They can sign up again through a MailPoet form.
Can I undo a send?
No. A scheduled send can be cancelled until it starts, and a running send can be paused in MailPoet. Subscriber changes and draft edits can be undone for 72 hours by default.
Which versions do I need?
Royal MCP 1.5.15 or later with MailPoet active. The newsletter tools run on MailPoet 5.44 up to, but not including, 6.0 and are tested with MailPoet 5.44.