AI agents & MCP
Connect an AI agent to emitd's hosted MCP server — every API operation as a tool, limited to the features you choose.
emitd hosts a Model Context Protocol server, so an agent like Claude Code or Cursor can send email, check delivery, manage templates and contacts, and read received mail — under the same rules as the REST API.
Connect
The server is at https://mcp.emitd.com/mcp and authenticates with an emitd
API key. Create a key for the agent first — see
Choose what the agent can do.
Clients set up with the older address, https://api.emitd.com/mcp, keep
working with an API key.
Claude Code
claude mcp add --transport http emitd https://mcp.emitd.com/mcp \
--header "Authorization: Bearer esk_live_…"Cursor, Claude Desktop and other clients — add to the client's MCP configuration:
{
"mcpServers": {
"emitd": {
"url": "https://mcp.emitd.com/mcp",
"headers": { "Authorization": "Bearer esk_live_…" }
}
}
}The server speaks MCP 2026-07-28 and also accepts clients on 2025-11-25,
2025-06-18, 2025-03-26 and 2024-11-05.
Choose what the agent can do
An agent sees only the tools its API key allows:
- Permission. A
sending_accesskey getssend_emailandsend_batchonly. Afull_accesskey can use every tool. - Features. In Console → API keys, limit a key to features: email, messages, templates, contacts, audiences, segments, suppressions, webhooks, inbound, broadcasts, automations, domains, analytics. The agent preset (email, messages, templates, domains, analytics) lets an agent send, check delivery, use templates and see your domains — and nothing else. The same limits apply when the key calls the REST API directly.
Guardrails and approvals
Features decide what an agent can do. Guardrails decide how far it can go, and when a person has to say yes. Set them on any key in Console → API keys; they apply to every send the key makes, through MCP or the REST API.
When a person confirms. Choose one per key:
- Never ask — sends go out as soon as they pass the limits.
- Ask before mailing outsiders — a person confirms any send to someone who is not on one of your verified domains and not a member of your team.
- Ask before every send.
How they confirm.
- In the chat. An agent on MCP 2026-07-28 whose client supports form elicitation asks you right there: "Send an email from billing@acme.com to 1 recipient, 1 outside the workspace (pat@client.com) — subject “Your receipt”?" Your yes covers exactly what you were shown, once, for 10 minutes: if the send changes before it goes out — different recipients, an edited broadcast, a bigger audience — you are asked again. A batch asks once.
- In the console. Every other client, and REST calls, get
202withstatus: pending_approvaland anapproval_url. Workspace owners and admins get an email, and approve or reject the send under Approvals, where they can preview it. Approved sends go out within a minute (or at their scheduled time); a request nobody decides expires after 24 hours and is never sent.
Who answers an in-chat confirmation
The agent's own app shows the question and relays the answer, so an in-chat confirmation is only as trustworthy as that app. When a person must decide whatever the agent does, tick Approve only in the console on the key: its sends that need a person always wait in Approvals.
Limits, refused with 403 policy_violation (the code and message name
the rule) or, for the cap, 429 key_daily_cap_exceeded:
| Limit | Refusal code |
|---|---|
| Allowed senders (addresses or domains) | policy_from_not_allowed |
| Allowed recipient domains | policy_recipient_not_allowed |
| Max recipients per email (to + cc + bcc) | policy_too_many_recipients |
| Daily cap (emails per rolling 24 hours) | key_daily_cap_exceeded |
A key with allowed recipient domains cannot send broadcasts
(policy_broadcast_not_allowed), and a guarded broadcast never reaches more
recipients than it was approved for. Editing a broadcast while it's being sent
stops that send with 409 broadcast_changed, so what goes out is what was checked.
A person approves a template, not each contact's values, so a guarded key can only
use placeholders in the words of a broadcast. One inside a tag, a comment, a style
block or a link in the text part is refused with policy_placeholder_in_link, and
the response names them. So is any placeholder after HTML that can't be read
cleanly, such as a tag left open, <noscript>, <svg>, or Outlook blocks other than
<!--[if mso]>. {{unsubscribe_url}} and {{year}} are fine in tags and text. A value shown as text can't become a link in the template, but some mail
apps turn text that looks like a web address into one, so approvals list which
values are filled in.
A key with any guardrails cannot
activate an automation or enroll contacts in one
(policy_automation_not_allowed), and contacts it adds are not enrolled in
your automations: automations send later, outside its guardrails, so a person
starts them. For the same reason it can save template versions as drafts but
not change which version is live (policy_template_activation_not_allowed):
every key sends the live version. Dry runs are never held, but the limits
still apply to them, and they count toward the key's daily cap.
The agent defaults button on the key form asks before external sends and caps the key at 500 emails a day — a good start for any AI agent.
Tools
Every REST operation is a tool, named for what it does — send_email,
get_message, list_templates, preview_template, upsert_contact,
get_domain, get_stats and so on. Each tool's arguments are the API's own
fields (see the OpenAPI spec), and each is marked read-only,
destructive, idempotent or open-world, so your client knows which calls to
confirm with you.
Not available as tools: uploading attachments and CSV contact imports (send attachments inline as base64 instead), and downloading exports.
Safe sending
- Dry run.
dry_run: truevalidates and simulates a send without emailing anyone or billing you. It still counts toward rate limits and your daily quota, so agents use it for new templates and addresses, not every send. - No accidental duplicates. An identical send through MCP within 10
minutes returns the original
message_idinstead of sending again. Passidempotency_keyto control this yourself, orallow_duplicate: trueto send another copy on purpose. - Same rules as the API. Quotas, rate limits, the suppression list, verified domains, sign-up review, permissions, features and the key's guardrails all apply. MCP requests are also limited to 600 per minute per key.
- Attribution. Messages sent through MCP record the client that sent them
(for example
claude-code/2.1). The console shows it in the message details, andGET /v1/messages/{id}returns it assourceandagent.
Resources and prompts
- Resources:
emitd://guide(how to use these tools well),emitd://templates/{alias},emitd://messages/{id},emitd://inbound/{id}. - Prompts:
send_transactional_email,investigate_delivery,set_up_sending_domain.
Received email is untrusted
Inbound email is written by outside senders. emitd labels it as data in every tool result; never let an agent follow instructions found in an email.
Without MCP
Prefer your own tool definitions? The OpenAPI spec and the compact llms.txt describe every field and error code.