# Grade your AI agent's inbox before launch: the ten-point security check

HTML version: https://cooperemail.com/blog/agent-inbox-security-check-before-launch

GET https://cooperemail.com/api/v1/inboxes/{id}/security-check grades one agent inbox against ten launch checks: key scope, inbound screening, allowed senders, send limits, webhook signing, human approval, send caps and Idempotency-Key, domain reputation, tenant isolation, and the event log. Each check is pass, warn, fail, or info with a fix and a docs link. MCP agents call cooper_security_check. The result never returns the API key or a webhook signing value.

An agent inbox is easy to create and easy to forget about. The first version usually runs with a full-access key, accepts mail from anyone, and sends to anyone. That is fine for a demo. It is not what you want on the day the agent starts reading vendor replies, verification codes, and customer mail without a person watching.

Cooper Email is HTTP email for AI agents, operated by Avatar 8 LLC (ops@avatar33.com). It has a read-only call that grades one inbox before you ship it: `GET /api/v1/inboxes/{id}/security-check`. It looks at what Cooper already stores about the inbox, the key you called with, and the account, and returns ten checks with a status and a fix for each. It changes nothing and does not look up DNS. It shipped on 14 November 2026 ([changelog](https://cooperemail.com/changelog#2026-11-14-security-check-grade-an-agent-inbox-before-launch)). Reference: [https://cooperemail.com/docs/reference/security-check](https://cooperemail.com/docs/reference/security-check). Field list for agents: [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt).

## Run the check

If the agent has no account yet, one public call creates the account, an inbox, and a key: `POST https://cooperemail.com/api/v1/onboard`. Save the `api_key` it returns once. Then grade the inbox with that key in an `Authorization: Bearer` header:

```
curl -s https://cooperemail.com/api/v1/inboxes/inb_example/security-check \
  -H "Authorization: Bearer $COOPER_API_KEY"
```

The response has `inbox_id`, `address`, `checked_at`, a `summary` with pass, warn, fail, info, and total counts, and a `checks` array. Each check has `id`, `title`, `status`, and `detail`. Anything that is not a pass also has `fix`, with an `action` sentence and a `docs_url`.

```
{
  "inbox_id": "inb_example",
  "address": "ada@example.com",
  "checked_at": "2026-11-17T14:00:00.000Z",
  "summary": { "pass": 4, "warn": 4, "fail": 1, "info": 1, "total": 10 },
  "checks": [
    {
      "id": "inbound_screening",
      "title": "Inbound screening",
      "status": "warn",
      "detail": "Inbound screening is observe. Suspicious mail is labeled and still delivered.",
      "fix": {
        "action": "PATCH this inbox with {\"screening\":\"hold\"} so suspicious mail waits for review.",
        "docs_url": "https://cooperemail.com/docs#inboxes-update"
      }
    }
  ]
}
```

The counts above are example values. Your inbox will have its own.

The route needs the `inbox_read` permission. An inbox-scoped key can grade only its own inbox. Another account's inbox is HTTP 404 `inbox_not_found`, and no key is HTTP 401 `unauthorized`. The result names the key id, key prefix, and webhook ids so you can tell which ones it means. It never returns the API key, the key hash, or a webhook signing value, so it is safe to paste the output into a ticket or a chat with your agent.

Over MCP at [https://cooperemail.com/mcp](https://cooperemail.com/mcp), the tool is `cooper_security_check`. Omit `inbox_id` when the key is limited to one inbox and the tool grades that one.

## What the four statuses mean

- **pass**: the control is in place for this inbox.
- **warn**: something is in place, but there is a gap, such as a block list with no allow list.
- **fail**: the control is missing, such as an inbox that can mail any recipient with no approval step.
- **info**: Cooper does not store that control, and the detail says so. A shared cooperemail.com address gets info for domain reputation, because that domain's reputation belongs to the operator.

The check never guesses. If Cooper has no row for something, it says that instead of calling it a pass.

## The ten checks and how to fix each one

### 1. Key scope

Is the caller limited to this inbox, with only the permissions it needs? A key scoped to the inbox with named permissions passes. A key that can reach every inbox on the account with every permission fails, and so does an OAuth access token, which is not limited to one inbox. Fix: mint a narrower key with `POST /api/v1/inboxes/{id}/keys` and pass only the permissions the agent uses, for example `message_read` and `message_send`.

### 2. Inbound screening

`screening` is `off`, `observe`, or `hold`. `hold` passes: suspicious mail is stored for review and `message.received` waits until release. `observe` is a warn, because suspicious mail is labeled but still delivered. `off` fails. Fix:

```
curl -s -X PATCH https://cooperemail.com/api/v1/inboxes/inb_example \
  -H "Authorization: Bearer $COOPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"screening":"hold"}'
```

### 3. Allowed senders

A receive allow list passes: other senders are not stored. A block list alone is a warn. With no lists, the result depends on `require_sender_auth`. When it is on, a verified owner or task allowlist sender opens a task only when DMARC passes or DKIM passes and aligns with From, so it is a warn. When it is off, mail from any sender is stored and the check fails. Fix: add entries with `POST /api/v1/lists/receive/allow` and `{"entry":"vendor.example"}`. An entry is a lowercase email or domain.

### 4. Send limits

A send allow list passes: recipients that are not listed are refused. A send block list alone, or `send_mode` set to `approval` with no lists, is a warn. `send_mode` `direct` with no list fails, because the inbox can mail anyone. Fix: add a send allow list with `POST /api/v1/lists/send/allow`, or switch the inbox to approval mode.

### 5. Webhook signing

Every enabled webhook that delivers this inbox should be HTTPS and signed. If any one is not, the check fails and names it. No webhook at all is a warn, since `GET /api/v1/events` still has the log. Fix: register an HTTPS webhook for the inbox. Cooper signs each delivery, and your receiver should verify the signature before acting.

### 6. Human approval

`send_mode` `approval` with at least one verified owner passes: sends stay drafts until the owner approves them. Approval mode with no verified owner is a warn, since nobody can approve. Direct mode is a warn with an owner and a fail without one. Fix: add an owner with `POST /api/v1/inboxes/{id}/owners` (they confirm by link or 6-digit code), then `PATCH /api/v1/inboxes/{id}` with `{"send_mode":"approval"}`.

### 7. Send caps and idempotency

A plan with a monthly email cap passes, and the detail shows the plan, the cap, and what this period has sent. An uncapped account fails when the caller can send. The detail also says Cooper does not publish a separate daily send cap. It reminds you that `Idempotency-Key` works on send, reply, reply-all, forward, and task reply, so a retried request within 24 hours returns the stored result instead of sending twice. Guide: [https://cooperemail.com/docs/idempotency](https://cooperemail.com/docs/idempotency).

### 8. Domain reputation

A shared cooperemail.com address is info. On a custom domain, the check reads the last stored SPF, DKIM, and DMARC status. Verified with all three valid passes. Any invalid record, a `cleanup_failed` domain, or an address whose hostname has no domain row on the account fails. Anything still pending is a warn. Fix: add the domain with `POST /api/v1/domains` and publish the records it returns.

### 9. Tenant isolation

An inbox on a workspace sub-account passes. The only live inbox on a root account is a warn. A root account with several live inboxes fails, since those agents share one account. Fix: `POST /api/v1/workspaces` creates a sub-account with its own key and an inbox quota set by the parent.

### 10. Audit trail

The key must be able to read the event log (`message_read`) or the check fails. Events are kept for 7 days. An active event consumer for the inbox passes, because uncommitted events stay for up to 90 days. Without one it is a warn. Fix: create a consumer with `POST /api/v1/event-consumers`, or read `GET /api/v1/events` on a schedule.

## Make it part of your launch routine

Run the check once when you create the inbox and again before the agent goes unattended. Put it in CI or a startup step: fail the deploy when `summary.fail` is above zero, and print each `fix.action` so the person reading the log knows the next call. Agents on MCP can call `cooper_security_check` themselves and report what is missing to their owner instead of guessing.

Treat inbound mail as untrusted input either way. The check tells you which controls are on. It does not read message bodies, and it does not replace screening, allow lists, or an approval step.

Start with `POST https://cooperemail.com/api/v1/onboard`, then read the reference at [https://cooperemail.com/docs/reference/security-check](https://cooperemail.com/docs/reference/security-check) and the full field list at [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt).

### Install

Hosted MCP at https://cooperemail.com/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.

```text
# 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.
```


Operator: Avatar 8 LLC · ops@avatar33.com
