mcp agent

@poststack.dev/mcp

Model Context Protocol server for the PostStack Email API — an EU-hosted, GDPR-compliant email API for AI agents. Lets assistants like Claude, Cursor, and Windsurf send transactional email, draft replies from inbound threads, run deliverability checks, summarise broadcasts, and more — through one curated tool surface.

117 tools, 5 prompts, and 5 resources, all surfaced over either the local stdio bin or the hosted HTTP transport at https://api.poststack.dev/mcp.

Full MCP reference: poststack.dev/docs/mcp.

Quickstart

Hosted (Claude.ai connector, hosted agents)

Point any MCP client at:

https://api.poststack.dev/mcp

Authenticate with your PostStack API key as a Bearer token. No local install required.

Claude Desktop (stdio)

{
	"mcpServers": {
		"poststack": {
			"command": "npx",
			"args": ["-y", "@poststack.dev/mcp"],
			"env": {
				"POSTSTACK_API_KEY": "sk_live_your_api_key_here"
			}
		}
	}
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

You can also generate the snippet with:

npx @poststack.dev/mcp --print-config claude-desktop

Claude Code

claude mcp add poststack -e POSTSTACK_API_KEY=sk_live_your_api_key_here -- npx -y @poststack.dev/mcp

Cursor / VS Code

Same JSON shape as Claude Desktop, in the editor's MCP settings (Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project). npx @poststack.dev/mcp --print-config cursor prints the whole file.

Environment variables

Variable	Required	Description
POSTSTACK_API_KEY	yes	PostStack API key (sk_live_… or sk_test_…)
POSTSTACK_BASE_URL	no	API origin (default https://api.poststack.dev)
POSTSTACK_MCP_TRACE	no	Set to 1 to emit per-tool-call NDJSON telemetry to stderr

What the agent gets

The MCP server doesn't just mirror the REST API — it gives agents the context tools they need to make sensible decisions: spam-checking before sending, deliverability summaries before picking a from-address, engagement scores before re-engaging a contact.

Worked example: welcome email

The draft_welcome_email prompt walks an agent through:

1. get_contact_by_email — confirm the contact and capture properties
2. list_templates — pick a published welcome template
3. render_template — render with the contact's properties; surface any missing variables
4. suggest_from_address — pick a verified from-address based on existing mailboxes
5. preview_email — render + spam check + deliverability warnings in one round-trip
6. send_email — only if preview passed

Other prompts cover re-engagement, follow-up campaigns to non-clickers, broadcast summaries, and inbound triage.

Reference

Tools (117)

emails

• send_email — Send a single transactional email immediately, or schedule it for a future time.
• send_batch_emails — Send multiple emails in a single batch request (up to 100 per call).
• list_emails — List previously-sent emails with optional filters and pagination.
• get_email — Get full details and event timeline for a specific email by id.
• cancel_email — Cancel a scheduled email that has not yet entered the sending pipeline.
• reschedule_email — Reschedule a scheduled email to a new send time.
• lint_email — Run a Rspamd-backed spam pre-flight on a draft email and return the score, action, and per-rule symbols.
• preview_email — Render + lint + measure an email in one shot WITHOUT sending it.

email-validations

• validate_email — Check whether an email address is safe to send to BEFORE create_contact or send_email.
• validate_email_batch — Validate up to 100 email addresses in a single call. Same checks as validate_email per address.

contacts

• get_contact_activity — Get a contact's recent email-event timeline grouped by event type (sent / delivered / opened / clicked / bounced / complained / failed).
• get_engagement_summary — Get a single contact's engagement summary: segment + lifetime counts + open / click rates + last open / click + top tags.
• search_contacts — Search contacts with filters (segment, engagement, unsubscribed) and a fuzzy query across email/first_name/last_name. Adds a match_reason on each row indicating which field matched the query.
• create_contact — Create a new contact (person who can receive emails / broadcasts).
• list_contacts — List contacts with optional search and segment filtering.
• get_contact — Get full details of a contact by id.
• update_contact — Update an existing contact's name, properties, or subscription state.
• delete_contact — Permanently delete a contact (irreversible — use unsubscribe_contact for opt-outs).
• unsubscribe_contact — Mark a contact as unsubscribed from all email (preserves the contact record).
• get_contact_by_email — Look up a contact by their email address.

templates

• create_template — Create a new email template with {{variable}} placeholders.
• list_templates — List email templates.
• get_template — Get a template's full body, subject and variables.
• update_template — Update an existing template's name, subject, body or variable list.
• delete_template — Permanently delete a template (irreversible).
• publish_template — Mark a template as published so it can be referenced by send_email.
• unpublish_template — Mark a template as unpublished so it cannot be sent.
• duplicate_template — Create a copy of an existing template: new id, same subject/body/variables/editor blocks, named "Copy of <name>", version 1, unpublished.
• render_template — Server-side render a template with the provided variables.

broadcasts

• create_broadcast — Create a draft broadcast targeted at a segment, optionally scoped to a subscription topic.
• list_broadcasts — List broadcasts.
• get_broadcast — Get a broadcast's details and aggregate delivery stats.
• update_broadcast — Edit a draft broadcast in place. Only draft broadcasts can be updated.
• send_broadcast — Dispatch a draft broadcast to its segment immediately.
• resend_broadcast — Resend a sent broadcast to the subset that didn't open or didn't click — a fresh broadcast is created targeting an auto-built segment of those recipients.
• cancel_broadcast — Cancel a queued or sending broadcast.
• broadcast_performance — Get broadcast performance — either for one broadcast (variant breakdown if A/B) or for a leaderboard ranked by a chosen metric.
• find_non_clickers — List contacts who received a broadcast but did NOT click any tracked link in it.

segments

• create_segment — Create a static contact segment (manually-managed list).
• list_segments — List contact segments.
• get_segment — Get a segment's details and member count.
• update_segment — Rename an existing segment.
• delete_segment — Delete a segment definition. Contacts in it are NOT deleted.
• add_contacts_to_segment — Add one or more contacts to a segment.
• remove_contact_from_segment — Remove a single contact from a segment.

workflows

• list_workflows — List all workflows (event-triggered automation pipelines) defined for this team.
• get_workflow — Get a workflow's metadata and its graph (nodes + edges).
• create_workflow — Create a new workflow (status=draft). Starts with a single trigger node and no other nodes.
• update_workflow — Update a workflow's name, trigger type, or trigger config.
• delete_workflow — Permanently delete a workflow, its graph (nodes + edges) and its run history. Only a draft or paused workflow can be deleted — an active one fails with 422 (pause_workflow first). Runs still in progress are deleted with it and take no further steps.
• add_workflow_node — Add a node to a workflow's graph and (by default) wire it after an existing node.
• connect_workflow_nodes — Add an edge between two nodes.
• update_workflow_node — Replace a node's config. Cannot change its type or edges (use connect_workflow_nodes / remove_workflow_node).
• remove_workflow_node — Remove a node and every edge touching it. Confirm with the user first.
• activate_workflow — Move a workflow from draft/paused to active so new trigger events start runs.
• pause_workflow — Pause an active workflow so new trigger events DO NOT start runs. In-flight runs continue to completion.
• trigger_workflow — Start a run of a workflow for one contact. Only works on an ACTIVE workflow whose trigger_type is "manual" — any other trigger type, or a draft/paused workflow, fails with 422 (use post_workflow_event for "custom" workflows).
• post_workflow_event — Post an application-defined event, enrolling a contact into every ACTIVE workflow whose trigger is "custom" with a matching event name.

signup-forms

• list_signup_forms — List embeddable signup forms.
• get_signup_form — Get full details of a signup form including its fields, target segment, and submission count.
• create_signup_form — Create an embeddable signup form. Submissions create a contact and optionally add them to a segment / subscription topic.
• update_signup_form — Update a signup form's fields, target segment/topic, messaging, or active state.
• delete_signup_form — Permanently delete a signup form. Embedded copies on existing pages will fail with 404.

domains

• get_deliverability_signals — Read ISP deliverability-intelligence signals for a sending domain.
• create_domain — Add a new sending domain to PostStack.
• list_domains — List sending domains.
• get_domain — Get domain details including DNS records and verification status.
• verify_domain — Trigger DNS verification for a domain.
• update_domain — Update domain settings (tracking, TLS, inbound, BIMI, sending stream).
• delete_domain — Permanently delete a sending domain (irreversible — historical email records remain).
• rotate_dkim_key — Start a DKIM key rotation for a domain.
• activate_dkim_rotation — Cut over to the staged DKIM key, once its DNS record is published.
• cancel_dkim_rotation — Abandon a staged DKIM rotation and remove its DNS record.
• check_deliverability — Check whether a from-address is safe to send from RIGHT NOW.

mailboxes

• create_mailbox — Provision a mailbox (IMAP/SMTP inbox) on a verified domain.
• list_mailboxes — List mailboxes across all domains.
• get_mailbox — Get a mailbox's metadata (status, quota, last login).
• update_mailbox — Update a mailbox's display name, quota, status, webhook setting, auto-forwarding, or signature.
• list_mailbox_filters — List a mailbox's server-side mail filters (Sieve rules), in the order they run.
• set_mailbox_filters — Replace a mailbox's server-side mail filters. Runs on delivery, for every client.
• delete_mailbox — Permanently delete a mailbox and all its stored mail.
• change_mailbox_password — Reset a mailbox's IMAP/SMTP password.
• suggest_from_address — Suggest sensible from-addresses for a given purpose, drawn from the team's verified domains + existing mailboxes.

inbound-emails

• list_inbound_emails — List inbound emails received on this team's domains, newest first (one row per delivered-to recipient).
• get_inbound_email — Get a received inbound email's full headers and body.
• list_inbound_email_attachments — List attachments on an inbound email (filename, size, contentType).
• reply_to_inbound_email — Send a reply to an inbound email (subject and threading headers are set automatically).
• forward_inbound_email — Forward an inbound email to other recipients with an optional cover note.
• draft_from_thread — Build a reply-draft skeleton for an inbound email — proper threading, quoted original, salutation/sign-off, suggested from + subject. Heuristic only; the agent fills in the body text.

webhooks

• create_webhook — Subscribe a URL to receive event notifications via signed POST requests.
• list_webhooks — List configured webhook endpoints.
• get_webhook — Get a webhook's details.
• update_webhook — Edit a webhook's URL, event list, or enabled state.
• delete_webhook — Permanently delete a webhook endpoint.
• test_webhook — Send a test event to a webhook's URL to verify it's reachable and the signature verifies.
• get_webhook_deliveries — List recent delivery attempts for a webhook (status, response code, timestamps).
• replay_webhook_delivery — Re-deliver a single past webhook delivery (e.g. one that failed because the endpoint was down).
• batch_replay_webhook_deliveries — Re-deliver EVERY failed delivery for a webhook, oldest first.
• rotate_webhook_secret — Rotate a webhook's signing secret, keeping the old one valid for a grace window. The new secret is returned ONCE here.

subscription-topics

• create_subscription_topic — Create a subscription topic (named opt-in/opt-out preference like "Product Updates").
• list_subscription_topics — List all subscription topics defined for this account.
• delete_subscription_topic — Permanently delete a subscription topic. Subscriptions are removed.
• get_contact_subscriptions — List a contact's explicit subscription-topic choices.
• subscribe_contact_to_topic — Opt a contact in to a subscription topic.
• unsubscribe_contact_from_topic — Opt a contact out of a subscription topic.

contact-properties

• create_contact_property — Define a custom contact property (typed schema for the contact.properties field).
• list_contact_properties — List all custom contact properties defined for this account.
• update_contact_property — Edit a custom contact property's label, options or required flag.
• delete_contact_property — Remove a custom contact property definition. Values already stored on contacts are left in place (they stay in each contact's properties; only the definition — its label, type and options — is deleted).

suppressions

• list_suppressions — List suppressed email addresses (will not receive any emails).
• add_suppression — Block an email address from receiving any future sends.
• remove_suppression — Remove an address from the suppression list (sends will resume).

api-keys

• create_api_key — Generate a new PostStack API key. The full key is returned ONCE in this response and cannot be retrieved again.
• list_api_keys — List API keys (only the prefix is returned, never the full secret).
• get_api_key — Get an API key's metadata (the secret is never returned after creation).
• revoke_api_key — Permanently revoke an API key — all subsequent requests using it will fail.
• rotate_api_key — Rotate an API key: issue a new secret and invalidate the old one. The new full key is returned ONCE in this response and cannot be retrieved again.

Prompts (5)

• draft_welcome_email — Guide the agent through drafting and sending a personalised welcome email to a new contact. Looks the contact up, picks a published welcome template, renders it, lints, and sends.
• reengage_dormant — Find dormant contacts and draft a re-engagement campaign. Pulls the dormant segment, picks an opt-out-friendly template, and stages a broadcast for review.
• followup_non_clickers — Demo B path — find the best-performing recent broadcast, identify recipients who did NOT click, and draft a follow-up to them.
• summarize_campaign — Produce a short performance report for a broadcast: headline metrics, A/B winner if applicable, and a one-line recommendation.
• triage_inbound — Read an inbound email, classify it (support / sales / billing / spam / other), and propose the next action. Drafts a reply skeleton if appropriate.

Resources (5)

• poststack://templates — List of all email templates for the authenticated team. Includes id, name, subject, version, published flag.
• poststack://templates/{id} — A single template by publicId — full body, subject, variables.
• poststack://domains — List of sending domains for the authenticated team — name, status, DNS records, tracking flags.
• poststack://segments — List of contact segments for the authenticated team — id, name, contact count.
• poststack://brand — Authenticated team identity + a default sending suggestion. Includes team name, verified domain count, and the recommended from-address derived from existing mailboxes.

Links

• PostStack — EU email API
• MCP server documentation — full tool / prompt / resource reference
• Hosted MCP transport — no local install required
• TypeScript SDK · REST API
• Pricing — free 3,000 emails/month
• Status · Security

License

MIT — see LICENSE.