Promptli Comms docs
Email, phone calls and SMS for AI agents: one agent identity with an inbox and a phone number.
Connect Claude, ChatGPT, Codex, Cursor or any MCP client to the hosted Promptli Comms MCP server. You sign in with OAuth, so there is no key to paste. You can also use the REST API, the Python and TypeScript SDKs, the CLI, or a plugin for Claude Code, Codex, OpenClaw, Hermes, Grok Bot or Rakazo.
What Promptli Comms is
Promptli Comms gives each AI agent its own communications identity: an email address, a phone number for texts and calls, and one conversation history per person across all three.
- Email. Every agent gets an address at
<handle>@agents.promptli.com. You can also add your own domain. The agent reads its inbox and replies in the same thread. - Texts. SMS from the agent's own phone number, including scheduled texts. Opt-outs (STOP, START, HELP) are handled for you.
- Phone calls. The agent places or schedules outbound calls. A Promptli voice assistant holds the conversation using the reason and context the agent gives it. Afterwards the agent reads the outcome, summary and full transcript. With a plugin, your own agent can also answer inbound calls.
- One history per person. The same person by email, then by text, then on the phone is one conversation, with saved contact notes.
- Test mode. Everything is simulated, so you can build without reaching real people.
The hosted MCP server is listed in the official
MCP Registry as
com.promptli/comms. Promptli Comms is made by Promptli Inc.
Quickstart: connect with one URL
Every MCP client uses the same server URL:
https://api.comms.promptli.com/mcp
It uses Streamable HTTP and OAuth 2.1 (PKCE S256 and dynamic client registration), so most clients find the sign-in on their own. When your browser opens:
- Sign in to Promptli Comms with Google or an emailed code. A new account starts on the Free plan, with no card.
- Choose your organization and pick an agent identity, or create one.
- Choose Live or Test mode. Test mode simulates everything, and nothing is sent.
For texts and calls the agent also needs a phone number. Get one in the console (the Free plan includes one) or with --number during plugin or CLI setup.
Claude (claude.ai and Claude Desktop)
- Open Customize > Connectors. Add Promptli Comms from the directory once it
is listed, or add a custom connector with the URL
https://api.comms.promptli.com/mcp. - Choose Connect and sign in as described above.
- In a chat, turn the connector on under + > Connectors. Claude asks before every email, text or call.
Try: "Check my Promptli inbox and summarize anything that needs a reply today, then draft replies for me to approve."
Claude Code
claude mcp add --transport http promptli https://api.comms.promptli.com/mcp
Then run /mcp, select promptli and choose Authenticate. For the skill and
setup commands as well, install the Claude Code plugin instead.
ChatGPT and Codex
Codex CLI, IDE extension and app:
codex mcp add promptli --url https://api.comms.promptli.com/mcp
codex mcp login promptli
codex mcp login opens your browser (use --no-browser over SSH). In ChatGPT, add a custom
connector with the URL https://api.comms.promptli.com/mcp and OAuth authentication, where your
ChatGPT plan allows custom connectors (developer mode).
Cursor
Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project), then sign in when Cursor asks:
{
"mcpServers": {
"promptli": { "url": "https://api.comms.promptli.com/mcp" }
}
}
Any MCP client
Point the client at https://api.comms.promptli.com/mcp with the Streamable HTTP transport and leave
the OAuth client ID empty. The server answers an unauthenticated request with 401 and a
WWW-Authenticate header that points to its metadata at
https://api.comms.promptli.com/.well-known/oauth-protected-resource (RFC 9728), and the authorization
server metadata is at https://api.comms.promptli.com/.well-known/oauth-authorization-server (RFC 8414).
Clients without OAuth support can send an identity-scoped API key instead:
Authorization: Bearer psk_….
Let the agent sign itself up
An agent can create its own identity with no key and no console visit. Its human only confirms a six-digit code:
POST https://api.comms.promptli.com/v1/signupwith JSON{"handle": "<your-handle>", "human_email": "<your human's email>"}. Optional:"display_name", and"test_mode": truefor the sandbox. The response has a provisional API key, and the human receives a code by email.POST https://api.comms.promptli.com/v1/signup/verifywithAuthorization: Bearer <the key>and{"code": "<six digits>"}. The same key is upgraded to full scopes for the identity.- Check progress at any time with
GET https://api.comms.promptli.com/v1/signup/status.
Install for your agent
Each plugin adds the hosted MCP server and a skill that teaches the agent how to email, text and call. Most
also have an optional background service that lets people reach your agent: it keeps an outbound
Agent Link WebSocket to Promptli, so there are no tunnels, webhooks or open ports, and it resumes
where it left off after your machine sleeps. Setup logs you in with your browser; add --number to
get a phone number and --test (where offered) for test mode.
Security: anyone who learns the agent's address or number can message it. Inbound content is marked as untrusted, but an agent can still be talked into using any tool you allow. Keep the agent's permissions tight.
Claude Code
Plugin (tools, skill, and the /promptli-comms:setup, :status and :doctor commands; it runs nothing on your machine):
/plugin marketplace add promptli-dev/claude-code-plugin
/plugin install promptli-comms@promptli
Then run /mcp, select promptli, choose Authenticate, and run /promptli-comms:setup to check the connection.
Optional service to answer inbound email and texts (macOS; Linux for development):
curl -fsSL https://comms.promptli.com/install/claude.sh | sh
promptli-claude setup
Source: promptli-dev/claude-code-plugin.
Codex
Plugin (MCP server and skills) by hand:
codex plugin marketplace add promptli-dev/promptli-codex-plugin
codex plugin add promptli-comms@promptli
codex mcp login promptli
Or everything, including the inbound service (one Codex thread per person; macOS and Linux):
curl -fsSL https://comms.promptli.com/install/codex.sh | sh
codex mcp login promptli # tools for interactive Codex
promptli-codex setup # let people email, text or call the agent
Source: promptli-dev/promptli-codex-plugin.
OpenClaw
A promptli channel next to Telegram and WhatsApp, with live phone calls and 19 promptli_* tools. Requires OpenClaw 2026.11.5 or newer and Node 24.16+ / 26.1+.
curl -fsSL https://comms.promptli.com/install/openclaw.sh | sh
openclaw promptli setup
openclaw gateway restart
Or by hand:
openclaw plugins install @promptli-npm/openclaw-plugin
openclaw promptli setup
openclaw gateway restart
To let the agent place calls, allow the optional tools in your tool policy: { tools: { allow: ["promptli_place_call", "promptli_schedule_call"] } }.
Source: promptli-dev/promptli-openclaw-plugin.
Hermes Agent
A Hermes messaging platform: Promptli shows up in hermes gateway status, cron delivery and hermes send. You need Hermes Agent installed.
hermes plugins install promptli-dev/promptli-hermes-plugin --enable
hermes promptli setup
hermes mcp login promptli
hermes gateway restart
Or use the installer, which runs the first command for you:
curl -fsSL https://raw.githubusercontent.com/promptli-dev/promptli-hermes-plugin/main/install.sh | sh
The Hermes gateway uses an identity-scoped API key (asked for in a hidden prompt); the tools use a browser login. Source: promptli-dev/promptli-hermes-plugin.
Grok Bot
- In Grok Bot, open Connect apps (or Plugins), search for Promptli Comms and choose Add, then Authenticate.
- Before the Marketplace listing is live, use Connect apps > Add a custom connector: type Remote HTTPS, URL
https://api.comms.promptli.com/mcp, headers and OAuth client ID empty. - Ask the Bot:
use promptli-status.
Optional bridge so inbound email, texts and voicemail start a run of a Grok Bot routine (ask the Bot to use promptli-setup first to create the routine):
curl -fsSL https://comms.promptli.com/install/grok.sh | sh
promptli-grok setup # browser login to Promptli, then paste the webhook URL and key
promptli-grok test-delivery # starts one test run; check the Bot's chat
Source: promptli-dev/promptli-grok-plugin.
Rakazo
- Open Integrations, then +, then From GitHub. Paste
https://github.com/promptli-dev/promptli-rakazo-plugin, choose Preview and Connect, then Add skills. - On Promptli Comms, choose Sign in and pick or create an agent.
- With a bot selected, choose Use in this bot, then ask the bot:
/promptli-status.
Optional bridge for inbound email, texts and voicemail (run /promptli-setup in the bot first to create the webhook routine):
uv tool install promptli-rakazo # or: uv tool install git+https://github.com/promptli-dev/promptli-rakazo-plugin
promptli-rakazo setup # browser login to Promptli Comms, then paste the webhook URL and key
Source: promptli-dev/promptli-rakazo-plugin.
Some plugin installers and packages are still rolling out. If a short installer URL or package isn't available yet, follow the repository's README, which has the current steps.
Python SDK, CLI, TypeScript and REST
Python SDK and CLI
pip install promptli
promptli login
promptli login opens your browser, where you pick or create an agent (add --number for a
phone number, --no-browser over SSH). promptli login --api-key and the
PROMPTLI_API_KEY environment variable also work. Other commands: promptli whoami,
promptli email send -i glow --to jane@example.com --subject Hi --text Hello,
promptli text send -i glow --to +15551234567 --text Hi, promptli events tail -i glow and
promptli doctor -i glow.
from promptli import Promptli
with Promptli() as p: # PROMPTLI_API_KEY from the environment
glow = p.identity("glow")
glow.send_email("jane@example.com", "Your booking", text="Confirmed for 3pm")
glow.send_text("+15551234567", "Reminder: 3pm tomorrow")
There is also an async client (AsyncPromptli) with an Agent Link client for receiving events over an outbound WebSocket. Source and examples: promptli-dev/promptli-comms.
TypeScript
npm install @promptli-npm/sdk
REST API
Base URL https://api.comms.promptli.com/v1. Authenticate with an API key from the console:
Authorization: Bearer psk_live_… or psk_test_…. The OpenAPI spec is
spec/openapi.json in the SDK repo.
curl https://api.comms.promptli.com/v1/identities/glow/texts \
-H "Authorization: Bearer $PROMPTLI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+15551234567", "body": "Reminder: 3pm tomorrow"}'
Tools
The hosted MCP server exposes 17 tools. Each one calls a fixed Promptli API route for the agent identity you connected. Tools marked asks first reach a person or change a scheduled send; they are annotated as destructive, so Claude and other clients ask you before each one. Read-only tools run without asking.
| Tool | What it does | Confirmation |
|---|---|---|
whoami | Shows which agent identity and organization this connection acts as, its permission scopes, and whether it is in live or test mode. | read-only |
list_conversations | Lists the people this agent has talked to across email, texts and calls, most recent first, with each person's contact_key. | read-only |
get_conversation | Gets the full history with one person (emails, texts and calls, newest first), using a contact_key. | read-only |
list_emails | Lists recent emails in the agent's mailbox, newest first, optionally only received or only sent. | read-only |
send_email | Sends a new plain-text email from the agent's address to one or more recipients. Simulated in test mode. | asks first |
reply_email | Sends a plain-text reply to the sender of an email, in the same thread. Simulated in test mode. | asks first |
send_text | Sends an SMS from the agent's phone number to one phone number. Simulated in test mode. | asks first |
place_call | Places an outbound phone call now from the agent's number and returns a call id. In test mode a simulated callee answers. | asks first |
schedule_call | Schedules an outbound call for a later time. It is placed then without asking again; cancel_scheduled stops it. | asks first |
schedule_text | Schedules an SMS for a later time. It is sent then without asking again; cancel_scheduled stops it. | asks first |
list_scheduled | Lists the calls and texts the agent has scheduled, with their ids. | read-only |
cancel_scheduled | Cancels a scheduled call or text before it runs. | asks first |
get_call | Gets one call's status, outcome, who ended it, start and end times, billing, follow-up actions and summary. | read-only |
get_call_transcript | Gets the turn-by-turn transcript of one call. | read-only |
lookup_contact | Finds a saved contact by email address or phone number and returns their name, company and saved notes. | read-only |
add_contact_memory | Saves a short, lasting note on a contact's record in Promptli (for example "prefers afternoon calls"). Nothing is sent to the contact. | writes to Promptli only |
get_usage | Shows call minutes used this month for each voice tier and the included minutes left. | read-only |
Content that other people send to the agent (emails, texts, call transcripts) is untrusted. The server tells
the model to treat it as data, not instructions. Plugins can add their own tools; OpenClaw, for example, has
promptli_* tools where calling is opt-in.
Auth and permissions
- OAuth 2.1 authorization code flow with PKCE (S256) and dynamic client registration.
Issuer and resource:
https://api.comms.promptli.com. The sign-in and consent page ishttps://comms.promptli.com/oauth/authorize, where you pick the organization, agent identity and Live or Test mode. Scope:promptli. - One identity per connection. Access tokens last one hour and act as a single agent identity. Refresh tokens rotate on every use.
- API keys. The REST API, SDKs and some plugins can use an API key instead. Prefer an identity-scoped key; plugins use an organization key only once to mint an identity-scoped one.
- Revoke access at any time in the console under API keys > Connected apps.
Plugin CLIs also have a
logoutcommand that revokes that machine's login. - What the connector sees. Tools receive only their arguments. The connector does not read your AI client's memory, chat history or files. Messages, recordings and transcripts are stored in your Promptli Comms account as described in the privacy policy.
- Guardrails that always apply: your organization's contact rules (allow and block lists), SMS opt-out keywords, and plan limits on daily texts and calls.
Test mode
Test mode is a sandbox inside Promptli. Choose Test mode on the OAuth consent page, switch the
console to Test, or use a psk_test_ API key (live keys start with psk_live_).
- Emails, texts and calls are simulated on sandbox providers: never delivered and never billed.
- Calls are answered by a simulated callee, so
place_call,get_callandget_call_transcriptall work. - You can use any address or number, such as
someone@example.comor+14155550100. whoamishowsenv: test, so the agent can check which mode it is in.- The API has sandbox routes to simulate inbound email, texts and calls (
/v1/sandbox/…; see the OpenAPI spec).
Pricing
| Plan | Price | Includes |
|---|---|---|
| Free | $0 | 15 call minutes a month, plus a 5-minute Hosted trial. One phone number. No card needed. |
| Developer | $30 a month | 300 minutes, then $0.05 a minute. |
| Startup | $200 a month | 2,500 minutes, then $0.05 a minute. |
Calls are billed in 6-second blocks. Hosted calls (where the Promptli voice assistant talks) count twice against your minutes and the Premium voice five times. Email and texts are included, and a spend cap keeps the bill where you set it. Upgrade under Billing in the console; current prices are on promptli.com/comms.
Limits and compliance
Availability
- Phone numbers are available in the US and Canada.
- US text messaging turns on as carrier (10DLC) registration completes; until then US numbers show SMS as pending. Calls work meanwhile.
- Outbound email to new recipients is being opened up gradually. If a send to a new address is refused, contact support.
- Daily limits on texts and calls, and the number of agents and numbers, depend on your plan. The API also rate-limits each key and organization; slow down and retry on
429.
Rules for calls and texts
- AI disclosure. Calls must make clear that the caller is an AI, and the agent must never claim to be human. Promptli's plugins instruct agents to open outbound calls by saying they are an AI assistant; you are responsible for disclosure on every call you place.
- Consent. Only contact people who agreed to hear from you, and follow the laws that apply to you (for example the TCPA in the US). Call only people the owner asked the agent to call.
- Calling hours. Calls to Indian (+91) numbers are allowed only between 9 AM and 9 PM IST, under TRAI rules. The plugins refuse to place or schedule calls outside that window.
- Opt-outs. When someone texts STOP, it is recorded in a consent ledger and texts to them stop until they text START. HELP gets an automatic answer. Sends to someone who opted out fail with
recipient_opted_out.
See the terms of service for acceptable use.
Troubleshooting
- "Connect with an agent identity"
The connection has no agent identity selected. Disconnect, connect again, and pick an identity on the consent page.
- "Couldn't reach the MCP server"
Usually a network or firewall problem. Check that
https://api.comms.promptli.com/mcpis reachable. A plainGETreturns405and an unauthenticatedPOSTreturns401; both mean the server is up.- The sign-in window doesn't open or loops
Allow pop-ups for your AI client, then retry. Over SSH, use the
--no-browseroption of the CLI or plugin, which shows a link and a code to enter on any device.- Nothing arrives
Run
whoami. If it showsenv: test, sends are simulated by design; reconnect in Live mode. Otherwise check the availability notes above and the recipient's opt-out status.- Texts or calls fail with no phone number
The agent identity needs a number. Get one in the console or with
--numberduring setup.- Claude doesn't ask before sending
Check your client's tool permissions. If you set a tool to "always allow", it won't ask again.
- Plugins
Each plugin has a doctor that checks the login, channels, Agent Link, clock and service:
/promptli-comms:doctororpromptli-claude doctor,promptli-codex doctor,openclaw promptli doctor,hermes promptli doctor,promptli-grok doctor,promptli-rakazo doctor, andpromptli doctor -i <handle>for the CLI.
Still stuck? Email info@promptli.com with the time of the problem and the x-request-id response header if you have it.
FAQ
How can my AI agent make phone calls?
Give the agent a Promptli Comms identity with a phone number, then connect the agent to the hosted MCP server at https://api.comms.promptli.com/mcp (or use the SDK or REST API). The agent calls place_call with the number and the reason for the call. A Promptli voice assistant holds the conversation, and afterwards the agent can read the outcome, summary and transcript with get_call and get_call_transcript. Calls can also be scheduled with schedule_call.
How do I give Claude an email address?
Add Promptli Comms to Claude as a connector with the URL https://api.comms.promptli.com/mcp, or in Claude Code run claude mcp add --transport http promptli https://api.comms.promptli.com/mcp. Sign in when asked and pick or create an agent. The agent gets the address <handle>@agents.promptli.com, and Claude can read its inbox, send email and reply in the same thread.
How do I give my AI agent its own phone number?
Sign in to the Promptli Comms console at comms.promptli.com, open your agent and get a phone number on the Phone page (the Free plan includes one). Numbers are available in the US and Canada. The plugins and the CLI can also request one during setup with --number.
Can Claude Code send text messages and make calls?
Yes. Install the Promptli Comms plugin with /plugin marketplace add promptli-dev/claude-code-plugin and /plugin install promptli-comms@promptli, then run /mcp and choose Authenticate. Claude Code can then send texts, place and schedule calls, and send and read email. Claude asks before each send or call.
Is there an MCP server for phone calls, SMS and email?
Yes. Promptli Comms runs a hosted remote MCP server at https://api.comms.promptli.com/mcp (Streamable HTTP, OAuth 2.1 with PKCE and dynamic client registration). It is listed in the official MCP Registry as com.promptli/comms and exposes 17 tools for email, texts, calls, scheduling, contacts and usage.
How do I let ChatGPT or Codex send email and texts?
In Codex run codex mcp add promptli --url https://api.comms.promptli.com/mcp, then codex mcp login promptli. In ChatGPT, add a custom connector with the URL https://api.comms.promptli.com/mcp and OAuth authentication, where your ChatGPT plan allows custom connectors.
Can I test my agent without contacting real people?
Yes. Choose Test mode when you connect, or use a psk_test_ API key. In test mode email, texts and calls are simulated on sandbox providers: nothing is delivered and nothing is billed. Calls are answered by a simulated callee.
Is it legal for an AI agent to call people?
It depends on where you call and whether you have consent. You are responsible for having consent to contact people and for following the laws that apply to you, such as the TCPA in the US. Promptli calls must disclose that the caller is an AI and must never claim to be human. Calls to Indian (+91) numbers are only allowed between 9 AM and 9 PM IST (TRAI). Recipients who text STOP are not texted again until they text START.
How much does Promptli Comms cost?
Free is $0 with 15 call minutes a month and a 5-minute Hosted trial. Developer is $30 a month for 300 minutes and Startup is $200 a month for 2,500 minutes, then $0.05 a minute on either. Calls are billed in 6-second blocks. Email and texts are included. See promptli.com/comms and the console for current pricing.
Does my agent need a public server or webhook to receive messages?
No. Agent Link is an outbound WebSocket from your agent to Promptli, so there is no public URL, tunnel or open port. It resumes from where it left off after restarts. The Claude Code, Codex, OpenClaw, Hermes, Grok Bot and Rakazo plugins use it to answer people who email, text or call the agent. Signed webhooks are also available.
Support
- Email: info@promptli.com
- Console: comms.promptli.com
- SDKs and CLI: github.com/promptli-dev/promptli-comms
- For AI agents: promptli.com/llms.txt and promptli.com/comms/llms.txt