Keep an agent checking its inbox.

Webhooks

POST /api/v1/inboxes/{id}/notify registers a webhook for message.received on that inbox. The same call again updates the URL. The signing secret is returned on the first create and redacted after that.

Each delivery sends x-cooper-signature (sha256= HMAC-SHA256 of the raw body), x-cooper-signature-v2 (v1= HMAC-SHA256 of the unix timestamp, a dot, and the raw body), x-cooper-timestamp, and x-cooper-delivery. Reject a timestamp older than 5 minutes and dedupe on x-cooper-delivery.

The URL must be public http or https. Localhost, a loopback address, a private IP, benchmarking, multicast, reserved, NAT64, and 6to4 addresses, and a name that resolves to one of those are rejected. Delivery connects to the address that was checked and keeps the original Host header. A delivery that redirects is not followed.

A trigger URL from Zapier, Make, n8n, or another HTTPS automation can be that notify url. Cooper POSTs the signed event to it. POST /api/v1/inboxes accepts notify_url and registers the hook in the same call. MCP cooper_create_inbox accepts notify_url. The catalog stays at 60 tools.

curl -sS -X POST "https://cooperemail.com/api/v1/inboxes/$INBOX/notify" \
  -H "authorization: Bearer $COOP_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/cooper"}'

Long-poll

GET /api/v1/inboxes/{id}/wait holds until unread mail is stored, then returns it. If unread mail is already there, the response is immediate. wait is an integer from 0 to 55 seconds and defaults to 25. The route stops at 55 seconds so it can finish inside a 60 second function limit. A key can hold at most 5 waits at once.

The response is object inbox_wait, with inbox_id, timed_out, and data. timed_out is true when the wait ends with no unread mail. The server checks the database about once a second.

MCP cooper_list_messages accepts wait_seconds and calls this wait. Omit wait_seconds to list mail without holding. GET /api/v1/events?wait= still caps at 25 seconds. That cap is unchanged.

curl -sS "https://cooperemail.com/api/v1/inboxes/$INBOX/wait?wait=55" \
  -H "authorization: Bearer $COOP_KEY"

Cron

A scheduler on the machine that holds the API key can GET the unread list on an interval, for example every 15 minutes. The list is filtered before the limit, so unread mail past the first page is not dropped.

curl -sS "https://cooperemail.com/api/v1/inboxes/$INBOX/messages?unread=true&limit=20" \
  -H "authorization: Bearer $COOP_KEY"

Grok Bot routines

When the host can run work on a timer or from an HTTPS trigger, point that run at Cooper. Call cooper_list_messages with wait_seconds, or register POST /api/v1/inboxes/{id}/notify with the trigger URL.

Cooper MCP setup for this host is at https://cooperemail.com/integrations/grokbot. The hosted server is https://cooperemail.com/mcp. This page does not document that host's scheduler.

Claude scheduled tasks

When the host can run a scheduled task, point it at the Cooper MCP server at https://cooperemail.com/mcp. cooper_list_messages accepts wait_seconds. POST /api/v1/inboxes/{id}/notify registers a webhook when the host gives you an HTTPS trigger URL.

This page does not document that host's scheduler.