Email for agents.

Build with Cursor, Codex, or Claude Code. The agent reads auth.md, connects hosted MCP, and sends through the same typed email API your app uses. You inspect the email it sent.

( ZERO TO FIRST SEND )

The email API your agent wires up for you.

Hand Cursor or Codex a short brief. It reads the credential guide, connects over MCP or the samva CLI, and calls the send tool. The message id and delivery status come back for you to check.

# brief for a coding agent

Read https://samva.dev/auth.md, create an API key,
then follow the quickstart to send email.

→ tool messages_send_email
  { to: "ada@example.com",
    subject: "Your code is 391042" }

← result
  { id: "msg_7q2xk9mvt4znw8rh", status: "pending" }

( HUMAN-ONLY SETUP )

Email APIs were built for a human at a keyboard.

Email APIs expect a person in a dashboard.

Setup assumes someone clicks through a console, copies a key by hand, and reads a getting-started page written for human eyes.

A handed-off credential reaches too far.

A shared password or an over-broad key gives an agent more of the organization than the one job you meant to delegate.

Setup docs don't read as instructions.

An agent cannot follow a screenshot. Prose written for people leaves the agent to guess at auth, the send call, and what to do next.

( HOW IT WORKS )

Read auth.md. Connect MCP. Send.

#01 — READ

Point it at auth.md.

The agent fetches samva.dev/auth.md and picks a credential: an API key for unattended work, or samva login when a human is at the terminal.

GET https://samva.dev/auth.md

API key → X-API-Key: samva_sk_live_…
          servers, CI, unattended agents
OAuth → samva login          a human at a terminal
MCP → mcp.samva.dev

#02 — CONNECT

Connect the hosted MCP.

Point Cursor, Codex, Claude Code, or any OAuth-capable client at mcp.samva.dev. It runs the OAuth flow, you approve once, and the agent gets email as tools.

{
  "mcpServers": {
    "samva": {
      "type": "http",
      "url": "https://mcp.samva.dev"
    }
  }
}

#03 — SEND

Send the first email.

The agent calls the send tool and gets a message id and delivery status back. You inspect the send.

→ messages_send_email
  { to: "ada@example.com", subject: "Welcome aboard" }

← msg_7q2xk9mvt4znw8rh · pending

( SDK, SKILLS, MCP )

Build with your agent from here.

Developers

Typed SDK, REST, and the auth model. The same contract the agent uses.

Agent skills

Instructions that teach a coding agent which Samva surface to reach for.

MCP server

Connect Cursor, Codex, or any OAuth client and send email as tools.

READ AUTH.MDThe machine-readable setup guide. Paste it into Cursor or Codex.

Questions from engineers.

Can my agent create its own key?

A person creates the first credential: an API key under Developers, API Keys, or a session with samva login. From there the agent holds that credential and can create and rotate more keys through the API keys endpoint. Every key is bound to one organization.

How do I connect Cursor or Codex?

Point the client at https://mcp.samva.dev with no key. The server returns the discovery details, the client runs OAuth, and you approve once. After that Cursor, Codex, Claude Code, or any OAuth-capable MCP client acts on your organization.

What tools does MCP expose?

With a credential, the agent can send email, manage contacts, read conversations and delivery status, manage domains and senders, edit and publish templates, operate webhooks, schedule mail, and run campaigns. Without a key, the same server answers product questions and searches the public template gallery. The server describes itself on connect.

How do I scope what an agent can send?

Give the agent a key bound to one organization, so it acts inside that organization and nowhere else. Every MCP action runs against that organization. Rotate or revoke the key from the dashboard to cut off access. Inspect the message id and delivery status on every send.

MCP and CLI