MCP server

PristineSend exposes a remote Model Context Protocol server so an AI agent can send email, check deliverability, manage contacts, and observe what happened after a send — all as native tools. It's a thin doorway over the same API the SDK uses — every tool runs the identical deliverability, suppression, idempotency, and scope logic as the REST endpoints. Authenticate with a scoped API key; hand an agent a Send-only key and that's the only thing it can do.

Overview

Endpoint	`https://pristinesend.com/api/mcp`
Transport	`Streamable HTTP`
Auth	`Bearer API key (ps_live_… or ps_test_…)`
Tools	`send · deliverability · contacts (read/write) · email status · events · suppression check`

Endpoint & auth

The server lives at https://pristinesend.com/api/mcp. Authenticate exactly like the REST API — a Bearer API key from Settings → Developer. Each tool enforces its own scope, so a key's scopes decide which tools it can call (see Least-privilege keys). A missing or invalid key is rejected before any tool runs.

Install the plugin (Claude Code)

The fastest way to use PristineSend from Claude Code is the plugin: one install wires up the MCP server and bundles a deliverability skill — guidance that loads automatically when you're sending email, so the agent scores content before sending, sends from an authenticated domain, respects the suppression list, and confirms delivery.

# Claude Code plugin — the deliverability skill + every tool in one install.

# 1. Add PristineSend"color:#a5d6ff">'s marketplace:
/plugin marketplace add pristinesend/claude"color:#ff7b72">-plugins

# 2. Install the plugin:
/plugin install pristinesend@pristinesend

# 3. Set your key — the plugin ships NO credentials; it reads this env var.
#    Run this in your shell BEFORE starting Claude Code:
export PRISTINESEND_API_KEY="ps_live_YOUR_API_KEY"

# Now just ask: "Check this email's deliverability, then send it to a@example.com."
# The deliverability skill loads automatically and steers the agent to the tools.

The plugin ships no credentials. It reads your key from the PRISTINESEND_API_KEY environment variable on your machine — the plugin is public, but it does nothing without a valid key, which only your PristineSend account provides. Use a least-privilege key and start in the sandbox with a ps_test_ key.

Connect a client

Prefer to connect the server directly (or using another client)? Any client that speaks remote MCP over Streamable HTTP with a Bearer header works — the same server, no plugin required. The common ones:

# Claude Code (CLI) — connect with a scoped key:
claude mcp add pristinesend -"color:#ff7b72">-transport http \
  -"color:#ff7b72">-header "Authorization: Bearer ps_live_YOUR_API_KEY" \
  https://pristinesend.com/api/mcp

# Then, in a session:
#   "Check the deliverability of this email, then send it to a@example.com."

claude.ai web & mobile: the in-app custom-connector UI currently accepts OAuth connectors only (no API-key field), so use one of the clients above for now. OAuth support for the in-app connector is a planned follow-up.

Tools

Tool	Required scope	What it does
`send_email`	`email:send`	Send a transactional email — deliverability, suppression, and idempotent retries handled for you.
`check_deliverability`	`deliverability:check`	Score inbox-placement risk before sending. Pure check — sends nothing, logs nothing.
`add_contact`	`contacts:write`	Add a contact to the workspace audience (idempotent on email).
`list_contacts`	`contacts:read`	List audience contacts, newest first, with filters + cursor pagination.
`get_email_status`	`emails:read`	Look up a sent email by id: its status plus the delivered / opened / clicked / bounced / complained timeline.
`list_events`	`events:read`	Read the delivery & engagement event log (delivered, opened, clicked, bounced, complained, failed). A pull log — no webhook needed.
`check_suppression`	`suppressions:read`	Check whether an address is on the do-not-send list before you send to it.

send_email is always idempotent: pass a stable idempotency_key per logical send for full retry safety, or omit it and an identical send within a short window is de-duplicated automatically. A well-behaved agent calls check_deliverability before sending to avoid the spam folder.

The read tools close the send → observe → react loop. After send_email returns an id, call get_email_status with it to see whether the message was delivered, opened, clicked, bounced, or marked as spam; list_events is the same signal across all your sends as a pull log (no webhook endpoint required); and check_suppression tells the agent up front whether an address is on the do-not-send list, so it can skip a send PristineSend would block. These are the same projections behind the Emails, Events, and Suppressions REST endpoints.

Develop against the sandbox

Build and test your agent against a ps_test_ key. Test keys capture sends — send_email returns a normal success with a test_ id, but nothing is delivered and nothing is metered. Swap to a ps_live_ key when you're ready to send for real. See Test mode.

Least-privilege keys

Scopes are the safety story. Create a key in Settings → Developer with only the scopes the agent needs — e.g. a Send only key (email:send) can call send_email and is refused every other tool with a clear insufficient-scope error. A full-access key can use all four. This bounds the blast radius of a leaked or rogue key to exactly what you granted. See Authentication.