Mailpuff MCP Tools Reference: All 40 AI Agent Tools

Mailpuff gives AI agents 40 MCP tools, registered as WordPress abilities under the mailpuff/ namespace. They cover subscribers, tags and segments, campaigns from first draft to final report, PostShiba sending setup, and settings. Every tool has an input and output schema, needs an administrator account, and runs the same code as the Mailpuff admin screens, so an agent and a person get the same result.

What are the tools called?

Each tool has one ability name, and the MCP name depends on the server you connect through.

Where you call it	Name to use
WordPress Abilities API (PHP or REST)	mailpuff/create-campaign
Saddle’s MCP server	saddle-mailpuff-create-campaign
MCP Adapter’s default server	mcp-adapter-execute-ability with "ability_name": "mailpuff/create-campaign"

The tables below use the short name, such as create-campaign. Setup for both servers is in Connect an AI agent to Mailpuff.

Which tools manage subscribers?

Six tools read, add and clean up subscribers. Mailpuff’s code and tools say “contact”; the admin says “subscriber”. They mean the same record.

Tool	What it does	Effect
list-contacts	Lists subscribers newest first with their status and tags. Filters by status, search, tag or segment. Up to 100 per page.	Read only
add-contact	Adds one person, optionally with a tag. Status pending sends them a confirmation email.	Changes data
import-contacts	Adds up to 500 people per call with an optional tag. subscribed needs a consent note saying how they agreed.	Changes data
list-forms	Shows every page or post with the signup block, the tags it gives and whether it uses double opt-in.	Read only
get-inactive-subscribers	Counts subscribers who got 5 or more campaigns in 180 days and opened or clicked none.	Read only
cleanup-inactive-subscribers	Tags those people for a win-back email, or unsubscribes them.	Changes data, asks first in Saddle

Which tools manage tags and segments?

A tag is a label you put on people. A segment is a saved filter that Mailpuff works out each time it’s used. Both can be a campaign’s audience.

Tool	What it does	Effect
list-audiences	Every audience a campaign can go to, with its id, how many it reaches, and which campaigns and segments use it.	Read only
create-tag	Creates a tag. public tags appear on signup forms and the preferences page.	Changes data
update-tag	Renames a tag or changes its description or visibility.	Changes data
update-tag-members	Adds or removes a tag by email (up to 500), contact id, or everyone a segment matches now.	Changes data
delete-tag	Deletes a tag and removes it from everyone. The people stay subscribed.	Changes data, asks first in Saddle
create-segment	Saves a filter on status, tags, source, customer type, search and engagement.	Changes data
update-segment	Renames a segment or replaces its whole filter.	Changes data
delete-segment	Deletes the filter only. No subscriber or tag changes.	Changes data, asks first in Saddle

Which tools write and send campaigns?

Twelve tools take a campaign from draft to sent. A new campaign is always a draft, and nothing goes to your list without send-campaign or schedule-campaign.

Tool	What it does	Effect
list-campaigns	Lists campaigns newest first, filtered by status. Up to 50 per page.	Read only
get-campaign	One campaign in full: subject, preview text, sender, audience and its size, body as blocks and text, theme, and the review and editor links.	Read only
create-campaign	Creates a draft. Only subject is required. The body goes in as blocks or HTML.	Changes data
update-campaign	Changes subject, name, preview text, sender, reply-to or audience. Never the body.	Changes data
set-campaign-content	Replaces the whole body, including edits made in the editor since.	Changes data, asks first in Saddle
list-email-themes	The eight email themes with the styles each one sets.	Read only
set-campaign-style	Changes the look: a theme, single styles, or both. Never the words.	Changes data
send-campaign-test	Sends one test copy, subject marked [Test], to the connected account’s email.	Sends email, asks first in Saddle
schedule-campaign	Schedules a send for a local date and time, at least a minute ahead.	Sends email later, needs the send switch
unschedule-campaign	Takes a scheduled campaign back to draft.	Changes data
send-campaign	Sends to the whole audience now. Sent email can’t be recalled.	Sends email, needs the send switch
stop-campaign	Halts a send in progress. Up to one batch of 50 already handed to the mail server still arrives.	Changes data

How the body is written as blocks is covered in How AI agents write emails in Mailpuff.

Which tools report results?

Tool	What it does	Effect
campaign-stats	Recipients, delivered, failed, unique opens and clicks with their rates, total clicks and unsubscribes. The same numbers as the campaign report.	Read only
get-campaign-progress	A live send’s sent, failed and pending counts, emails per minute, expected finish time, and whether it has stalled.	Read only
get-send-time	The weekday and hour your subscribers open most, from 180 days of opens. Tuesday 10:00 until there are 30 opens.	Read only

Which tools set up sending?

Eight tools connect PostShiba, verify your domain and check a campaign before it goes. No answer ever includes your API key or a secret, only the key’s last four characters.

Tool	What it does	Effect
get-delivery	How email goes out and whether it’s ready: the route, PostShiba’s limits, domains and DNS records, and warm-up progress.	Read only
connect-postshiba	Connects PostShiba with a Full access API key and Team ID that the owner pastes.	Calls PostShiba, asks first in Saddle
refresh-postshiba	Reads the account again after DNS or plan changes.	Calls PostShiba
verify-sending-domain	Asks PostShiba to check a domain’s DNS records now.	Calls PostShiba
set-warmup	Turns the 14-day warm-up for a new domain on or off.	Changes data, asks first in Saddle
disconnect-postshiba	Forgets the key and the bounce webhook.	Calls PostShiba, asks first in Saddle
send-delivery-test	Sends one short email through the current route to check delivery end to end.	Sends email, asks first in Saddle
check-send-readiness	The safe-sending checklist, optionally for one campaign. ready is true only when nothing required is open.	Read only

Which tools read and change settings?

Tool	What it does	Effect
get-overview	Open setup tasks, notices, subscriber growth, open and click rates, and the next campaign. Start here.	Read only
get-settings	Every setting with its value, type, label and help text.	Read only
update-settings	Changes settings, checked like the settings screen. Refuses the two owner-only switches.	Changes data

What order should an agent use for a send?

1. get-overview to see what’s open.
2. list-audiences to pick who gets it.
3. create-campaign with the subject, preview text, audience and body.
4. get-campaign to show the owner the subject, audience and its size.
5. send-campaign-test, then the owner reads the test.
6. check-send-readiness for the campaign, and fix what it lists.
7. get-send-time for a good slot.
8. schedule-campaign or send-campaign, only when the owner asks.
9. get-campaign-progress while it sends, then campaign-stats.

Mailpuff tells connected agents this order in the tool descriptions. AI agent permissions and safe sending explains each check.

What limits apply to the tools?

Limit	Value
Contacts per list-contacts page	100
Campaigns per list-campaigns page	50
People per import-contacts call	500
Emails per update-tag-members call	500
Blocks in one email body	200
Characters in one block	5,000
Plain-text body returned by get-campaign	20,000 characters

Can I run the tools without an AI app?

Yes. They are ordinary WordPress abilities. In PHP, run one with the Abilities API:

$ability = wp_get_ability( 'mailpuff/campaign-stats' );
$stats   = $ability->execute( array( 'campaign_id' => 42 ) );

Over REST, list them at /wp-json/wp-abilities/v1/abilities and run one at /wp-json/wp-abilities/v1/abilities/mailpuff/{tool}/run, signed in as an administrator. WordPress picks the HTTP method from each tool’s annotations: GET for read-only tools, DELETE for tools marked both destructive and idempotent, and POST for the rest. Pass the input as input. The Abilities API handbook covers registering and running abilities.

FAQ

Can I turn off single tools?

With Saddle, yes: every Mailpuff tool has its own switch on Saddle’s permissions screen. Mailpuff keeps one switch of its own, “AI agents can send campaigns”, which decides whether the sending tools exist at all.

Why can’t the agent change “My host delivers mail”?

That setting and “AI agents can send campaigns” both let email go out, so only the owner changes them in wp-admin. update-settings refuses them.

What happens when a tool gets a bad input?

WordPress checks every call against the tool’s input schema before it runs, and refuses anything that doesn’t fit. update-settings also checks values the way the settings screen does and names the field and the reason.

Related guides

• Connect an AI agent to Mailpuff with MCP
• How AI agents write emails in Mailpuff
• AI agent permissions and safe sending
• Mailpuff hooks reference