plunk-mcp
OfficialSummary: A Model Context Protocol server that gives Claude (and any MCP client) full access to a self-hosted or hosted Plunk email platform — 94 tools spanning email sending, contacts, campaigns, segments, templates, workflows, events, domains, activity, analytics, and uploads.
Send email — transactional sends with subject/body or a template UUID, recipients as string/object/array, attachments, custom headers, reply-to, and template variables (
plunk_send_transactional)Track events & verify addresses — fire events that drive workflows and segment filters (
plunk_track_event, requires apk_*public key), and check deliverability (plunk_verify_email)Manage contacts — list/search/sort/filter by subscription state with cursor pagination, get, create or upsert by email, PATCH updates (including address changes), delete, plus subscribe/unsubscribe via public id and bulk import/subscribe/unsubscribe/delete, and custom field management
Run campaigns — full lifecycle: create, update, send, cancel, test, and pull stats
Build segments — dynamic and static segments with a full filter-condition schema, member management, and recompute
Manage templates — reusable email templates referenced from sends, campaigns, and workflows
Author workflows — steps, transitions, and executions: the whole automation builder, including starting and cancelling executions
Read events & analytics — event history, stats, names, usage; timeseries, top campaigns, top events
Inspect activity — activity feed, stats, upcoming sends
Manage sending domains — add, verify, and delete (an authority Plunk's own MCP withholds)
Upload images — base64 image uploads for templates and campaigns
Operate safely — annotate every tool, run read-only (40 tools, no mutation possible), and gate sends/bulk deletes/domain deletion behind human confirmation prompts
*(The schema excerpt supplied shows 10 of these tools: the three transactional ones, six contact tools, and image upload; the README documents the remaining 84 across the other categories.)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@plunk-mcp create a new campaign for Black Friday sale"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
plunk-mcp
A Model Context Protocol server for Plunk, the open-source self-hosted email platform. Gives Claude (and any MCP client) 94 tools across the Plunk API: transactional email, contacts, campaigns, segments, templates, workflows, events, analytics.
Unofficial. Not affiliated with Plunk. Built by Ignyte.
Why this exists
Plunk's official Node SDK does two things: track and send. The API behind those two methods has grown into a full email automation platform that includes workflows, segments, templates, analytics, but the SDK never caught up. So Claude couldn't reach any of it.
This MCP closes that gap. Every endpoint Claude can usefully call, it can call.
Related MCP server: Tratto MCP Server
Requirements
The active Plunk codebase: useplunk/plunk, distributed as ghcr.io/useplunk/plunk. Self-hosted or on useplunk.com.
Note that this MCP does not support the legacy driaug/plunk Docker image. If you're on that image, see Migrating from legacy.
Node.js ≥ 20 (required by the v2 MCP SDK).
Install
Add to ~/.claude.json or your Claude Desktop config:
{
"mcpServers": {
"plunk": {
"command": "npx",
"args": ["-y", "@ignytehq/plunk-mcp"],
"env": {
"PLUNK_API_KEY": "sk_your_secret_key_here",
"PLUNK_PUBLIC_KEY": "pk_your_public_key_here",
"PLUNK_API_URL": "https://your-plunk-host"
}
}
}
}Restart Claude.
PLUNK_API_URL is optional on hosted Plunk. It defaults to https://next-api.useplunk.com, which is
the API for the active useplunk/plunk codebase — not api.useplunk.com, which serves the legacy
API and 404s every route this server uses.
PLUNK_PUBLIC_KEY is optional. Plunk's /v1/track endpoint is gated by the public key (pk_*), not the secret key — if you omit PLUNK_PUBLIC_KEY, plunk_track_event will 401 against v0.10+ instances.
Multiple Plunk projects
Plunk API keys are project-scoped. To work with multiple projects in the same session, register one MCP server per project:
{
"mcpServers": {
"plunk-acme": {
"command": "npx",
"args": ["-y", "@ignytehq/plunk-mcp"],
"env": {
"PLUNK_API_KEY": "sk_acme_...",
"PLUNK_API_URL": "https://plunk.acme.com"
}
},
"plunk-personal": {
"command": "npx",
"args": ["-y", "@ignytehq/plunk-mcp"],
"env": {
"PLUNK_API_KEY": "sk_personal_...",
"PLUNK_API_URL": "https://plunk.example.com"
}
}
}
}Claude sees each as its own tool namespace.
Configuration
Env var | Required | Default | What it does |
| yes | — | Secret API key ( |
| no | — | Public API key ( |
| no |
| Base URL of your Plunk API. For self-hosted, point at the API host (e.g. |
| no |
|
|
| no |
|
|
| no | — | Takes precedence over |
| no | — | Takes precedence over |
| no |
| Skip the startup probe and expose every tool regardless of what your instance supports. Useful for debugging. |
The flags --read-only and --api-url=<url> do the same as their environment variables, and win over them.
If you self-host Plunk on the same machine
Plunk's own API server uses an environment variable called PLUNK_API_KEY for its platform
notification emails — and that key belongs to a different project. If both are present in the same
environment, this server would silently talk to the wrong project rather than error. Set
PLUNK_MCP_API_KEY and it wins.
Tests
npm test builds and runs the suite (vitest). It never touches a real Plunk instance — the
integration tests point the server at an unroutable address, so a tool that gets past a gate fails at
the socket, which is what proves it got past.
Four areas, chosen because each one covers a regression that actually happened during development:
Annotation invariants — every tool classified, no orphan rows, the fail-closed default holds, and no tool whose verb implies a side effect is admitted to read-only mode.
Schema regressions — identifiers accept well-formed non-RFC UUIDs (zod 4's
z.uuid()rejects them where zod 3 did not), and the recursive filter tree is advertised with real structure at both its outer and nested level.Confirmation builders — thresholds, counts, pluralisation, address-preview capping, and prompts grounded in a fetched campaign, including when that fetch fails.
Protocol integration — the real binary over stdio: registration counts, read-only withholding, the confirmation round-trip on both protocol eras, declines, malformed confirmations, the bypass variable, and startup validation.
Safety
A Plunk secret key is all-or-nothing over its project, so this server adds its own brakes.
Read-only mode is enforced by registration. With PLUNK_READ_ONLY=true (or --read-only) the 54
mutating tools are never registered, so they do not appear in tools/list and cannot be invoked even
by name. The gate reads each tool's readOnlyHint annotation, and an unclassified tool defaults to
destructive — a tool is excluded unless it is known to be safe, never the other way round.
Every tool is annotated. All 94 carry readOnlyHint, destructiveHint, idempotentHint and
openWorldHint, so clients that gate on annotations can prompt before a send or a delete without
pattern-matching on tool names. Sends (plunk_send_campaign, plunk_send_transactional,
plunk_start_workflow_execution) are marked destructive: not destructive in the delete sense, but
irreversible in the only sense that matters for email.
Sends and bulk deletes ask a human first. Eight tools are gated behind a confirmation the model
cannot grant itself — it arrives through an elicitation round-trip, on a channel the model never
writes to, so a true originated with the person at the keyboard:
Tool | When it asks |
| always |
| more than one recipient |
| always |
| always |
| always |
The prompt is built from what the API reports, not from what the model claims — asking to send a
campaign fetches its name, subject and real audience size first, so the blast radius in the prompt is
the true one. Both protocol eras are served: modern (2026-07-28) clients get the input_required
round-trip, 2025-era clients the push-style elicitation request. A client that can do neither cannot
send, which is the safe direction for mass email; PLUNK_ALLOW_UNCONFIRMED_SENDS=true is the
documented way out for headless automation.
A declined or cancelled prompt stops the call. It is not re-asked, so a refusal cannot be worn down by repetition.
A note on domain tools. plunk_add_domain and plunk_delete_domain are exposed, unlike in
Plunk's own MCP server, which withholds them. Plunk's reasoning is worth knowing: those endpoints skip
the admin-role check when called with an API key, so an agent holding one can do something a non-admin
member of the same project cannot. They are excluded from read-only mode, and plunk_delete_domain is
gated behind confirmation, but if that authority is not something you want an agent to hold, run with
PLUNK_READ_ONLY=true or use a project whose key you are comfortable handing over.
The gate is deliberately narrower than destructiveHint: it covers what is irreversible and wide.
Single deletes are annotated but not gated — gating everything would train people to set the bypass
variable and lose the gate altogether. The table lives in
src/confirmations.ts.
Misconfiguration fails at startup, not at call time. A pk_* key in the secret slot, a sk_* key
in the public slot, or a non-absolute API URL each exit with an explanation instead of letting every
tool 401 one call at a time.
The full classification lives in src/annotations.ts — one table, 94 rows, so
the security posture of the server can be read in one screen.
An API key still grants full read and write access to its project. Use a separate Plunk project for anything you would not want an agent to change.
What's in the box
94 tools across 11 categories — 40 read-only, 54 mutating. At startup, the MCP probes one endpoint per category and only registers tools whose category responds — so on older useplunk/plunk releases, missing features are hidden rather than failing at call time.
Category | Tools | Highlights |
Transactional | 3 |
|
Contacts | 19 | CRUD, bulk import/subscribe/unsubscribe/delete, custom field management |
Campaigns | 15 | Full lifecycle: create, update, send, cancel, test, stats |
Segments | 10 | Dynamic + static segments, member management, recompute |
Templates | 8 | Reusable email templates referenced from sends/campaigns/workflows |
Workflows | 19 | Steps, transitions, executions — the whole automation builder |
Events | 6 | Read API: history, stats, names, usage, delete |
Domains | 4 | Add, verify, delete sending domains |
Activity | 5 | Activity feed, stats, upcoming sends |
Analytics | 4 | Timeseries, top campaigns, top events |
Uploads | 1 | Image uploads for templates and campaigns |
Tool names follow plunk_<verb>_<resource>. Examples:
plunk_send_transactional— send a one-off emailplunk_track_event— fire an event (which then drives workflows and segment filters)plunk_create_workflow+plunk_add_workflow_step+plunk_start_workflow_executionplunk_create_segment(full filter-condition schema)plunk_get_analytics_timeseries,plunk_get_top_campaigns
Every tool has a typed input schema, a short title, and a structured description:
**Purpose:** what it does
**Not for:** the sibling you probably wanted instead, and why
**Returns:** the shape of a success
**Use when:** the situation that should make you reach for it
**Note:** version gates, limits, gotchasWith 94 tools the failure mode is not a model that cannot use a tool — it is a model that picks the
wrong one of four that sound alike. Not for is the load-bearing field, and every tool has one:
plunk_delete_contact points at plunk_unsubscribe_contact, plunk_delete_campaign at
plunk_cancel_campaign, plunk_send_campaign at plunk_test_campaign. Those cross-references are
checked by the test suite, so a pointer can never name a tool that does not exist.
The descriptions cost roughly 38 KB of context when all 94 tools are registered. PLUNK_READ_ONLY
cuts that to the 40 read tools if an agent only needs to look.
Capability detection, briefly
On startup the MCP makes one probe request per tool family to see what your instance answers. If /templates 404s, the seven template tools are hidden for the rest of the session. If /workflows answers, the sixteen workflow tools are registered.
The point is to keep Claude from confidently invoking endpoints that don't exist on your specific Plunk version. The probe takes one round trip per family at startup, then nothing.
Migrating from legacy driaug/plunk
The legacy image exposes a smaller, different API. This MCP won't fully work against it. The migration path:
Stand up
ghcr.io/useplunk/plunk:lateston a separate host or subdomain. Don't disrupt your existing sender. The official guide is at docs.useplunk.com/self-hosting/introduction.Re-create your project on the new instance. Grab a fresh
sk_*API key. The schemas differ; there's no in-place upgrade.Export contacts from legacy (CSV from the dashboard). Import on the new instance via
plunk_import_contacts.Re-create campaigns and templates. Workflows and segments are entirely new on the modern codebase.
Repoint your apps to the new host. Decommission legacy.
This is a real migration project, an easy evening or two of work.
Building from source
git clone https://github.com/ignytehq/plunk-mcp.git
cd plunk-mcp
npm install
npm run build
PLUNK_API_KEY=sk_... PLUNK_API_URL=https://your-plunk node dist/index.jsTests
npm test
Contributing
Issues and PRs welcome. If an endpoint responds unexpectedly, please include:
Which Plunk version you're running (
docker inspect <container> | grep Imageplus the tag)The endpoint path that misbehaved
The full error message
License
MIT. See LICENSE.
Acknowledgements
Plunk and Driaug Aerts, for being open source. Anthropic, for the Model Context Protocol.
Available Tools
94 toolsplunk_add_domainAdd sending domainA
Purpose: Register a new sending domain and get the DKIM and SPF records to place in DNS.
Not for: Re-checking a domain already added — that is plunk_verify_domain.
Returns: The created domain with the DNS records that must be configured.
Use when: Setting up a new from address on a domain Plunk does not yet know about.
Note: Adding a domain via an API key skips the admin-role check the dashboard applies, so this grants authority a non-admin project member does not have.
Inputs: domain (required), projectId (required).
plunk_add_segment_membersAdd segment membersAIdempotent
Purpose: Add contacts to a STATIC segment by email address, optionally creating any that do not exist yet.
Not for: A DYNAMIC segment, whose membership is decided by its filter — edit the condition with plunk_update_segment instead.
Returns: The result of the membership change.
Use when: Hand-curating an audience, or importing a list someone supplied.
Note: Up to 500 emails per call. createMissing decides whether unknown addresses become new contacts.
Inputs: id (required), emails (required), subscribed, createMissing.
plunk_add_workflow_stepAdd workflow stepA
Purpose: Add a step to a workflow — send an email, wait, branch on a condition, call a webhook, or update the contact.
Not for: Slotting a step between two that are already connected — plunk_insert_workflow_step does that in one call and rewires both sides. A step added here is orphaned until plunk_add_workflow_transition wires it in.
Returns: The created step including its id, needed for transitions.
Use when: Building out what an automation does, one step at a time.
Note: DELAY is capped at 365 days. WEBHOOK url, headers and body interpolate template variables on v0.12+. UPDATE_CONTACT accepts subscriptionAction to change subscription state as part of the step.
Inputs: id (required), name (required), type (required), config (required), +3 more.
plunk_add_workflow_transitionConnect workflow stepsA
Purpose: Connect one step to another, defining what happens next and under which condition.
Not for: Creating the steps themselves, which is plunk_add_workflow_step. Both ends must exist first.
Returns: The created transition including its id.
Use when: Wiring a newly added step into the workflow, or branching on a condition.
Inputs: id (required), toStepId (required), fromStepId (required), priority, +1 more.
plunk_archive_campaignArchive campaignAIdempotent
Purpose: Hide a campaign from the default list while keeping it and all its performance history intact.
Not for: Getting rid of one for good, which is plunk_delete_campaign and discards the history with it.
Returns: The archived campaign.
Use when: Tidying up finished or abandoned campaigns without losing the record of how they did.
Note: Requires Plunk v0.15+. Fully reversible with plunk_unarchive_campaign. Scheduled and sending campaigns cannot be archived, since they still need attention.
Inputs: id (required).
plunk_bulk_archive_campaignsBulk archive campaignsAIdempotent
Purpose: Archive or restore up to 1000 campaigns in one call.
Not for: Deleting them, which is plunk_bulk_delete_campaigns and cannot be undone.
Returns: The outcome of the batch.
Use when: Clearing a backlog of finished campaigns out of the way in bulk.
Note: Requires Plunk v0.15+. Reversible: pass archived false to restore. No confirmation is asked because nothing is lost.
Inputs: ids (required), archived (required).
plunk_bulk_delete_campaignsBulk delete campaignsADestructiveIdempotent
Purpose: Permanently delete up to 1000 draft campaigns in one atomic call.
Not for: A single campaign (plunk_delete_campaign), or stopping a send (plunk_cancel_campaign).
Returns: The outcome of the batch.
Use when: Clearing out accumulated drafts.
Note: Requires Plunk v0.12+. Only draft campaigns can be bulk-deleted. Asks for confirmation before running.
Inputs: ids (required).
plunk_bulk_delete_contactsBulk delete contactsADestructiveIdempotent
Purpose: Permanently delete up to 1000 contacts and their event histories.
Not for: Stopping mail to them, which is plunk_bulk_unsubscribe_contacts — deletion loses the opt-out record, so a later import can re-add them.
Returns: A job id to poll with plunk_get_bulk_job_status.
Use when: Genuine erasure of a cohort is required.
Note: Asks for confirmation before running.
Inputs: contactIds (required).
plunk_bulk_delete_templatesBulk delete templatesADestructiveIdempotent
Purpose: Permanently delete up to 1000 templates in one atomic call.
Not for: A single template — plunk_delete_template is clearer and its failure message is more specific.
Returns: The outcome of the batch.
Use when: Clearing out many templates at once, typically after an audit.
Note: Requires Plunk v0.12+. Atomic: if any template in the batch is still referenced by a campaign or workflow, none are deleted. Asks for confirmation before running.
Inputs: ids (required).
plunk_bulk_delete_workflowsBulk delete workflowsADestructiveIdempotent
Purpose: Permanently delete up to 1000 workflows, including their execution histories.
Not for: A single workflow, which is plunk_delete_workflow.
Returns: The outcome of the batch.
Use when: Clearing out abandoned automations.
Note: Requires Plunk v0.12+. Asks for confirmation before running.
Inputs: ids (required).
plunk_bulk_subscribe_contactsBulk subscribeAIdempotent
Purpose: Opt up to 1000 existing contacts back in to marketing email.
Not for: Reversing unsubscribes people chose for themselves. Only use this where consent genuinely exists.
Returns: A job id to poll with plunk_get_bulk_job_status.
Use when: Correcting a mistaken mass unsubscribe, or migrating consent recorded elsewhere.
Inputs: contactIds (required).
plunk_bulk_unsubscribe_contactsBulk unsubscribeAIdempotent
Purpose: Opt up to 1000 contacts out of marketing email.
Not for: Deleting them, which is plunk_bulk_delete_contacts.
Returns: A job id to poll with plunk_get_bulk_job_status.
Use when: Honouring a batch of opt-out requests, or suppressing a cohort that should not be mailed.
Note: Asks for confirmation before running.
Inputs: contactIds (required).
plunk_cancel_all_workflow_executionsCancel all workflow runsADestructiveIdempotent
Purpose: Stop every in-flight run of a workflow at once.
Not for: Preventing new entries. Disable the workflow with plunk_update_workflow, or contacts will keep entering after this.
Returns: The number of executions cancelled.
Use when: An automation is misbehaving and everyone in it should stop where they are.
Note: Contacts stop mid-flow and scheduled steps do not run. Asks for confirmation before running.
Inputs: id (required).
plunk_cancel_campaignCancel campaignADestructiveIdempotent
Purpose: Stop a scheduled or in-flight campaign. Mail already delivered cannot be recalled.
Not for: Removing the campaign entirely, which is plunk_delete_campaign.
Returns: Confirmation of the cancellation.
Use when: A send was started in error, or a scheduled send should no longer happen.
Note: Only stops recipients not yet reached; delivered mail cannot be recalled. On Plunk v0.15+ a cancelled campaign returns to an editable draft, so it can be fixed and sent again.
Inputs: id (required).
plunk_cancel_workflow_executionCancel workflow runADestructiveIdempotent
Purpose: Stop one contact's run of a workflow. Mail already sent cannot be recalled.
Not for: Stopping the workflow for everyone, which is plunk_cancel_all_workflow_executions, or disabling it via plunk_update_workflow.
Returns: Confirmation of the cancellation.
Use when: One contact should not continue — they replied, unsubscribed, or entered by mistake.
Inputs: id (required), executionId (required).
plunk_compute_segmentRecompute segmentAIdempotent
Purpose: Force a DYNAMIC segment to re-evaluate its filter now rather than waiting for its normal refresh.
Not for: Refreshing only the displayed count, which is the cheaper plunk_refresh_segment_count.
Returns: The recomputed segment state.
Use when: Contacts or events changed and the segment must be current before you send to it.
Inputs: id (required).
plunk_create_campaignCreate campaignA
Purpose: Create a campaign as a draft. It is never sent by this call.
Not for: A one-off message to specific people — that is plunk_send_transactional. A campaign targets an audience.
Returns: The created draft including its id.
Use when: Composing a newsletter or announcement for a list, segment or filtered audience.
Note: audienceType ALL reaches every subscribed contact; SEGMENT needs segmentId; FILTERED takes an inline audienceCondition. Sending is a separate, confirmed step.
Inputs: body (required), from (required), name (required), subject (required), +7 more.
plunk_create_contactCreate contactAIdempotent
Purpose: Create a contact, or update it if the email already exists. Safe to call twice.
Not for: Adding many at once, which is plunk_import_contacts.
Returns: The created or updated contact.
Use when: Adding a single person, or ensuring one exists before acting on them.
Note: Emails are normalised server-side for case and whitespace on Plunk v0.12+.
Inputs: email (required), data, subscribed.
plunk_create_segmentCreate segmentA
Purpose: Create a reusable audience. A DYNAMIC segment re-evaluates its filter continuously, so contacts join and leave on their own; a STATIC one holds a membership you manage by hand.
Not for: A one-off audience for a single campaign — plunk_create_campaign accepts an inline filter via audienceType FILTERED, with no segment to maintain afterwards.
Returns: The created segment including its id.
Use when: The same audience will be reused, or the user wants to see it in the dashboard.
Note: DYNAMIC requires a condition. trackMembership emits entry and exit events that workflows can trigger on.
Inputs: name (required), type, condition, description, +1 more.
plunk_create_templateCreate templateA
Purpose: Create a reusable email template that sends, campaigns and workflow steps can reference by id.
Not for: A one-off email. plunk_send_transactional takes an inline subject and body directly, with no template needed.
Returns: The created template including its id.
Use when: The same email will be sent more than once, or a workflow step needs something to point at.
Inputs: body (required), from (required), name (required), subject (required), +4 more.
plunk_create_workflowCreate workflowA
Purpose: Create a workflow with its trigger. Steps and transitions are added afterwards.
Not for: A finished automation in one call. A usable workflow needs plunk_add_workflow_step and plunk_add_workflow_transition after this.
Returns: The created workflow including its id.
Use when: Starting a new automation. Create it, add steps, connect them, then enable it.
Inputs: name (required), eventName (required), enabled, description, +1 more.
plunk_delete_campaignDelete campaignADestructiveIdempotent
Purpose: Permanently delete one campaign and its record.
Not for: Stopping a campaign that is scheduled or in flight — use plunk_cancel_campaign, which halts the send and keeps the history.
Returns: Confirmation of the deletion.
Use when: A draft is genuinely unwanted. Deleting a sent campaign also discards its performance history.
Inputs: id (required).
plunk_delete_contactDelete contactADestructiveIdempotent
Purpose: Permanently delete one contact and their event history.
Not for: Stopping mail to someone, which is plunk_unsubscribe_contact — deleting loses the record that they opted out, so they can be re-added by a later import.
Returns: Confirmation of the deletion.
Use when: Genuine erasure is wanted, such as a data-deletion request.
Inputs: id (required).
plunk_delete_contact_fieldDelete custom fieldADestructiveIdempotent
Purpose: Remove a custom field and its values from every contact.
Not for: Clearing it on one contact — pass null for that key via plunk_update_contact instead.
Returns: Confirmation of the deletion.
Use when: A field is genuinely obsolete. Check plunk_get_field_usage first; segments filtering on it will stop matching.
Inputs: field (required).
plunk_delete_domainDelete sending domainADestructiveIdempotent
Purpose: Remove a sending domain from the project.
Not for: Temporarily pausing sending. There is no undo short of re-adding the domain and verifying DNS again.
Returns: Confirmation of removal.
Use when: A domain is genuinely retired. Nothing can be sent from it afterwards.
Note: Asks for confirmation before running. Like plunk_add_domain, this skips the admin-role check when called with an API key.
Inputs: id (required).
plunk_delete_eventDelete eventADestructiveIdempotent
Purpose: Delete an event and its recorded history from the project.
Not for: Removing one contact's event record. This removes the event across the project.
Returns: Confirmation of the deletion.
Use when: An event name was created in error and nothing references it. Check plunk_get_event_usage first — workflows and segments that trigger on it will stop working.
Inputs: eventName (required).
plunk_delete_segmentDelete segmentADestructiveIdempotent
Purpose: Permanently delete a segment. The contacts themselves are untouched.
Not for: Removing people from the segment while keeping it, which is plunk_remove_segment_members.
Returns: Confirmation of the deletion.
Use when: A segment is no longer needed. Campaigns configured to target it will lose their audience.
Inputs: id (required).
plunk_delete_templateDelete templateADestructiveIdempotent
Purpose: Permanently delete one template.
Not for: Clearing out many at once — plunk_bulk_delete_templates handles up to 1000 in a single atomic call.
Returns: Confirmation of the deletion.
Use when: A template is genuinely unwanted. Check plunk_get_template_usage first; the call fails if a campaign or workflow still references it.
Inputs: id (required).
plunk_delete_workflowDelete workflowADestructiveIdempotent
Purpose: Permanently delete a workflow, its steps and its execution history.
Not for: Stopping it temporarily — set enabled to false via plunk_update_workflow, which is reversible.
Returns: Confirmation of the deletion.
Use when: An automation is genuinely retired. Contacts partway through it are dropped.
Inputs: id (required).
plunk_delete_workflow_stepDelete workflow stepADestructiveIdempotent
Purpose: Remove one step from a workflow.
Not for: Deleting the whole workflow, which is plunk_delete_workflow.
Returns: Confirmation of the deletion.
Use when: Removing a step from the graph.
Note: Transitions into and out of this step are left dangling. Fetch the workflow with plunk_get_workflow afterwards and reconnect the graph, or contacts will stall where the step used to be.
Inputs: id (required), stepId (required).
plunk_delete_workflow_transitionDisconnect workflow stepsADestructiveIdempotent
Purpose: Remove a connection between two steps.
Not for: Deleting either step, which is plunk_delete_workflow_step.
Returns: Confirmation of the deletion.
Use when: Rerouting a workflow. Removing a transition can strand the steps downstream of it, so check the graph afterwards.
Inputs: id (required), transitionId (required).
plunk_duplicate_campaignDuplicate campaignA
Purpose: Copy a campaign into a new draft, content and audience settings included.
Not for: Sending the same campaign again to the same people — that is usually not what is wanted, and the copy is a fresh draft either way.
Returns: The new draft including its own id.
Use when: Basing a new send on one that worked, or recovering an editable version of something already sent.
Inputs: id (required).
plunk_duplicate_templateDuplicate templateA
Purpose: Copy a template, body and all, into a new independent template.
Not for: Editing the original, which is plunk_update_template.
Returns: The new copy including its own id.
Use when: Building a variant of something that works, without risking the version already in use.
Inputs: id (required).
plunk_duplicate_workflowDuplicate workflowA
Purpose: Copy a workflow with all its steps and transitions into a new one.
Not for: Editing the original, which is plunk_update_workflow.
Returns: The new copy including its own id.
Use when: Reworking an automation without disturbing the one currently running.
Note: Requires Plunk v0.11+. The copy is created disabled and with no execution state, so it cannot start sending by accident.
Inputs: id (required).
plunk_get_activityActivity feedARead-onlyIdempotent
Purpose: Read the project activity feed: sends, opens, clicks, bounces and complaints as they happened, newest first.
Not for: Aggregate numbers. For totals use plunk_get_activity_stats; for one campaign's performance use plunk_get_campaign_stats.
Returns: A page of individual activity records.
Use when: Investigating what actually happened to a specific contact or in a specific window, rather than how much happened overall.
Inputs: page, type, limit.
plunk_get_activity_statsActivity totalsARead-onlyIdempotent
Purpose: Aggregate counts across the activity feed — totals per activity type for the project.
Not for: Per-campaign performance (plunk_get_campaign_stats) or a movement over time (plunk_get_analytics_timeseries).
Returns: Totals by activity type.
Use when: The user wants project-wide numbers rather than individual events.
Inputs: no named parameters.
plunk_get_analytics_timeseriesAnalytics over timeARead-onlyIdempotent
Purpose: Email metrics bucketed over a time range, so a trend can be read rather than a single total.
Not for: One campaign's numbers (plunk_get_campaign_stats) or a ranking (plunk_get_top_campaigns). This is the shape of a movement over time.
Returns: Time-bucketed metric series.
Use when: The question is about direction — whether opens are rising, whether bounces spiked, what a given week looked like.
Inputs: to, from, interval.
plunk_get_bulk_job_statusBulk job statusARead-onlyIdempotent
Purpose: Check how a bulk subscribe, unsubscribe or delete job is progressing.
Not for: Import jobs, which are polled with plunk_get_import_status.
Returns: The job's state, progress and any errors.
Use when: After starting a bulk operation, to confirm it completed.
Inputs: jobId (required).
plunk_get_campaignGet campaignARead-onlyIdempotent
Purpose: Fetch one campaign in full: subject, body, sender, audience configuration and status.
Not for: How it performed after sending — that is plunk_get_campaign_stats.
Returns: The complete campaign record, including its audience configuration.
Use when: Reviewing a draft before sending, or checking who a campaign is configured to reach.
Inputs: id (required).
plunk_get_campaign_breakdownCampaign breakdownARead-onlyIdempotent
Purpose: Comparative campaign statistics across the project, broken down for analysis.
Not for: A single campaign's headline numbers — plunk_get_campaign_stats is the direct answer for that.
Returns: Per-campaign statistics across the selected range.
Use when: Comparing campaigns against each other rather than reading one in isolation.
Inputs: to, from, interval.
plunk_get_campaign_statsCampaign statsARead-onlyIdempotent
Purpose: Delivery and engagement figures for one campaign: sends, opens, clicks, bounces and complaints.
Not for: A campaign's content or audience settings (plunk_get_campaign), or a comparison across campaigns (plunk_get_top_campaigns).
Returns: Counts and rates for this campaign.
Use when: The user asks how a specific campaign performed.
Note: For the actual addresses behind the bounce and complaint counts, use plunk_list_campaign_recipients.
Inputs: id (required).
plunk_get_contactGet contactARead-onlyIdempotent
Purpose: Fetch one contact by id, including custom data and subscription state.
Not for: Looking someone up by email address — use plunk_lookup_contacts, which takes addresses directly.
Returns: The complete contact record.
Use when: You already have a contact id and need the full picture.
Inputs: id (required).
plunk_get_contact_eventsContact event historyARead-onlyIdempotent
Purpose: List every event recorded for one contact, in order.
Not for: Delivery activity for that contact — opens and clicks live in plunk_get_activity.
Returns: That contact's event history.
Use when: Working out why a contact did or did not enter a workflow or segment.
Inputs: contactId (required).
plunk_get_event_statsEvent statsARead-onlyIdempotent
Purpose: Aggregate statistics across tracked events.
Not for: A ranking of the busiest events, which is plunk_get_top_events.
Returns: Aggregate event figures.
Use when: Summarising event volume for the project.
Inputs: no named parameters.
plunk_get_event_usageEvent usageARead-onlyIdempotent
Purpose: Show where an event name is referenced — which workflows trigger on it and which segments filter by it.
Not for: How often it fired, which is plunk_get_event_stats or plunk_get_top_events.
Returns: The workflows and segments referencing this event.
Use when: Before deleting or renaming an event, to see what would break.
Inputs: eventName (required).
plunk_get_field_usageField usageARead-onlyIdempotent
Purpose: Report how widely a custom field is populated across contacts.
Not for: The values themselves, which is plunk_get_field_values.
Returns: Usage figures for this field.
Use when: Deciding whether a field is worth segmenting on, or safe to delete.
Inputs: field (required).
plunk_get_field_valuesField valuesARead-onlyIdempotent
Purpose: List the distinct values stored in one custom field.
Not for: How many contacts have the field set at all, which is plunk_get_field_usage.
Returns: The distinct values for this field.
Use when: Building a segment filter and needing to know what to match against.
Inputs: field (required).
plunk_get_import_statusImport statusARead-onlyIdempotent
Purpose: Check how an import job started by plunk_import_contacts is progressing.
Not for: Bulk subscribe, unsubscribe or delete jobs — those are polled with plunk_get_bulk_job_status.
Returns: The job's state, progress and any errors.
Use when: After starting an import, to confirm it finished and see what failed.
Inputs: jobId (required).
plunk_get_recent_activity_countRecent activity countARead-onlyIdempotent
Purpose: A single cached number: how much activity the project has seen recently.
Not for: Anything you intend to break down. It is one figure, cached for speed, with no dimensions to slice.
Returns: One count.
Use when: Answering whether anything is happening at all, cheaply, before deciding what to look at properly.
Inputs: no named parameters.
plunk_get_segmentGet segmentARead-onlyIdempotent
Purpose: Fetch one segment in full, including its filter condition tree.
Not for: Its members, which is plunk_list_segment_contacts.
Returns: The complete segment record with its condition.
Use when: Working out why a segment matches who it matches, before editing its filter.
Inputs: id (required).
plunk_get_templateGet templateARead-onlyIdempotent
Purpose: Fetch one template in full, including its HTML body and subject.
Not for: Browsing what exists — use plunk_list_templates, which is far cheaper than fetching bodies one by one.
Returns: The complete template record.
Use when: You are about to edit a template and need its current body, or the user asks what a specific template says.
Inputs: id (required).
plunk_get_template_usageTemplate usageARead-onlyIdempotent
Purpose: List the campaigns and workflows that reference a template.
Not for: Delivery numbers. This reports references, not opens or clicks — those are plunk_get_campaign_stats.
Returns: The campaigns and workflows pointing at this template.
Use when: Before deleting or editing a template, to see what a change would affect.
Inputs: id (required).
plunk_get_top_campaignsTop campaignsARead-onlyIdempotent
Purpose: Rank campaigns by performance across a period.
Not for: A full list of campaigns (plunk_list_campaigns) or one campaign in depth (plunk_get_campaign_stats). This is a leaderboard.
Returns: Campaigns ordered by performance.
Use when: The user asks what worked best, or you need the strongest performers without fetching every campaign.
Inputs: limit.
plunk_get_top_eventsTop eventsARead-onlyIdempotent
Purpose: Rank tracked events by how often they fired across a period.
Not for: One event's detail (plunk_get_event_stats) or the list of event names that exist (plunk_list_event_names).
Returns: Events ordered by volume.
Use when: Finding out what your contacts actually do most, or which events are worth building a workflow around.
Inputs: limit.
plunk_get_workflowGet workflowARead-onlyIdempotent
Purpose: Fetch one workflow in full: its trigger, every step, and the transitions connecting them.
Not for: Its run history, which is plunk_list_workflow_executions.
Returns: The complete workflow graph.
Use when: Always, before editing a workflow. Steps and transitions reference each other by id, and you need the current graph to change it safely.
Inputs: id (required).
plunk_get_workflow_executionGet workflow runARead-onlyIdempotent
Purpose: Fetch one execution in detail: the steps taken, the current position and what is scheduled next.
Not for: A list of runs, which is plunk_list_workflow_executions.
Returns: The full execution record.
Use when: Working out why one specific contact is stuck, or what they have already been sent.
Inputs: id (required), executionId (required).
plunk_import_contactsImport contactsA
Purpose: Import many contacts at once. Runs as a background job.
Not for: One person, which is plunk_create_contact.
Returns: A job id to poll with plunk_get_import_status.
Use when: Loading a list from elsewhere.
Note: Only import addresses that consented to hear from you. Importing an unconsented list is how a sending domain gets burned.
Inputs: contacts (required).
plunk_insert_workflow_stepInsert step into a connectionA
Purpose: Add a step in the middle of an existing connection, so A to B becomes A to the new step to B, with both connections rewired for you.
Not for: Adding a step at the end or start of a branch — plunk_add_workflow_step plus plunk_add_workflow_transition is the way to do that.
Returns: The created step including its id.
Use when: Slotting a step into a workflow that already runs. This is safer than deleting a connection and rebuilding it by hand, because the graph is never left broken partway through.
Note: Requires Plunk v0.13+. Plunk validates the resulting connections, so a change that would strand contacts is rejected rather than half-applied.
Inputs: id (required), name (required), type (required), config (required), +3 more.
plunk_list_activity_typesList activity typesARead-onlyIdempotent
Purpose: List the activity types this Plunk instance records, which are the valid filter values for the activity feed.
Not for: Event names you track yourself — those are plunk_list_event_names. These are delivery-level types like open and bounce.
Returns: The available activity type identifiers.
Use when: Before filtering plunk_get_activity, so the filter uses a type this instance actually records.
Inputs: no named parameters.
plunk_list_campaign_recipientsCampaign bounces and complaintsARead-onlyIdempotent
Purpose: List the individual recipients whose mail bounced, or who marked a campaign as spam.
Not for: The totals, which are in plunk_get_campaign_stats. This names the actual addresses behind those numbers.
Returns: A page of recipients with a cursor for the next page.
Use when: A campaign shows a worrying bounce or complaint rate and you need to see who, so the addresses can be cleaned up.
Note: Requires Plunk v0.15+. Capped at 100 per page. Repeated bounces and complaints are what damage a sending domain's reputation, so act on these rather than just reading them.
Inputs: id (required), type, limit, cursor.
plunk_list_campaignsList campaignsARead-onlyIdempotent
Purpose: List campaigns with their status — draft, scheduled, sending or sent.
Not for: Performance figures. This tells you a campaign exists and what state it is in; plunk_get_campaign_stats tells you how it did.
Returns: A page of campaigns with ids, names, subjects and statuses.
Use when: You need a campaign id, or the user asks what campaigns exist or what is scheduled.
Note: Archived campaigns are hidden by default; pass archived true to see them. Search, sort and the archived filter require Plunk v0.15+.
Inputs: dir, page, sort, search, +3 more.
plunk_list_contact_fieldsList custom fieldsARead-onlyIdempotent
Purpose: List the custom data fields in use across contacts.
Not for: The values stored in a field, which is plunk_get_field_values.
Returns: The field names in use.
Use when: Before writing a segment filter, so the field named is one that exists.
Inputs: no named parameters.
plunk_list_contactsList contactsARead-onlyIdempotent
Purpose: Browse or search contacts, with cursor pagination, email search, subscription filter and sorting.
Not for: Resolving a batch of known addresses to contacts — plunk_lookup_contacts does that in one call instead of searching repeatedly.
Returns: A page of contacts with a cursor for the next page.
Use when: Exploring who is in the project, or finding a contact whose exact address you do not have.
Note: Prefer narrowing with search or subscribed over paging through everything. The subscribed filter and sorting require Plunk v0.12+.
Inputs: dir, page, sort, limit, +3 more.
plunk_list_domainsList sending domainsARead-onlyIdempotent
Purpose: List the project's sending domains and whether each is verified.
Not for: Checking whether one address is deliverable, which is plunk_verify_email.
Returns: Domains with their verification status and DNS records.
Use when: Before sending, to confirm the from address sits on a verified domain.
Note: Requires the project UUID, which is not derivable from the API key. It is in the dashboard URL.
Inputs: projectId (required).
plunk_list_event_namesList event namesARead-onlyIdempotent
Purpose: List the distinct event names that have been tracked, which are the valid values for workflow triggers and segment filters.
Not for: Delivery activity types like open and bounce — those are plunk_list_activity_types.
Returns: The distinct event names in use.
Use when: Before building a workflow trigger or an event-based segment filter, so the name used is one that actually fires.
Inputs: no named parameters.
plunk_list_eventsList eventsARead-onlyIdempotent
Purpose: List event records across the project — what fired, for whom, and when.
Not for: The distinct set of event names (plunk_list_event_names), or one contact's history (plunk_get_contact_events).
Returns: Event records.
Use when: Investigating what has actually been tracked, rather than what could be.
Inputs: no named parameters.
plunk_list_segment_contactsList segment membersARead-onlyIdempotent
Purpose: List the contacts currently in a segment.
Not for: The segment's definition, which is plunk_get_segment.
Returns: The contacts in this segment.
Use when: Checking who a campaign would actually reach before sending to this segment.
Inputs: id (required).
plunk_list_segmentsList segmentsARead-onlyIdempotent
Purpose: List saved audience segments with their names, types and current sizes.
Not for: The contacts inside a segment — that is plunk_list_segment_contacts. This returns the segments themselves.
Returns: All segments with ids, types, conditions and counts.
Use when: You need a segment id for a campaign, or the user asks what audiences exist and how big they are.
Inputs: no named parameters.
plunk_list_templatesList templatesARead-onlyIdempotent
Purpose: List every reusable email template in the project, with its id, name and subject.
Not for: Finding out where a template is used — that is plunk_get_template_usage. This returns the templates themselves, not their bodies in full.
Returns: All templates with ids, names and subjects.
Use when: You need a template id to reference from a send, campaign or workflow step, or the user asks what templates exist.
Inputs: no named parameters.
plunk_list_upcoming_sendsUpcoming sendsARead-onlyIdempotent
Purpose: List mail that is scheduled but has not gone out yet, across campaigns and workflows.
Not for: What has already been sent, which is plunk_get_activity.
Returns: Scheduled sends with their times.
Use when: Checking what is about to go out — worth doing before sending anything else, and before cancelling a campaign.
Inputs: no named parameters.
plunk_list_workflow_executionsList workflow runsARead-onlyIdempotent
Purpose: List runs of a workflow: which contacts are in it, where they have reached, and which have finished.
Not for: The workflow's definition, which is plunk_get_workflow.
Returns: Executions with their contacts, states and current steps.
Use when: Checking whether an automation is working, or how many people are partway through it.
Inputs: id (required).
plunk_list_workflow_fieldsList workflow fieldsARead-onlyIdempotent
Purpose: List the fields available to workflow conditions and template interpolation.
Not for: Contact custom fields in general, which is plunk_list_contact_fields.
Returns: The field names usable inside workflow steps and conditions.
Use when: Before writing a workflow condition or a step that interpolates values, so the reference resolves.
Inputs: no named parameters.
plunk_list_workflowsList workflowsARead-onlyIdempotent
Purpose: List automation workflows with their names, triggers and enabled state.
Not for: What is currently running inside one — that is plunk_list_workflow_executions.
Returns: All workflows with ids, triggers and status.
Use when: You need a workflow id, or the user asks what automations exist and which are live.
Inputs: no named parameters.
plunk_lookup_contactsLook up contacts by emailARead-onlyIdempotent
Purpose: Resolve up to 500 email addresses to contacts in one call. Reads only; nothing is created.
Not for: Browsing or searching by partial address, which is plunk_list_contacts.
Returns: The matching contacts, and which addresses had no match.
Use when: You hold a list of addresses and need their ids or subscription states — far better than one lookup per address.
Inputs: emails (required).
plunk_refresh_segment_countRefresh segment countAIdempotent
Purpose: Recalculate a segment's cached member count.
Not for: Re-evaluating membership itself, which is plunk_compute_segment. This updates the number, not who is in it.
Returns: The refreshed count.
Use when: A displayed size looks stale and you only need the figure corrected.
Inputs: id (required).
plunk_remove_segment_membersRemove segment membersADestructiveIdempotent
Purpose: Remove contacts from a STATIC segment. The contacts themselves are not deleted.
Not for: Deleting contacts (plunk_delete_contact) or unsubscribing them (plunk_unsubscribe_contact). This only changes membership.
Returns: The result of the membership change.
Use when: Pruning a hand-curated audience.
Note: Up to 500 emails per call.
Inputs: id (required), emails (required), subscribed, createMissing.
plunk_send_campaignSend campaignADestructive
Purpose: Send a campaign to its configured audience, immediately or at a scheduled time.
Not for: Checking how it will look — plunk_test_campaign sends one copy to a project member without touching the audience.
Returns: Confirmation that the send has started or been scheduled.
Use when: The draft is final, the audience is right, and the mail should actually go out.
Note: Irreversible once sending begins. Asks for confirmation first, stating the real recipient count. Send a test first if the content has not been seen.
Inputs: id (required), scheduledFor.
plunk_send_transactionalSend emailADestructive
Purpose: Send a one-off email to specific recipients, with an inline subject and body or a template id.
Not for: Mail to a list or segment — that is a campaign (plunk_create_campaign then plunk_send_campaign), which respects unsubscribes properly.
Returns: Confirmation of the send.
Use when: Messaging a named person or small set of people: a receipt, a reply, a notification.
Note: Supply subject and body, or template. from is optional and falls back to the project's default sender. Sending to more than one recipient asks for confirmation first. Pass idempotencyKey to make a retry safe after a timeout.
Inputs: to (required), body, data, from, +8 more.
plunk_snooze_contactSnooze contactAIdempotent
Purpose: Pause marketing email to a contact for a fixed period, after which they resubscribe automatically.
Not for: A permanent opt-out, which is plunk_unsubscribe_contact. Snoozing is a break, not a goodbye.
Returns: The contact with its subscription state and the date the snooze expires.
Use when: Someone wants a rest from your email rather than to leave. Offering this instead of unsubscribing keeps the relationship and avoids a spam complaint.
Note: Requires Plunk v0.15+. While snoozed the contact counts as unsubscribed and is excluded from every send. Durations: 2_weeks, 1_month, 6_months, 1_year.
Inputs: id (required), duration (required).
plunk_start_workflow_executionStart workflow for a contactADestructive
Purpose: Put one contact into a workflow immediately, without waiting for its trigger to fire.
Not for: Testing what a workflow does. This is a real run against a real contact, and steps that send mail will send it.
Returns: The created execution including its id.
Use when: A contact should go through an automation that its trigger would not catch.
Note: Irreversible once mail goes out. Cancel with plunk_cancel_workflow_execution, which only stops steps that have not run yet.
Inputs: id (required), contactId (required), context.
plunk_subscribe_contactSubscribe contactAIdempotent
Purpose: Opt a contact back in to marketing email.
Not for: Creating someone who does not exist yet, which is plunk_create_contact.
Returns: The updated subscription state.
Use when: Someone has asked to start receiving mail again. Do not use this to reverse an unsubscribe they chose.
Inputs: id (required).
plunk_test_campaignTest campaignA
Purpose: Send one copy of a campaign to a project member, so the rendered result can be checked.
Not for: The real send, which is plunk_send_campaign. This reaches one mailbox, not the audience.
Returns: Confirmation that the test was sent.
Use when: Always, before plunk_send_campaign, when nobody has seen the rendered email yet.
Inputs: id (required), email (required).
plunk_track_eventTrack eventA
Purpose: Record that a contact did something. Events drive workflow triggers and segment filters, and the contact is created if it does not exist.
Not for: Reading events back — that is plunk_list_events or plunk_get_contact_events. This writes one.
Returns: Confirmation that the event was recorded.
Use when: Something happened that automation should react to, or that you want to segment on later.
Note: Omitting subscribed preserves the contact's current subscription state; passing true would resubscribe someone who opted out. Works with or without PLUNK_PUBLIC_KEY: with it, one request; without it, the contact is upserted first and the event recorded against it. Pass idempotencyKey to make a retry safe after a timeout.
Inputs: email (required), event (required), data, subscribed, +1 more.
plunk_unarchive_campaignRestore campaignAIdempotent
Purpose: Bring an archived campaign back into the default list.
Not for: Recovering a deleted campaign. Deletion is permanent; only archiving can be undone.
Returns: The restored campaign.
Use when: An archived campaign is needed again, to review or to duplicate.
Note: Requires Plunk v0.15+.
Inputs: id (required).
plunk_unsubscribe_contactUnsubscribe contactAIdempotent
Purpose: Opt a contact out of marketing email. Transactional mail is unaffected.
Not for: Erasing them, which is plunk_delete_contact. Unsubscribing keeps the record that they opted out, which is what prevents them being mailed again.
Returns: The updated subscription state.
Use when: Someone asks to stop receiving mail. This is almost always the right tool rather than deletion.
Note: If they only want a break rather than to leave, plunk_snooze_contact pauses email for a set period and resubscribes them afterwards.
Inputs: id (required).
plunk_update_campaignUpdate campaignAIdempotent
Purpose: Replace a draft campaign's fields — subject, body, sender or audience.
Not for: A campaign that has already gone out. Sent mail cannot be edited; duplicate it instead with plunk_duplicate_campaign.
Returns: The updated campaign.
Use when: Revising a draft before it is sent.
Inputs: id (required), body, from, name, +8 more.
plunk_update_contactUpdate contactAIdempotent
Purpose: Change a contact's email address or custom data. Only the fields supplied are modified.
Not for: Changing subscription state, which has its own tools: plunk_subscribe_contact and plunk_unsubscribe_contact.
Returns: The updated contact.
Use when: Correcting an address or setting custom fields.
Note: In the data object, null deletes a key, empty strings are ignored, and reserved keys are filtered. Changing an email to one already in use returns 409.
Inputs: id (required), data, email, subscribed.
plunk_update_segmentUpdate segmentAIdempotent
Purpose: Change a segment's name, description or filter condition.
Not for: Adding or removing individual people from a STATIC segment — use plunk_add_segment_members and plunk_remove_segment_members.
Returns: The updated segment.
Use when: Refining who a dynamic segment should match.
Note: Changing the condition of a DYNAMIC segment changes who is in it, which changes who any campaign targeting it will reach.
Inputs: id (required), name, type, condition, +2 more.
plunk_update_templateUpdate templateAIdempotent
Purpose: Change fields on an existing template. Only the fields supplied are modified.
Not for: Creating a variant while keeping the original — duplicate it first with plunk_duplicate_template, then edit the copy.
Returns: The updated template.
Use when: Editing copy in place, where every campaign and workflow referencing this template should pick up the change.
Note: Live campaigns and workflows referencing this template will use the new content on their next send.
Inputs: id (required), body, from, name, +5 more.
plunk_update_workflowUpdate workflowAIdempotent
Purpose: Change a workflow's name, trigger or enabled state.
Not for: Changing what the workflow does — that is plunk_update_workflow_step and the transition tools.
Returns: The updated workflow.
Use when: Enabling or disabling an automation, or changing what sets it off.
Note: Enabling a workflow makes it live: matching contacts begin entering it, and steps that send mail will send.
Inputs: id (required), name, enabled, description, +3 more.
plunk_update_workflow_stepUpdate workflow stepAIdempotent
Purpose: Change an existing step's configuration or position.
Not for: Changing which step follows which — that is the transition tools.
Returns: The updated step.
Use when: Adjusting a delay, swapping the template a send step uses, or fixing a condition.
Note: Editing a step in an enabled workflow affects contacts already partway through it.
Inputs: id (required), stepId (required), name, config, +2 more.
plunk_upload_imageUpload imageA
Purpose: Upload an image to Plunk's storage and get back a URL usable in template and campaign HTML.
Not for: File attachments on an email — those go inline as base64 in plunk_send_transactional's attachments field.
Returns: The hosted URL of the uploaded image.
Use when: A template or campaign body needs an image that is not already hosted somewhere public.
Inputs: content (required), filename (required), contentType (required).
plunk_verify_domainVerify domain DNSARead-onlyIdempotent
Purpose: Re-check a domain's DNS records and report whether verification now passes.
Not for: Adding the domain in the first place (plunk_add_domain) or validating a single address (plunk_verify_email).
Returns: Current verification status per record.
Use when: DNS records were just published and you want to know whether they have propagated.
Inputs: id (required).
plunk_verify_emailVerify email addressARead-onlyIdempotent
Purpose: Check whether an address is plausibly deliverable: syntax, disposable-domain lists, plus-addressing and MX records.
Not for: Checking whether someone is already a contact — use plunk_get_contact or plunk_lookup_contacts. This validates an address, not your database.
Returns: A verdict on the address with the reasons behind it.
Use when: Before adding an address a user typed, or when investigating bounces.
Inputs: email (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 94 tools
Individual descriptions are unusually disciplined, each with explicit 'Not for' cross-references that separate close neighbors (add vs insert_workflow_step, refresh_segment_count vs compute_segment, get_import_status vs get_bulk_job_status). However, with 94 tools there remains real overlap among the analytics family (get_campaign_stats vs get_top_campaigns vs get_campaign_breakdown vs get_activity_stats vs get_analytics_timeseries) that an agent could easily misselect.
Virtually every tool follows the same plunk_verb_noun snake_case convention with the verb leading (list_, get_, create_, update_, delete_, send_, bulk_). Modifiers are applied consistently (bulk_ prefix, list_X_contacts/list_X_members patterns), so the naming is highly predictable throughout.
94 tools is far beyond the 25+ threshold the rubric treats as too many; the surface is heavily fragmented into many narrow single-purpose calls (separate archive/unarchive/bulk_archive, separate import vs bulk job status). While the email-marketing domain is broad, this volume will strain an agent's tool-selection budget.
Coverage is exhaustive: full CRUD and lifecycle operations for contacts, campaigns, segments, templates, workflows, events, domains and analytics, plus imports, bulk operations, activities and upcoming sends. Almost no obvious lifecycle gaps or dead ends remain.
Maintenance
Related MCP Connectors
Connect AI agents to Emitd email sending, message tracking, templates, and automations. Emitd hosts a Model Context Protocol server for integrating supported email operations into AI-agent workflows. Connect a compatible client to the hosted endpoint (https://mcp.emitd.com/mcp) and authenticate with an Emitd API key. Available tools depend on the key's permissions and enabled features. Emitd's capability areas include sending email, message activity, templates, contacts, audiences, segments, domains, analytics, inbound email, broadcasts, automations, webhooks, and suppressions. Use restricted keys, sending guardrails, and approval settings appropriate to each workflow. For more information check https://emitd.com
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Official remote MCP server of MailSenpai, the EU-hosted email marketing platform. Connect Claude, ChatGPT, Cursor or another MCP client with OAuth 2.1 and PKCE. 74 tools manage lists, subscribers, segments, templates, draft campaigns and stats, and check email DNS, blacklists and spam. Sends and deletions require explicit confirmation; every call is logged. The same team also offers SMTP Senpai, an SMTP relay and email API for transactional sending: https://en.mailsenpai.com/smtp-senpai/.
Hosted Mailchimp MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- FlicenseDqualityDmaintenanceA comprehensive Model Context Protocol server that enables interaction with the Klaviyo API, providing tools and resources for managing customer profiles, lists, segments, campaigns, flows, and various marketing automation features.473-

Tratto MCP Serverofficial
AlicenseAqualityDmaintenanceLets AI tools send transactional emails, check status, and manage contacts through the Model Context Protocol.2MIT- AlicenseBqualityCmaintenanceThe email API your AI agent can actually use. A Model Context Protocol server for Send16 that gives Claude, Cursor, and any MCP client 79 tools to send transactional & marketing email, manage contacts, audiences, segments, automations, templates, the inbox, suppressions, and webhooks.7954 npmMIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that exposes Veil Mail API operations as tools for AI agents, enabling email sending, template management, audience management, and analytics retrieval through natural language.MIT