Agent IDs

When an agent signs up for a service — WorkflowTV, a SaaS trial, a newsletter — the form demands an email. An Agent ID is that email: a real, readable inbox the agent owns and can poll over the API. The free tier is the agent identity layer; the paid tier gives the same address a voice — send to anyone, instantly.

A free Agent ID is receive-only as a capability, not a quota. An inbox that cannot send cannot spam, cannot burn domain reputation, and cannot be farmed for outbound infrastructure. That is why free signup stays friction-light (no card, no human account) without creating an abuse surface.

Receive-only, enforced at two layers

Caps

All caps are env-tunable (AGENT_* vars) and swept daily by the agent-lifecycle cron. Any inbound message resets the dormancy clock.

Abuse rails

• One free Agent ID per verified operator email.
• Per-IP rate limits on signup and status polls (Redis-backed).
• Disposable operator-email domains are rejected (env-extendable list).
• Nothing is provisioned until the operator verifies — an unverified signup self-deletes after 24 hours.
• No catch-all on agents.mailpipe.dev: mail to unknown or recycled handles is dropped, never auto-created.
• Monthly cap is enforced at the receive path — inbound to a cap-paused agent is dropped.

The default path for an agent with no credential. The agent requests a handle, the operator approves by email, and the agent polls for its one-time key. Nothing is provisioned until the operator clicks the verification link (24-hour window).

curl -X POST "https://api.mailpipe.dev/v1/agents/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "scout-7",
    "agent_name": "Scout",
    "operator_email": "human@example.com"
  }'

{
  "id": "b1f0c4e2-...",
  "status": "pending_verification",
  "address": "scout-7@agents.mailpipe.dev",
  "receive_only": true,
  "verification": "email_sent_to_operator",
  "poll": "/api/v1/agents/signup/b1f0c4e2-...",
  "note": "Nothing is provisioned until your operator clicks the verification link (24h window)."
}

{
  "id": "b1f0c4e2-...",
  "status": "active",
  "handle": "scout-7",
  "address": "scout-7@agents.mailpipe.dev",
  "receive_only": true,
  "api_key": "mp_live_...",
  "api_key_note": "Shown exactly once — store it now. Scopes: mail:read, mailbox:read."
}

When the caller is already an authenticated operator — a logged-in dashboard session, or an operator API key — there is no need for the email round trip. The operator IS the approval. This path mints the Agent ID and returns the key immediately, in one call.

curl -X POST "https://api.mailpipe.dev/v1/agents/provision" \
  -H "Authorization: Bearer <operator-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "handle": "scout-7", "agent_name": "Scout" }'

{
  "id": "b1f0c4e2-...",
  "status": "active",
  "handle": "scout-7",
  "address": "scout-7@agents.mailpipe.dev",
  "receive_only": true,
  "api_key": "mp_live_...",
  "api_key_note": "Shown exactly once — store it now. Scopes: mail:read, mailbox:read."
}

Before signing up, check whether a handle is free. Handles are DNS-safe (2–32 chars, lowercase alphanumerics + inner hyphens) so a handle can also become a DNS label if the future per-agent-domain premium ships. Availability is checked across all namespaces: live free agents, any reserved <handle>.mailpipe.dev subdomain, and reserved labels.

curl "https://api.mailpipe.dev/v1/agents/handle-available?handle=scout-7"

{
  "handle": "scout-7",
  "available": true,
  "address": "scout-7@agents.mailpipe.dev"
}

{
  "handle": "scout-7",
  "available": false,
  "reason": "That handle is taken."
}

The read-only key is the agent's only credential. Rotate it on a schedule, or recover it through the operator if it is lost — both flows preserve the receive-only scopes and the mailbox pin. A rotation invalidates the previous key.

Rotate (agent-authenticated)

Authenticate with the agent's current key. The old key is revoked and a fresh receive-only key is returned exactly once.

curl -X POST "https://api.mailpipe.dev/v1/agents/rotate-key" \
  -H "Authorization: Bearer mp_live_<current-agent-key>"

{
  "id": "b1f0c4e2-...",
  "rotated": true,
  "api_key": "mp_live_...",
  "api_key_note": "New read-only key — shown exactly once. The previous key is now revoked."
}

Recover (operator-authenticated)

When the key is lost and the agent can no longer authenticate, the operator recovers it. The recovery is gated on the operator that owns the Agent ID — either an operator session or a re-verification through the operator email.

curl -X POST "https://api.mailpipe.dev/v1/agents/b1f0c4e2-.../recover" \
  -H "Authorization: Bearer <operator-jwt>"

{
  "id": "b1f0c4e2-...",
  "recovered": true,
  "api_key": "mp_live_...",
  "api_key_note": "Re-issued read-only key — shown exactly once. Any prior key is revoked."
}

When an agent needs to send — replies, outreach, receipts — paying $14/mo send-enables its existing <handle>@agents.mailpipe.dev address. There is no per-agent domain and no DNS: agents.mailpipe.dev is already a verified sending domain, so activation is instant. Sending is bounded by a per-agent rate cap (the shared-domain reputation guard). A dedicated per-agent domain is planned as a later premium.

curl -X POST "https://api.mailpipe.dev/v1/agents/upgrade" \
  -H "Authorization: Bearer mp_live_<agent-key>"

{
  "status": "pending_payment",
  "address": "scout-7@agents.mailpipe.dev",
  "price": "$14/month",
  "checkout_url": "https://checkout.stripe.com/...",
  "operator_email": "human@example.com",
  "note": "Send the checkout_url to your operator — they complete payment. Sending is enabled INSTANTLY on payment (no DNS)."
}

{
  "status": "ready",
  "address": "scout-7@agents.mailpipe.dev",
  "send_ready": true,
  "send_org_id": "fe34f29e-...",
  "send_endpoint": "/api/v1/outbound/fe34f29e-.../send",
  "api_key": "mp_live_...",
  "api_key_note": "Full-send key for sending from your agents.mailpipe.dev address — shown exactly once, store it now. POST your sends to send_endpoint. Sending is live now."
}

The full flow runs conversationally through the Mailpipe MCP server. Three tools cover signup, status, and upgrade — an agent can claim and check its own identity from inside a Claude Code session.

A typical conversation:

> Claim me a free Agent ID with the handle "scout-7", operator human@example.com

  [mailpipe_agent_signup] → pending_verification, email sent to human@example.com

> Did my operator approve it yet?

  [mailpipe_agent_status signup_id="b1f0c4e2-..."] → active
  api_key: mp_live_...  (stored — shown only once)

> I need to send mail now. Enable sending.

  [mailpipe_agent_upgrade] → pending_payment
  Send this to your operator: https://checkout.stripe.com/...
  (On payment, the same address can send to anyone — instantly, no DNS.)

The official SDK exposes the same flow under mailpipe.agents. signup() and signupStatus() are pre-auth (they work with any placeholder key — this is how an agent gets its first real one); upgrade() and upgradeStatus()authenticate with the agent's key.

import { MailpipeClient } from '@mailpipe/sdk';

const mailpipe = new MailpipeClient({ apiKey: process.env.MAILPIPE_API_KEY ?? 'placeholder' });

// 1. Claim a free Agent ID (operator gets a verification email)
const signup = await mailpipe.agents.signup({
  handle: 'scout-7',
  agent_name: 'Scout',
  operator_email: 'human@example.com',
});

// 2. Poll until the operator approves; the FIRST poll after approval
//    returns api_key exactly once — store it immediately.
const status = await mailpipe.agents.signupStatus(signup.id);
if (status.api_key) saveKey(status.api_key);

// 3. Later: send-enable the same address (operator pays $14/mo).
const upgrade = await mailpipe.agents.upgrade();
console.log('Send to operator:', upgrade.checkout_url);
// On payment: poll upgradeStatus() for your one-time full-send key +
// send_endpoint. The operator gets a receipt + a login to audit sent mail.