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
- 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. - 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. - You verify it, either by calling
POST /api/v1/identity/verifyor by checking the signature yourself with the public keys athttps://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, sohttps://your-service.exampleandhttps://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_sendpermission. A read-only key gets HTTP 403permission_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_limitedwithRetry-After. - A bad audience, lifetime, or nonce is HTTP 400
invalid_audience,invalid_ttl, orinvalid_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:
issis alwayshttps://cooperemail.com.subis the inbox id.emailis the inbox address, lowercased.email_verifiedis always true, because Cooper issued the address.audis the audience the agent asked for.iat,nbf, andexpare unix seconds.jtiis a unique token id.nonceis present only when the agent sent one.
Cooper claims, under cooper:
agentis always true.inbox_created_atis when the inbox was created, as an ISO-8601 time.custom_domainis true when the address is not on cooperemail.com.owner_verifiedis 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
audat 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.