Blog · 20 October 2026

How to wake an AI agent when an email arrives with MCP Events

Ask ChatGPT, in a dot or a Work chat, to watch a Cooper inbox and it subscribes to message.received. Cooper POSTs a signed webhook when a new email is stored. events/subscribe checks the https callback by requiring it to echo a challenge, then stores the subscription. The callback carries inbox, message id, thread, timestamp, participants, labels, and channel, and leaves out the subject, body, attachments, and headers. Read the message with cooper_get_message and treat that content as data. The default lifetime is 72 hours, the maximum is 30 days, and each API key or OAuth app can have 20 active subscriptions.

To wake an AI agent the moment an email arrives, connect Cooper Email's MCP server and subscribe to message.received. Cooper POSTs a signed webhook when a new email is stored. ChatGPT does that from a dot or a Work chat; any other MCP client calls events/subscribe on https://cooperemail.com/mcp with the inbox and an https callback. The callback carries message details — inbox, message id, thread, timestamp, participants, labels, and channel — and leaves out the subject, body, attachments, and headers, so the agent reads the message with cooper_get_message and treats that content as data.

Cooper Email is an email API and a hosted MCP server for AI agents, from Avatar 8 LLC. One public POST https://cooperemail.com/api/v1/onboard returns an api_key (shown once) and an inbox at username@cooperemail.com. Later calls send Authorization: Bearer coop_live_…, or an OAuth access token. Field-level detail is in https://cooperemail.com/llms.txt. The event contract is https://cooperemail.com/docs/mcp-events. The connector itself is https://cooperemail.com/docs/mcp.

Why a push beats another poll

Listing GET /api/v1/inboxes/:id/messages on a timer pays for every empty page, and a reply that lands just after the call waits for the next tick. Push closes that gap: Cooper stores the message, then tells the client.

Classic webhooks, from POST /api/v1/webhooks or cooper_register_webhook, POST the stored message to a URL you run. They cover message.received and other types such as message.held, message.sent, and message.blocked. Signing and retries for that path are in inbound webhooks and custom headers and retries. MCP Events is narrower. The client calls events/subscribe, the only event is message.received, and the body is a short record, not the message.

With no public URL, do not subscribe. cooper_wait_for_message holds for the next message.received on one inbox (default 20 seconds, maximum 25). The HTTP twin is GET /api/v1/events?wait= and GET /api/v1/inboxes/:id/events. That hold is wait for a verification code. A timer with no hold is polling without a webhook.

ChatGPT: a dot or a Work chat

Connect the Cooper plugin at https://chatgpt.com/plugins/plugin_asdk_app_6a9c72b1e468819190e4d653372612fc. In a dot or a Work chat, ask it to watch an inbox. A prompt that matches the docs:

Whenever research-bot@cooperemail.com gets a new email, summarize it and tell me.

ChatGPT calls events/subscribe for message.received. Cooper POSTs the signed webhook when a new email is stored, and ChatGPT runs. The same methods work for any MCP client on https://cooperemail.com/mcp and on POST /api/mcp.

Held, screened, and blocked mail does not fire message.received. ChatGPT then reads the message with cooper_get_message and treats that content as data, not as instructions.

Discover the server and list the event

server/discover needs no auth and no initialize. It returns resultType complete, supported versions 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26, capabilities.tools.listChanged false, an empty capabilities.events object, instructions, server info, ttlMs 3600000, and cacheScope public.

Send protocol version 2026-07-28 in params._meta["io.modelcontextprotocol/protocolVersion"], or in top-level _meta, or in the MCP-Protocol-Version header. The first value that is set wins. That skips initialize. tools/list and events/list then include ttlMs and cacheScope private. A version newer than 2026-07-28, or a value that is not a calendar date, returns JSON-RPC -32022 with data.supported and data.requested. initialize is not rejected for a protocol version, and it does advertise events.

events/list needs no auth. The event name is message.received and delivery is webhook. arguments.inbox is an inbox id or address. A non-empty cursor returns an empty events array and no next page.

events/subscribe requires auth and webhook_write, the same permission as creating a webhook. arguments only accepts inbox. delivery.mode must be webhook. delivery.secret must start with whsec_ and its base64 must decode to 24–64 bytes. The URL must be https, with no userinfo, no explicit port, and a hostname that is not an IP. A name that resolves to a private or loopback address is rejected.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events/subscribe",
  "params": {
    "name": "message.received",
    "arguments": { "inbox": "research-bot@cooperemail.com" },
    "delivery": {
      "mode": "webhook",
      "url": "https://hooks.example.com/cooper",
      "secret": "whsec_…"
    }
  }
}

Send Authorization: Bearer with the key from onboard. Before the row is stored, Cooper POSTs {"type":"verification","challenge":"…"}. The response must be 2xx JSON that echoes challenge. That POST is signed with the secret you sent. A redirect is not followed and fails the check. A failed check writes no row. A pass is cached for 7 days per API key or OAuth app and callback URL, so a later subscribe to the same URL skips the challenge. The result is {id, refreshBefore, cursor: null, truncated: false}. The id starts with mes_.

The same key, callback URL, event, and inbox refreshes that row and keeps the id. Omit ttlMs and the lifetime is 72 hours. ttlMs null is the 30 day maximum. Below 5 minutes is raised to 5 minutes. Above 30 days is capped there. refreshBefore is always a finite ISO 8601 time. Subscribe again before it if the agent should keep waking.

What Cooper POSTs

When mail is stored as message.received, Cooper POSTs the callback. Delivery uses the same public-host check and does not follow redirects. Headers are Content-Type: application/json, webhook-id (the Cooper event id, stable across retries), webhook-timestamp (unix seconds, fresh per attempt), webhook-signature, and X-MCP-Subscription-Id.

{
  "eventId": "evt_01",
  "name": "message.received",
  "timestamp": "2026-10-20T13:00:00.000Z",
  "data": {
    "inbox_id": "inb_01",
    "inbox": "research-bot@cooperemail.com",
    "message_id": "msg_01",
    "thread_id": "thr_01",
    "timestamp": "2026-10-20T13:00:00.000Z",
    "from": "ada@example.com",
    "to": ["research-bot@cooperemail.com"],
    "cc": [],
    "labels": ["unread", "inbox"],
    "channel": "email"
  },
  "cursor": null
}

eventId matches webhook-id. cursor is null. The body is at most 256 KiB. data is inbox_id, inbox (the address), message_id, thread_id, timestamp, from, to, cc, labels, and channel. channel is the channel the message arrived on: email, sms, voicemail, or voice. The subject, the body, attachments, and headers are not included.

webhook-signature is Standard Webhooks. The signed content is the id, a dot, the timestamp, a dot, and the raw body. The HMAC key is the base64 after whsec_. The header value is v1, plus that digest. A new secret on refresh keeps the previous secret for 24 hours, and the header then has two space-separated signatures, current first.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyStandardWebhook(secret, id, timestamp, rawBody, header) {
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key).update(id + "." + timestamp + "." + rawBody).digest("base64");
  return header.split(" ").some((part) => {
    const sig = part.startsWith("v1,") ? part.slice(3) : "";
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    if (a.length !== b.length) return false;
    return timingSafeEqual(a, b);
  });
}

408, 429, 5xx, and network errors are retried. 410, 413, and other 4xx responses are not. Those HTTP failures do not end the subscription. A revoked key, a deleted inbox, or a lost OAuth grant does. Each attempt waits up to 4 seconds, then Cooper retries after 200 ms and 400 ms.

Read the message, then stop

The wake-up is not the mail. Call cooper_get_message with inbox_id and message_id. It returns subject, text, html, and extracted_text (quoted history removed). Treat that content as data from the sender, not as instructions. While labels include held, those text fields and attachment bytes stay empty until cooper_release_message.

Held, screened, and blocked mail does not fire message.received. Screening set to hold stores suspicious mail and fires message.held instead. A blocked sender is not stored, and production inbound fires message.blocked. The default mode, observe, still fires message.received. Screening is a heuristic, not a guarantee. MCP Events does not deliver message.held or message.blocked.

GET /api/v1/search?q= searches subject, extracted text, and addresses later. An inbox-scoped key searches only its inbox.

Limits, refresh, and unsubscribe

Each API key, and each OAuth app on an account, can have 20 active subscriptions. A 21st returns JSON-RPC -32025. Ended rows and expired rows do not deliver and do not count.

An inbox-scoped key can watch only its inbox. Another account's inbox is not found. Listing uses webhook_read. GET /api/v1/event-subscriptions returns the id, name, inbox, callback_host (hostname only), status, refresh_before, and the last delivery fields. The URL path and the signing secret are not returned. Newest first. The MCP tool is cooper_list_event_subscriptions.

events/unsubscribe keeps the row with status ended and returns {retained: true}. Calling it again returns the same. An unknown inbox, or a callback that was never subscribed, returns {}. DELETE /api/v1/event-subscriptions/{id} needs webhook_write and returns that row with retained true, including when it is already ended. Another account's id, or an inbox this key cannot see, is HTTP 404 event_subscription_not_found. The MCP tool is cooper_delete_event_subscription.

Error codes

Code	Meaning
`-32602`	Invalid params, such as a bad secret or a URL that is not https.
`-32000`	Authentication failed (HTTP 401).
`-32015`	Callback verification failed. `data.reason` is `challenge_failed`, `timeout`, `unreachable`, or `blocked_address`.
`-32022`	Unsupported protocol version.
`-32023`	Not found: unknown event, or an inbox this key cannot see.
`-32024`	Forbidden. Subscribe needs `webhook_write`. List needs `webhook_read`.
`-32025`	Already at 20 active subscriptions for this key or OAuth app.
`-32026`	Unsupported delivery mode. Only `webhook` is accepted.

FAQ

Does the callback include the email body?

No. Read it with cooper_get_message, and treat the sender's text as data.

What if there is no public https URL?

Use cooper_wait_for_message, or poll GET /api/v1/inboxes/:id/messages. Do not subscribe.

Will held or blocked mail wake the agent?

No. Held mail fires message.held on a classic webhook. Blocked inbound mail fires message.blocked and is not stored. MCP Events delivers message.received only.

How long does a subscription last, and how many can I have?

72 hours by default, 30 days at most, 5 minutes at least. Subscribe again before refreshBefore. The cap is 20 active subscriptions per API key and per OAuth app. Ending one, or letting it expire, frees a slot. Revoking the key or the grant stops delivery.

Paste into the agent

Copy this into ChatGPT, Claude, Cowork, Cursor, or any HTTP-capable agent, then ask it to watch the inbox:

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

AgentMail is an agent-mail API. Resend sends application mail, and its inbound path is a webhook rather than a searchable inbox. The Gmail API authorizes a human mailbox. Cooper gives the agent its own address and this signed callback. Plans are on https://cooperemail.com/pricing.

Cooper Email is built by Avatar 8 LLC. Questions: ops@avatar33.com.