AI assistants
Connect your AI tool to Postal
Connecting means giving an AI assistant permission to work in your Postal account. After that, you ask in plain English and it looks up contacts and sends, sends emails and creates campaigns, only within what you have authorized.
In a nutshell
How it works
Three steps, and what changes from one tool to another is where you paste the address.
1. Choose your tool
Each one has its own step-by-step guide, with what to copy and where to paste it.
2. Sign in with your account
You enter the Postal address, choose the team and click Allow. Some tools also accept an API key.
3. Ask in plain English
For example: “list my domains”. The assistant uses Postal's actions and answers in the conversation.
Tools
Choose your tool
There are 12 tools, from chat assistants to code editors and app builders. The badge tells you plainly how much we have tested.
Cursor
Connect the Cursor editor to Postal to look up domains, deliveries and templates and send test emails without leaving your code.
See how to connectTested by usClaude
Add Postal as a custom connector in Claude (web, desktop and mobile) and ask it to look up and send emails in plain language.
See how to connectTested by usClaude Code
Add Postal to Claude Code with one command and use the terminal to diagnose deliveries and send test emails.
See how to connectCompatible per the specificationCodex
Set up Postal in Codex (CLI, IDE extension and app) with a few lines in config.toml.
See how to connectTested by usGitHub Copilot
Use Postal in GitHub Copilot: in VS Code via OAuth, in the Copilot CLI and in the Copilot cloud agent with an API key.
See how to connectCompatible per the specificationGemini
Connect Postal to the Gemini CLI (and to Antigravity, which replaces it for those without a paid plan) to look up and send emails from the terminal.
See how to connectCompatible per the specificationv0
Connect Postal to v0 so it can look up your domains and templates and send test emails while it generates the app.
See how to connectCompatible per the specificationBolt
Add Postal as a custom Bolt connector to look up and send emails while you build your project.
See how to connectCompatible per the specificationLovable
Connect Postal to Lovable as a custom MCP server to use your email data in the project chat.
See how to connectCompatible per the specificationReplit
Add Postal as an MCP server in Replit Agent and use your domains, templates and sends in the project.
See how to connectTested by usChatGPT
Add Postal as a custom MCP server in ChatGPT and chat with your email data.
See how to connectCompatible per the specificationWindsurf
Connect Postal to Windsurf's Cascade (now in the Devin Desktop documentation) with a block in mcp_config.json.
See how to connectWhat each badge means is explained in the compatibility matrix.
MCP server
What the Postal server offers
Postal has an MCP server, the open standard AI assistants use to talk to other systems. It is what you connect.
One address for all tools
The URL is the same for all apps. The API domain is https://api.postal.so and the endpoint is /mcp.
- Transport: stateless Streamable HTTP. POST only on
/mcp; there is no old HTTP+SSE transport. If the app lets you choose between HTTP and SSE, choose HTTP. - 34 tools the assistant can use, plus 2 resources (domains and a getting-started guide) and 2 ready-made playbooks (write and send a campaign, diagnose delivery).
- Two ways to sign in: with your account (OAuth) or with an API key.
https://api.postal.so/mcpAuthentication
Two ways to sign in
Most tools accept both. Each tool's page says which is the recommended path.
OAuth 2.1 (recommended)
Each person signs in with their own Postal account and chooses one team on the permission screen. The app registers itself and access lasts 1 hour, renewed by a 30-day code that changes with every use.
API key in a header
For apps that accept fixed headers: Authorization: Bearer ps_..., with a key created in the dashboard, under API keys. The full-access key (full_access) sees all 34 tools; the send-only key (sending_access) sees only send_email and track_event.
Good to know
- The tools run the same endpoints as the REST API: the same validation, daily quota, sending pause, suppression list and per-second request limit of the plan (429 response
rate_limit_exceeded). - Lists return at most 100 items per call (default 20), in pages. Ask for fewer items when you can.
send_emailacceptsidempotency_key: repeating the call does not send the email twice.
Access
Scopes: what each access allows
A scope is a permission. Postal has three, from the most restricted to the broadest.
| Access | What it unlocks | Tools |
|---|---|---|
Read your datamcp:read | View emails, domains, contacts, segments, topics, templates, broadcasts, automations, forms, inbox conversations, metrics and usage. 22 tools (list_*, get_*). | 22 toolslist_domains, get_email, get_metrics |
Send emails and eventsmcp:send | Send and schedule emails from verified domains and record events for automations. 2 tools. On its own it does not allow viewing an email's status (get_email requires mcp:read). | 2 toolssend_email, track_event |
Manage everythingmcp:full | Everything in the previous ones, plus creating, changing and deleting contacts and templates, creating and sending broadcasts (send_broadcast requires confirm: true), canceling scheduled emails and working in the inboxes (organize, reply, create drafts). 10 write tools. | 10 toolssend_broadcast, create_contact, reply_to_inbox_thread |
mcp:full includes the other two. Apps request all three scopes by default (the server announces them in the WWW-Authenticate header) and the consent screen grants the requested set; the person chooses the team, not the scopes.
To limit this, pin the scope in the app's configuration when it allows it (Claude Code: oauth.scopes; Codex: scopes; Cursor: auth block with a client id you registered) or use a sending_access API key (send-only).
Step by step
Validate the connection
Before configuring an app, confirm that the server responds and that the app will find the authorization server. You don't need to be technical to connect: this part is for those who want to see the proof.
Check that OAuth discovery responds
The command below asks Postal for the account sign-in details. It should respond 200 with a JSON (issuer, authorization_endpoint, token_endpoint, registration_endpoint and code_challenge_methods_supported ["S256"]). If it responds 403 or an HTML page, something in front of the server is blocking the /.well-known path and apps with OAuth won't be able to connect. In that case, let us know through the contact form.
curl -i https://api.postal.so/.well-known/oauth-authorization-serverCheck the authentication challenge
Without a token, the server should refuse and say where the sign-in is: the expected response is 401, with the WWW-Authenticate header below.
curl -i -X POST https://api.postal.so/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"teste","version":"1"}}}'WWW-Authenticate: Bearer resource_metadata="https://api.postal.so/.well-known/oauth-protected-resource/mcp",
scope="mcp:read mcp:send mcp:full"List the tools with an API key
With a full-access key, the list should have 34 tools; with a send-only key, 2. Replace ps_... with your key. We tested this command line on Inspector version 2.12.0; option names may change in other versions.
npx @modelcontextprotocol/inspector --cli https://api.postal.so/mcp \
--transport http \
--header "Authorization: Bearer ps_..." \
--method tools/listOr use the web interface, signing in with your account
Run the command, choose the Streamable HTTP transport, paste the server address and connect. The Inspector walks you through the Postal sign-in in the browser: choose the team and allow. The exact button names change between Inspector versions. After connecting, the list should show all 34 tools (send_email, list_domains, list_contacts...), and running get_usage should return the plan usage of the team you chose.
npx @modelcontextprotocol/inspectorCheck the connection in the dashboard
The connection appears under Settings › AI connections, with the app, the team and the last use. This is also where you revoke it.
Status of each one
Compatibility matrix
One row per tool: how it signs in, which transport it uses and how much we have tested.
| Tool | Type | How you sign in | Transport | Status |
|---|---|---|---|---|
| Cursor | Editor | Account (OAuth) or API key | HTTP | Compatible per the specification |
| Claude | Assistant | Account (OAuth) | HTTP | Tested by us |
| Claude Code | Command line | Account (OAuth) or API key | HTTP | Tested by us |
| Codex | Command line | Account (OAuth) or API key | HTTP | Compatible per the specification |
| GitHub Copilot | Editor | Account (OAuth) or API key | HTTP | Tested by us |
| Gemini | Command line | Account (OAuth) or API key | HTTP | Compatible per the specification |
| v0 | App builder | Account (OAuth) or API key | HTTP | Compatible per the specification |
| Bolt | App builder | Account (OAuth) or API key | HTTP | Compatible per the specification |
| Lovable | App builder | Account (OAuth) or API key | Not specified | Compatible per the specification |
| Replit | App builder | API key or account (OAuth) | Not specified | Compatible per the specification |
| ChatGPT | Assistant | Account (OAuth) | HTTP | Tested by us |
| Windsurf | Editor | API key or account (OAuth) | HTTP | Compatible per the specification |
We ran Postal's automated tests with the real documents and redirect addresses the app publishes, and with the official MCP SDK client. It is not a test inside the actual application. Each tool's page has the full note on what was and was not verified.
We follow the app's specification and documentation, but have not yet tested with the actual app. Each tool's page has the full note on what was and was not verified.
What “tested by us” means, exactly
Verified by a Postal automated test with the real artifacts the app publishes (client metadata document, documented redirect URIs) and with the official MCP SDK client. It is not a test inside the app's product.
How we tested (10/28/2026). A local test server (php artisan serve, SQLite) exercised by a Node client with @modelcontextprotocol/sdk 1.32.2 (discovery, dynamic registration, PKCE, token, refresh with rotation, initialize, tools/list, tools/call, API key in a header), by the MCP Inspector in CLI mode and by automated tests (PHPUnit) that use the real metadata documents published by Claude, Claude Code, ChatGPT and VS Code.
This is not a badge from the vendor. For none of the tools in the table did we run the connection inside the actual application: that is why each page shows, besides the badge, the full note on what was and was not verified.
Before connecting
Frequently asked questions
Do I need a specific plan?
It depends on the plan. The team must have the MCP server feature on its plan; without it, the server responds with a 403 plan_limit_reached error. Some tools also have their own plan or permission rules (for example, who can add connectors): they appear under “Before you start”, on each tool's page. See the plans under Pricing.
Can I limit what the assistant does?
Partly. Access comes in three levels (read, send and manage everything), in the scopes table. With an API key, the send-only key (sending_access) exposes only send_email and track_event. When signing in with your account, apps request all three scopes by default and the permission screen grants the requested set: you choose the team, not the scopes. Some tools let you pin the scopes in the configuration (Claude Code, Codex and Cursor, for example); each tool's page says what applies to it. Even with full access, sending a campaign requires explicit confirmation (confirm: true).
How do I revoke access?
In the Postal dashboard, under Settings › AI connections: each connection appears with the app, the team and the last use, and can be revoked at any time. If you used an API key, revoke the key under API keys. The details are in the MCP server documentation and in Authentication.
Does my data go to the AI company?
Only what the tool looks up. When you ask for something, the tool calls Postal's actions and receives the result (for example, the list of your domains or the data of an email). That result becomes part of the conversation and falls under the rules of that tool's company. Postal only answers what the tool asks, within the access you authorized, and each connection acts on a single team. Read the policy of the tool you choose and give it only the access it needs. For the data held in Postal, see the Privacy Policy.
What if the connection fails?
- Check the address:
https://api.postal.so/mcp, with/mcpat the end, and the HTTP connection type. Postal does not offer SSE. - Check that the team has the "MCP server" feature on its plan. Without it, the server responds 403
plan_limit_reached. - To send emails, the team needs at least one verified domain.
- Each connection acts on a single team. To use another one, connect again and pick the other.
- Run the “Validate the connection” tests above. If OAuth discovery does not respond 200, apps with OAuth can't connect.
- 429 response (
rate_limit_exceeded): the plan's requests-per-second limit was reached. Wait a moment and try again. - Still not solved? See “If something goes wrong” on the tool's page and the MCP server documentation, or talk to us through the contact form.
Want to connect your tool?
Create your account and connect your assistant. If you need help, talk to us through the contact form.