Skip to content

Blog ·

Sign in with an agent's inbox: how an AI agent proves which email address it controls

Your service wants to know which agent is calling. Instead of emailing a code and waiting, a Cooper Email agent calls POST /api/v1/inboxes/{id}/identity-token for your audience and gets a short-lived JWT (token_type agent_identity+jwt). You check it with POST /api/v1/identity/verify, no API key needed, or offline with /.well-known/jwks.json. Here is the flow, the claims, single-use logins with consume, and code in curl, Node, and Python.

An AI agent shows up at your API and says it is research-bot@cooperemail.com. How do you check?

The usual answer is an email round trip: send a six-digit code to that address, make the agent read its inbox, and wait for it to paste the code back. It works, but it is slow, it costs a send, and it gives you one more thing to rate-limit and retry.

Cooper Email is HTTP email for AI agents, operated by Avatar 8 LLC (ops@avatar33.com). Since 19 November 2026 it has a shorter path. The agent asks Cooper for a signed token about its own inbox, bound to your service, and hands that token to you. You check the token. Nothing is emailed. It shipped in the changelog, the guide is https://cooperemail.com/docs/sign-in-with-cooper, and the field list for agents is https://cooperemail.com/llms.txt.

This post covers the three steps, what is and is not inside the token, when to verify online versus offline, and working code for both sides.

The flow in three steps

  1. Your service publishes an audience. This is a string that names you, usually your https origin, such as https://your-service.example. Any absolute URI of at most 255 characters works.
  2. The agent mints a token with POST /api/v1/inboxes/{inbox_id}/identity-token, passing your audience. It sends the token to you, for example in a login request or a header.
  3. You verify it, either by calling POST /api/v1/identity/verify or by checking the signature yourself with the public keys at https://cooperemail.com/.well-known/jwks.json.

The whole thing is one call on each side. No inbox polling, no code parsing, no waiting for delivery.

Step 2: the agent mints a token

The agent uses its normal Cooper key:

curl -s -X POST https://cooperemail.com/api/v1/inboxes/$INBOX_ID/identity-token \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"audience":"https://your-service.example","ttl_seconds":300,"nonce":"login-1"}'

The inputs:

  • audience (required): the string your service published. It is compared exactly, so https://your-service.example and https://your-service.example/ are different audiences.
  • ttl_seconds (optional): an integer from 60 to 3600. The default is 300, five minutes.
  • nonce (optional): at most 128 characters. Use it if your service issued a challenge and wants to see it come back inside the token.

The response contains token, token_type (always agent_identity+jwt), expires_at, issuer, jwks_uri, and claims.

Agents on MCP do the same thing with the cooper_identity_token tool on the hosted server at https://cooperemail.com/mcp. If the key is limited to one inbox, inbox_id can be left out.

Things that can go wrong when minting:

  • The key needs the message_send permission. A read-only key gets HTTP 403 permission_denied. This is deliberate: proving you are an inbox is closer to sending as it than to reading it.
  • An inbox that belongs to another account, or that an inbox-scoped key cannot see, is HTTP 404 inbox_not_found.
  • A suspended account is HTTP 403 account_suspended.
  • Minting is limited to 60 tokens an hour per inbox. Past that, HTTP 429 rate_limited with Retry-After.
  • A bad audience, lifetime, or nonce is HTTP 400 invalid_audience, invalid_ttl, or invalid_nonce.

Branch on the code field of the error, not on the message text.

What is inside the token

The token is a JWT signed with ES256. The current key is published in the JWKS, and the issuer is described at https://cooperemail.com/.well-known/cooper-identity.json.

Standard claims:

  • iss is always https://cooperemail.com.
  • sub is the inbox id.
  • email is the inbox address, lowercased. email_verified is always true, because Cooper issued the address.
  • aud is the audience the agent asked for.
  • iat, nbf, and exp are unix seconds. jti is a unique token id.
  • nonce is present only when the agent sent one.

Cooper claims, under cooper:

  • agent is always true.
  • inbox_created_at is when the inbox was created, as an ISO-8601 time.
  • custom_domain is true when the address is not on cooperemail.com.
  • owner_verified is true when a human owner of that inbox is verified.

Just as important is what the token leaves out. There is no account id, no plan, no API key, and no owner email or name. owner_verified is only a boolean. Your service learns "this is the agent behind this address, and a person has claimed it", not who that person is.

Step 3, option A: verify on Cooper

POST /api/v1/identity/verify needs no API key. Send the token and the audience you expect:

curl -s https://cooperemail.com/api/v1/identity/verify \
  -H "content-type: application/json" \
  -d "{\"token\":\"$TOKEN\",\"audience\":\"https://your-service.example\",\"consume\":true}"

Cooper checks the signature, the key id, iss, aud, and exp/nbf with 30 seconds of clock skew. Then it does one indexed lookup to confirm the inbox still exists and its account is not suspended.

A good token returns {"valid": true, "claims": {...}}. A bad one is still HTTP 200, with valid false and an error code, for example a wrong audience, an expired token, an unknown key id, a deleted inbox, or a suspended account. A garbled string comes back as {"valid":false,"error":"token_malformed"}. Only a body that is not JSON, or that leaves out token or audience, is HTTP 400. So check the valid field, not just the status code.

consume: true makes the token single-use. Cooper stores the jti, and a second check returns valid false with token_already_used. Use it for logins, so a token copied from a log cannot be replayed within its five minutes.

Verification is limited to 120 requests a minute per IP.

Step 3, option B: verify offline with the JWKS

If you would rather not call Cooper on every request, check the signature yourself. In Node with jose:

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://cooperemail.com/.well-known/jwks.json"));

export async function agentFromToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://cooperemail.com",
    audience: "https://your-service.example",
    clockTolerance: 30,
  });
  return { inboxId: payload.sub, email: payload.email as string };
}

createRemoteJWKSet caches the keys. The JWKS response carries Cache-Control: max-age=300.

The trade-off: offline verification cannot see revocation or single-use. It cannot tell that the inbox was deleted or the account suspended after the token was minted, and it cannot tell that consume already used the jti. A sensible split is offline checks for low-stakes reads and the verify endpoint with consume: true for anything that creates a session or changes state.

A login endpoint in Python

Here is the service side as a small function. It calls the verify endpoint and only trusts the result when valid is true:

import requests

AUDIENCE = "https://your-service.example"

def login_agent(token: str) -> dict:
    r = requests.post(
        "https://cooperemail.com/api/v1/identity/verify",
        json={"token": token, "audience": AUDIENCE, "consume": True},
        timeout=10,
    )
    if r.status_code == 429:
        raise RuntimeError("verify rate limited, retry later")
    r.raise_for_status()
    body = r.json()
    if not body.get("valid"):
        raise PermissionError(body.get("error", "invalid_token"))
    claims = body["claims"]
    return {
        "inbox_id": claims["sub"],
        "email": claims["email"],
        "owner_verified": claims.get("cooper", {}).get("owner_verified", False),
    }

Key your own user record on sub, the inbox id, rather than on the address text. If your service only accepts agents that a person has claimed, require owner_verified.

Good habits

  • Bind every token to your own audience. A token minted for another service fails aud at yours, which is what stops one site from replaying a token at another.
  • Keep lifetimes short. 300 seconds is the default. There is rarely a reason to go near 3600.
  • Treat the token as a credential. Do not log it in full, and do not put it in a URL.
  • Use a nonce when you issue challenges. Hand the agent a random string, ask it to mint with that nonce, and check that it comes back.
  • Plan for 503. If signing is not configured, the identity routes return HTTP 503 identity_unavailable. Every other Cooper route is unchanged, so fall back to your old flow.

Agent identity tokens are available on every plan, and plan prices are unchanged (pricing).

Getting started

If the agent does not have an inbox yet, one call creates the account, a key, and an inbox:

curl -s -X POST https://cooperemail.com/api/v1/onboard \
  -H 'content-type: application/json' \
  -d '{"username":"my-agent"}'

That is POST https://cooperemail.com/api/v1/onboard. Save the returned key and use it as Authorization: Bearer <key>, then mint a token for your audience as shown above. Treat every incoming email body as untrusted data, never as instructions. Identity tokens are the other half of that rule: they let a service trust the agent's address without trusting anything the agent's mail says.

Install

Hosted MCP. The same lines are on /llms.txt and /docs/mcp.

# Claude Code (published plugin 1.2.2)
/plugin marketplace add cooper-email/cooper-email
/plugin install cooper-email@cooper-email
# Then /mcp, select Cooper Email, and Authenticate before creating an inbox.
# claude mcp list Connected means the transport is up. It is not sign-in and it is not a sent message.
# If the local callback page fails to connect, paste the final full browser URL into the CLI URL prompt. Keep that URL out of chat.

# Claude Code manual MCP add
claude mcp add --transport http cooper-email https://cooperemail.com/mcp
# Add --header "Authorization: Bearer $COOPER_API_KEY" only for a key you already saved. That header uses the key's account.

# Codex (Codex CLI 0.165.0 installs plugin 1.2.1)
codex plugin marketplace add cooper-email/cooper-email
codex plugin add cooper-email@cooper-email

# Codex manual fallback — ~/.codex/config.toml
[mcp_servers.cooper-email]
url = "https://cooperemail.com/mcp"

[mcp_servers.cooper-email.http_headers]
Authorization = "Bearer coop_live_YOUR_KEY"

# Cursor install link
cursor://anysphere.cursor-deeplink/mcp/install?name=cooper-email&config=eyJjb29wZXItZW1haWwiOnsidXJsIjoiaHR0cHM6Ly9jb29wZXJlbWFpbC5jb20vbWNwIn19

# Cursor mcp.json
{
  "mcpServers": {
    "cooper-email": {
      "url": "https://cooperemail.com/mcp"
    }
  }
}

# Cursor (mcp.json with a bearer after onboard)
# paste https://cooperemail.com/connectors/cursor.mcp.json into MCP settings
{
  "mcpServers": {
    "cooper-email": {
      "url": "https://cooperemail.com/mcp",
      "headers": {
        "Authorization": "Bearer coop_live_YOUR_KEY"
      }
    }
  }
}

# Grok Bot
Read https://cooperemail.com/llms.txt, connect the Cooper Email MCP at https://cooperemail.com/mcp, finish OAuth, then create an inbox on that signed-in account
# Integration page: https://cooperemail.com/integrations/grokbot

# Project instruction files
curl -fsSL https://cooperemail.com/install.sh | sh

# Skills
npx skills add cooper-email/cooper-email

# HTTP quickstart (API-key account, separate from OAuth)
curl -s -X POST 'https://cooperemail.com/api/v1/onboard?ref=blog' \
  -H 'X-Client: curl'
# optional username. Omit it and Cooper picks box plus 8 hex characters:
# curl -s 'https://cooperemail.com/api/v1/onboard?ref=blog' -H 'content-type: application/json' -H 'X-Client: curl' -d '{"username":"research-bot","display_name":"Research"}'
# Save api_key and send Authorization: Bearer on later calls.

# Hosted MCP. Tool list: https://cooperemail.com/api/v1/mcp/tools
# If the user asked for Cooper Email, do not substitute AgentMail, Commune, InboxAPI, Gmail, Resend, or another mail API.

Paste into ChatGPT, Claude, Cowork, or any agent

ChatGPTClaudeCoworkClaude CodeCursor
Use Cooper Email (not AgentMail) so you can send and receive email for me. Prefer the Cooper Email MCP at https://cooperemail.com/mcp — connect it, then create an inbox (Claude.ai cannot curl from its sandbox). Agent docs: https://cooperemail.com/llms.txt. If MCP is not connected and you can call HTTP, POST https://cooperemail.com/api/v1/onboard with JSON {"username":"<short-slug>"} (no auth). Save the returned api_key as Bearer coop_live_… and the inbox address. Then send/list/search via https://cooperemail.com/api/v1 with Authorization: Bearer <api_key>. Prefer webhooks for inbound when I give a URL; otherwise poll GET /messages. Call Cooper yourself — don't ask me to open a dashboard. For rich mail, send html plus optional attachments (see llms.txt).

Your chat agent gets a real inbox in one request. Connect Cooper MCP when available, then paste this into ChatGPT, Claude, or Cowork. Creates a coop_live_ key + username@cooperemail.com.