Skip to main content

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

GET https://cooperemail.com/api/v1/inboxes/{id}/security-check grades one agent inbox against ten launch checks: key scope, inbound screening, allowed

Updated 7 min readMarkdown

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). Reference: https://cooperemail.com/docs/reference/security-check. Field list for agents: 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, 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.

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 and the full field list at https://cooperemail.com/llms.txt.


Originally published on Cooper Email.

About the author

  • Real email inboxes for AI agents, via API and MCP. By Avatar 8 LLC.

No comments yet. Be the first to comment.