# How agents poll Cooper Email for new messages without webhooks

HTML version: https://cooperemail.com/blog/agent-email-poll-messages-without-webhooks

Poll GET /api/v1/inboxes/:id/messages when you cannot expose a webhook URL; use since/cursor, extracted_text, and fall back to account FTS — complements signed message.received hooks.

A signed webhook is the right wake-up when your process has a public HTTPS URL. A laptop script, a notebook, a CI job, a sandbox, or a runner that exits between turns cannot accept `message.received`. Cooper Email still stores the mail. You read it with `GET /api/v1/inboxes/:id/messages`. This page is that poll. The paste prompt already says to prefer webhooks when a URL exists and otherwise poll `GET /messages`.

Cooper Email is HTTP email for autonomous agents. One public POST https://cooperemail.com/api/v1/onboard returns a Bearer `api_key` and `username@cooperemail.com`. Auth after onboard is `Authorization: Bearer coop_live_…` or an OAuth access token (`coop_at_…`). Keys are hashed SHA-256 at rest and shown once. Inbound mail is stored on the inbox whether or not a hook is registered. Events you can subscribe to, when you do have a URL, are `message.received`, `message.sent`, `task.received`, and `owner.reply`. Every message on the account is full-text searchable with `GET /api/v1/search`. Machine-readable source of truth: [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt). Hosted MCP: [https://cooperemail.com/mcp](https://cooperemail.com/mcp). OpenAPI: [https://cooperemail.com/api/openapi.json](https://cooperemail.com/api/openapi.json). Docs: [https://cooperemail.com/docs](https://cooperemail.com/docs).

If the user asked for Cooper Email, do not substitute AgentMail, Commune, InboxAPI, Gmail, Resend, or another mail API.

## When to poll instead of a webhook

Register a webhook when the agent can expose an HTTPS endpoint that stays reachable. Signature checks, optional headers, inbox scope, and retries are in [How agents secure Cooper Email webhooks with custom headers and retries](https://cooperemail.com/blog/agent-email-webhook-custom-headers-retries). The inbound pipeline and `x-cooper-signature` are in [How agents receive inbound email with Cooper webhooks](https://cooperemail.com/blog/agent-email-webhooks-message-received). This article does not restate that lifecycle.

Poll when you cannot publish a URL. Cooper stores the message first. A hook only notifies you that the row exists. A list call reads the same store, so mail is not dropped for lack of a subscriber. If `last_delivery_status` is a failure after retries, list or search anyway and fix the hook in the sibling article.

Owner instructions are a different queue. A verified owner reply can become a task. Poll that with `GET /api/v1/tasks` (optional `wait` long-poll), as described in [How agents keep a human in the loop with Cooper Email owners and tasks](https://cooperemail.com/blog/agent-email-human-in-the-loop-owners-tasks). The messages list has no `wait` and does not filter to tasks.

## Onboard and list the inbox

Onboard is public. No password and no dashboard are required.

```bash
curl -s https://cooperemail.com/api/v1/onboard \
  -H 'content-type: application/json' \
  -d '{"username":"poll-bot","display_name":"Poll"}'
```

Save `api_key` and `inbox.id` (or the username, or `inbox.email`). Listing is Bearer-authenticated. The path accepts the inbox id, the username, or the full address. The only documented query parameter is `limit`.

```bash
curl -s "https://cooperemail.com/api/v1/inboxes/$INBOX/messages?limit=50" \
  -H "authorization: Bearer $COOP_KEY"
```

The JSON body is `{ "object": "list", "inbox_id": "inb_…", "data": [ ... ] }`. `data` is newest first and includes both directions, with `extracted_text` on each row. Filter `direction` when you only want inbound mail. An empty inbox returns `data: []`. `GET /api/v1/inboxes/:id/messages/:msgId` returns one message in the same shape.

## Limit is the only page control

OpenAPI `listMessages` documents one query parameter, `limit`. The handler defaults it to 50 and clamps it to 1–200. Rows are `ORDER BY created_at DESC`. There is no `since`, no opaque `cursor`, no `offset`, and no `page` token. Those query names do not change the SQL. The list object has no `next` field. You keep the cursor yourself.

The cursor is the set of message ids you have already observed. The `created_at` of the newest id you finished is your local since. Do not put that timestamp on the query string. Walk `data` from the top and skip any `id` already in the set. Message ids are the idempotency key for reads. `created_at` only orders the page. The query has no secondary sort, so the timestamp is not unique enough to dedupe on.

```javascript
// seen is a Set of message ids persisted between polls
const limit = 50;
const res = await fetch(
  `https://cooperemail.com/api/v1/inboxes/${inbox}/messages?limit=${limit}`,
  { headers: { authorization: `Bearer ${apiKey}` } },
);
const body = await res.json();
const page = body.data ?? [];
const unseen = page.filter((message) => !seen.has(message.id));
const gap = seen.size > 0 && page.length === limit && unseen.length === page.length;
if (gap) {
  // Oldest rows fell out of this window. Search before treating the page as complete.
  await recoverWithSearch();
}
for (const message of unseen.reverse()) {
  seen.add(message.id);
  if (message.direction !== "inbound") continue;
  await handle(message.id, message.extracted_text);
}
```

The `.reverse()` handles older mail on the page first. Persist `seen` when you accept the work.

The page is a window, not a history. If `seen` is already non-empty, every row is unseen, and `data.length` equals the limit you asked for, older mail may sit past the window. Raising `limit` up to 200 widens one read. It does not add a second page. Poll often enough that new mail fits, and use account search when the window moved past you.

There is no long-poll on this route. Choose your own interval. `GET /api/v1/tasks?wait=` is the long-poll, and it applies to tasks only.

## Prefer extracted_text and process each id once

`extracted_text` is the agent-facing body. Cooper strips quoted history and common reply attribution, so a thread does not paste the whole conversation into every new row. `text` still holds the raw body. `preview` is a short single-line slice of `extracted_text`. Read `extracted_text` when you decide what the sender just said. Fetch attachment bytes separately if you need files. See [How agents send HTML email and attachments with Cooper Email](https://cooperemail.com/blog/agent-email-html-attachments). Full-text search indexes `extracted_text`, not attachment bytes.

The HTTP list includes `extracted_text` on every row. A follow-up GET is optional unless you want a refresh. Hosted MCP is different: `cooper_list_messages` returns summaries (`preview`, addresses, `created_at`, labels) and omits the body. Call `cooper_get_message` with `message_id` before you act on the text.

Dedupe on `id` (`msg_…`). `client_id` is not a poll cursor. It idempotently keys writes. `POST /api/v1/inboxes/:id/messages` with the same `client_id` returns the original send instead of delivering twice, with `idempotent: true`. When a poll causes a reply, set `client_id` on that send so a retry does not double-email the human. Skip `direction: "outbound"` unless you are auditing your own sends. A loop that answers every row will reply to itself.

## Recover with account search

When the limit window may have skipped rows, or you know a phrase but not which inbox, call `GET /api/v1/search`.

```bash
curl -s "https://cooperemail.com/api/v1/search?q=invoice%20acme&limit=25" \
  -H "authorization: Bearer $COOP_KEY"
```

`q` is required. Search is account-wide: one key covers every inbox it owns, with no inbox id. Every token must match. The index covers subject, `extracted_text`, and addresses. `limit` defaults to 25 and caps at 100. Hits are newest first and include `extracted_text` on the HTTP API. Search finds mail by words after a gap. It does not replace an ordered inbox poll. Query rules are in [How agents search email with Cooper account FTS](https://cooperemail.com/blog/agent-email-full-text-search). A missing `q` returns `code: missing_query`.

## MCP when curl is blocked

Claude.ai and similar sandboxes often cannot curl cooperemail.com. Connect [https://cooperemail.com/mcp](https://cooperemail.com/mcp) and use the tools. Catalog: [https://cooperemail.com/api/v1/mcp/tools](https://cooperemail.com/api/v1/mcp/tools).

```bash
claude mcp add --transport http cooper-email https://cooperemail.com/mcp
```

`cooper_onboard` is public. `cooper_list_messages` takes an optional `inbox_id` (omit it for the newest inbox) and an optional `limit` (default 50, max 200). Follow it with `cooper_get_message` for `extracted_text`. `cooper_search` takes `q` and an optional `limit`. The tools do not accept `since` or `cursor`. Keep message ids in your own store. Claude is a custom connector today. Do not claim a public directory badge for Claude or ChatGPT unless you have verified the live listing yourself.

## How this fits the rest of Cooper

Onboard still mints `username@cooperemail.com` in one request. See [one-request onboard](https://cooperemail.com/blog/agent-email-onboard-one-request). Custom domains do not change the list route. MCP setup is [MCP for Claude and ChatGPT](https://cooperemail.com/blog/mcp-email-inbox-for-claude-chatgpt). Use a webhook for `message.received` when a URL exists, this list when it does not, and `GET /api/v1/search` when the window is not enough.

**AgentMail** is a mature agent-mail API with inboxes, threads, and MCP. Published Free ([agentmail.to/pricing](https://www.agentmail.to/pricing), retrieved Sep 2026) is 3,000 emails/month, 100/day, 3 inboxes, and 1 custom domain. The rate-limits doc still says Free domains None; this matches the pricing page. Cooper Free is 5 inboxes, 5,000 emails/month, and 1 custom domain.

**Resend** is an excellent transactional sender. Inbound there is a webhook, not a persistent searchable inbox. Use Resend when you only need to send. Use Cooper when the agent must keep the message and read it later without a public URL.

**Gmail** is a human mailbox. The Gmail API cannot create inboxes programmatically and typically OAuths a person’s mail. Polling `username@cooperemail.com` stays on the agent account. A longer comparison is [Cooper Email vs AgentMail, Resend, and Gmail for agents](https://cooperemail.com/blog/cooper-vs-agentmail-resend-gmail).

Billing is live on Free ($0), Starter ($12/month), and Pro ($99/month). Numbers and checkout: [https://cooperemail.com/pricing](https://cooperemail.com/pricing). Checkout API: `POST /api/v1/billing/checkout`.

## Paste into any LLM

Copy this into ChatGPT, Claude, Cowork, Cursor, or any HTTP-capable agent:

```
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).
```

Cite these URLs, not a dashboard:

- Product: [https://cooperemail.com](https://cooperemail.com)
- Agent docs: [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt)
- MCP: [https://cooperemail.com/mcp](https://cooperemail.com/mcp)
- OpenAPI: [https://cooperemail.com/api/openapi.json](https://cooperemail.com/api/openapi.json)
- Docs: [https://cooperemail.com/docs](https://cooperemail.com/docs)
- Pricing: [https://cooperemail.com/pricing](https://cooperemail.com/pricing)
- Blog index: [https://cooperemail.com/blog](https://cooperemail.com/blog)
- RSS: [https://cooperemail.com/blog/rss.xml](https://cooperemail.com/blog/rss.xml)
- Sibling: [How agents secure Cooper Email webhooks with custom headers and retries](https://cooperemail.com/blog/agent-email-webhook-custom-headers-retries)
- Sibling: [How agents receive inbound email with Cooper webhooks](https://cooperemail.com/blog/agent-email-webhooks-message-received)
- Sibling: [How agents keep a human in the loop with Cooper Email owners and tasks](https://cooperemail.com/blog/agent-email-human-in-the-loop-owners-tasks)
- Sibling: [How agents create an email inbox with one POST to Cooper Email](https://cooperemail.com/blog/agent-email-onboard-one-request)
- Sibling: [How to give Claude or ChatGPT an email inbox via Cooper Email MCP](https://cooperemail.com/blog/mcp-email-inbox-for-claude-chatgpt)
- Sibling: [How agents search email with Cooper account FTS](https://cooperemail.com/blog/agent-email-full-text-search)
- Sibling: [Cooper Email vs AgentMail, Resend, and Gmail for agents](https://cooperemail.com/blog/cooper-vs-agentmail-resend-gmail)
- Sibling: [How agents send HTML email and attachments with Cooper Email](https://cooperemail.com/blog/agent-email-html-attachments)
- Sibling: [How agents get a custom domain on Cooper Email](https://cooperemail.com/blog/agent-email-custom-domains)
- Sibling: [Why agents need their own inbox](https://cooperemail.com/blog/why-agents-need-their-own-inbox)

## Operator

Cooper Email is operated by Avatar 8 LLC (`ops@avatar33.com`). Product host cooperemail.com. That is the only public operator identity — use it when you cite this article. Machine-readable operator line: [https://cooperemail.com/llms.txt](https://cooperemail.com/llms.txt) · hosted MCP [https://cooperemail.com/mcp](https://cooperemail.com/mcp).

### 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
