Skip to main content
Glama
plunk-mcp

plunk-mcp

Official
by ignytehq

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

PLUNK_API_KEY

yes

—

Secret API key (sk_*) from your project settings. Used for all admin endpoints and for /v1/send / /v1/verify.

PLUNK_PUBLIC_KEY

no

—

Public API key (pk_*). Required for plunk_track_event — Plunk's /v1/track endpoint is gated by the public key, not the secret key. Without this set, track_event will 401.

PLUNK_API_URL

no

https://next-api.useplunk.com

Base URL of your Plunk API. For self-hosted, point at the API host (e.g. https://api.plunk.example.com, or https://plunk.example.com/api if your reverse proxy maps it that way).

PLUNK_READ_ONLY

no

false

true registers only the 40 read-only tools. Nothing can be created, changed, sent or deleted.

PLUNK_ALLOW_UNCONFIRMED_SENDS

no

false

true skips the confirmation prompt before sends and bulk deletes. For headless automation only.

PLUNK_MCP_API_KEY

no

—

Takes precedence over PLUNK_API_KEY. Use it when PLUNK_API_KEY is already taken in the environment — see below.

PLUNK_MCP_API_URL

no

—

Takes precedence over PLUNK_API_URL, for the same reason.

PLUNK_SKIP_CAPABILITY_DETECTION

no

false

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

plunk_send_campaign

always

plunk_send_transactional

more than one recipient

plunk_bulk_delete_campaigns / _workflows / _templates / _contacts

always

plunk_bulk_unsubscribe_contacts

always

plunk_cancel_all_workflow_executions

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

send_transactional, track_event, verify_email

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 email

  • plunk_track_event — fire an event (which then drives workflows and segment filters)

  • plunk_create_workflow + plunk_add_workflow_step + plunk_start_workflow_execution

  • plunk_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, gotchas

With 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:

  1. Stand up ghcr.io/useplunk/plunk:latest on a separate host or subdomain. Don't disrupt your existing sender. The official guide is at docs.useplunk.com/self-hosting/introduction.

  2. Re-create your project on the new instance. Grab a fresh sk_* API key. The schemas differ; there's no in-place upgrade.

  3. Export contacts from legacy (CSV from the dashboard). Import on the new instance via plunk_import_contacts.

  4. Re-create campaigns and templates. Workflows and segments are entirely new on the modern codebase.

  5. 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.js

Tests

npm test

Contributing

Issues and PRs welcome. If an endpoint responds unexpectedly, please include:

  • Which Plunk version you're running (docker inspect <container> | grep Image plus 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 tools
plunk_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 membersA
Idempotent

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 campaignA
Idempotent

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 campaignsA
Idempotent

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 campaignsA
DestructiveIdempotent

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 contactsA
DestructiveIdempotent

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 templatesA
DestructiveIdempotent

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 workflowsA
DestructiveIdempotent

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 subscribeA
Idempotent

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 unsubscribeA
Idempotent

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 runsA
DestructiveIdempotent

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 campaignA
DestructiveIdempotent

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 runA
DestructiveIdempotent

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 segmentA
Idempotent

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 contactA
Idempotent

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 campaignA
DestructiveIdempotent

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 contactA
DestructiveIdempotent

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 fieldA
DestructiveIdempotent

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 domainA
DestructiveIdempotent

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 eventA
DestructiveIdempotent

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 segmentA
DestructiveIdempotent

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 templateA
DestructiveIdempotent

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 workflowA
DestructiveIdempotent

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 stepA
DestructiveIdempotent

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 stepsA
DestructiveIdempotent

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 feedA
Read-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 totalsA
Read-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 timeA
Read-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 statusA
Read-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 campaignA
Read-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 breakdownA
Read-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 statsA
Read-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 contactA
Read-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 historyA
Read-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 statsA
Read-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 usageA
Read-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 usageA
Read-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 valuesA
Read-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 statusA
Read-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 countA
Read-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 segmentA
Read-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 templateA
Read-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 usageA
Read-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 campaignsA
Read-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 eventsA
Read-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 workflowA
Read-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 runA
Read-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 typesA
Read-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 complaintsA
Read-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 campaignsA
Read-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 fieldsA
Read-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 contactsA
Read-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 domainsA
Read-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 namesA
Read-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 eventsA
Read-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 membersA
Read-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 segmentsA
Read-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 templatesA
Read-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 sendsA
Read-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 runsA
Read-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 fieldsA
Read-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 workflowsA
Read-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 emailA
Read-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 countA
Idempotent

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 membersA
DestructiveIdempotent

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 campaignA
Destructive

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 emailA
Destructive

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 contactA
Idempotent

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 contactA
Destructive

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 contactA
Idempotent

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 campaignA
Idempotent

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 contactA
Idempotent

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 campaignA
Idempotent

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 contactA
Idempotent

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 segmentA
Idempotent

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 templateA
Idempotent

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 workflowA
Idempotent

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 stepA
Idempotent

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 DNSA
Read-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 addressA
Read-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

    A4.2/5.0

    Scored across 94 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Lets AI tools send transactional emails, check status, and manage contacts through the Model Context Protocol.
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      The 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.
      79
      54 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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