Guides

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."

Connect from claude.ai (web & mobile)

The in-app custom-connector UI accepts OAuth connectors only — there is no API-key field — and PristineSend supports OAuth, so no key is involved. Add https://pristinesend.com/api/mcp as a custom connector and sign in. Your credentials stay on your side: nothing is pasted into a conversation.

Connecting is step one of two — grant it access. A newly connected agent starts with no scopes at all, on purpose: an agent should never inherit your whole account just by connecting. Until you grant it, the connector authenticates fine but every request is refused, and clients usually render that as “this connector has no tools available” — which looks like a broken integration and is really a permission waiting to be given. Open Settings → Connected agents (MCP), tick the scopes you want it to have, and save. Set Default access for new agents in the same place and future connections start with those scopes instead of none. Revoke takes away all of an agent's access. It stays on the list with no access until you tick scopes and save again. If you reconnect a client and it registers a new identity, that new agent starts with your default access.

Tools

Tool	Required scope	What it does
`send_email`	`email:send`	Send a transactional email — deliverability, suppression, and idempotent retries handled for you.
`send_bulk`	`email:send_bulk`	Draft a campaign to a segment and hold it for a human to approve. Sends nothing on its own; see the Bulk send reference.
`create_segment`	`segments:write`	Build an audience from a filter and read back the recipient count plus a masked sample, so the filter can be checked before anyone approves a send.
`check_deliverability`	`deliverability:check`	Score an email against the editor's deliverability rules 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.
`list_clicked_links`	`campaigns:read`	Rank the links a campaign's readers clicked. Unsubscribe links are counted, never named.

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, and holds on a DANGER verdict — it means something in the email is unfinished.

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.