Changelog · release notes
What shipped.
One typed list in the repo. The HTML page, /changelog.md, RSS, and Atom stay in sync. Operated by Avatar 8 LLC (ops@avatar33.com).
Agent Skills discovery: install Cooper's skills from cooperemail.com
- GET https://cooperemail.com/.well-known/agent-skills/index.json lists Cooper's public skills.
- $schema is https://schemas.agentskills.io/discovery/0.2.0/schema.json.
- Each entry has type skill-md, an absolute url ending in SKILL.md, and a sha256 digest of those bytes.
- GET https://cooperemail.com/.well-known/skills/index.json is the compatibility index.
- Each entry has name, description, and files SKILL.md, plus url and digest.
- The skill files are also at /.well-known/agent-skills/<name>/SKILL.md and /.well-known/skills/<name>/SKILL.md, and those bytes match /skills/<name>/SKILL.md.
- The skills are cooper-email, cooper-email-mcp, cooper-email-cli, cooper-agent-inbox, cooper-agent-signup-otp, and cooper-owner-approval.
- Hermes Agent installs with hermes skills install well-known:https://cooperemail.com/.well-known/skills/cooper-email-cli.
- hermes skills search https://cooperemail.com --source well-known reads that index.
- Hermes' security scan blocks a skill whose shell examples put an API key variable on a curl line, so the CLI skill is the one to install in Hermes.
- cooper-email-mcp and cooper-owner-approval also install.
- The direct file is hermes skills install https://cooperemail.com/skills/cooper-email-cli/SKILL.md.
- No new MCP tools.
- The catalog stays at 100 tools when SMS and voice are off, 107 when only SMS is on, 101 when only voice is on, and 108 when both are on.
- With SMS, voice, and chat the catalog is 113.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Chat SDK adapter: use a Cooper inbox as a Chat SDK channel
- The Chat SDK adapter is served at https://cooperemail.com/sdk/cooper-email-chat-sdk.tgz.
- npm install https://cooperemail.com/sdk/cooper-email-chat-sdk.tgz chat installs it with no build step.
- createCooperAdapter turns one Cooper inbox into a Chat SDK channel named cooper.
- A signed message.received webhook becomes a Chat SDK message, and thread.post sends a reply with POST /api/v1/inboxes/{id}/messages/{msgId}/reply.
- Edit, delete, and reactions are not supported for email.
- Typing does nothing.
- Docs are /docs/chat-sdk and /docs/chat-sdk.md.
- No new MCP tools.
- The catalog stays at 100 tools when SMS and voice are off, 107 when only SMS is on, 101 when only voice is on, and 108 when both are on.
- With SMS, voice, and chat the catalog is 113.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Agent identity tokens: prove which inbox your agent controls
- An agent can prove which Cooper inbox it controls without an email round trip.
- POST /api/v1/inboxes/{id}/identity-token returns a short-lived ES256 or EdDSA JWT (token_type agent_identity+jwt) for an audience the caller names.
- ttl_seconds defaults to 300 and must be from 60 to 3600.
- The claims are iss https://cooperemail.com, sub (the inbox id), email (the inbox address), email_verified true, aud, iat, exp, jti, an optional nonce, and cooper.agent, cooper.inbox_created_at, cooper.custom_domain, and cooper.owner_verified.
- owner_verified is a boolean.
- The token does not include an account id, a plan, an API key, or the owner's email or name.
- GET /.well-known/jwks.json publishes the public keys.
- GET /.well-known/cooper-identity.json describes the issuer.
- POST /api/v1/identity/verify checks the signature, the audience, the expiry (30 second skew), and that the inbox still exists and its account is not suspended.
- consume true makes that jti single-use.
- A replay is valid false with error token_already_used.
- Offline verification with the JWKS cannot see revocation or single-use.
- Minting needs the message_send permission, so a read-only key cannot mint, and is limited to 60 tokens an hour per inbox.
- Another account's inbox is HTTP 404 inbox_not_found.
- A missing signing key makes these routes HTTP 503 identity_unavailable and leaves every other route unchanged.
- MCP adds cooper_identity_token.
- The catalog is 100 tools when SMS and voice are off, 107 when only SMS is on, 101 when only voice is on, and 108 when both are on.
- With SMS, voice, and chat the catalog is 113.
- MCP server version stays 1.10.0 with SMS and voice off.
- The identity_token_uses table is additive.
- Docs: /docs#agent-identity and /docs/sign-in-with-cooper.
- Available on every plan.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Outbound spam screening
- Outbound sends are scored on this account before mail goes out.
- The score uses recipient fan-out, a repeated body, link-heavy or short-link content, all-caps text, spam phrases, whether the recipient has written to the account before, and account age.
- COOPER_OUTBOUND_SPAM_MODE is off, shadow, or enforce.
- The default is shadow: Cooper computes the score, logs it, and the send is unchanged.
- off skips scoring.
- enforce blocks a score of 60 or higher on an account younger than 14 days, or on an account that already has an abuse signal, with HTTP 422 outbound_spam_blocked and reasons.
- Nothing is sent or stored.
- An account that is 14 days or older and is not flagged is held for operator review instead of blocked, and the message is not sent.
- A reply to a thread the recipient started is exempt.
- Send, reply, reply-all, forward, MCP send, and sending an approved draft share the screen.
- COOPER_OUTBOUND_SPAM_THRESHOLD defaults to 60.
- The new tables are additive.
- No new MCP tools.
- The catalog stays at 98 tools when SMS and voice are off, 105 when only SMS is on, 99 when only voice is on, and 106 when both are on.
- With SMS, voice, and chat the catalog is 111.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
API key links for OAuth accounts, and no bounces during storage trouble
- An account created through OAuth (ChatGPT, Claude, Grok Bot, Claude Code) can now get an API key.
- MCP adds cooper_create_api_key_link and HTTP adds POST /api/v1/keys/link.
- Either needs an OAuth token or a full-access key; a restricted or inbox-scoped key gets HTTP 403 permission_denied.
- The response is a single-use link that expires in 15 minutes.
- The person opens it in a browser and presses Create key, and the next page shows one new full-access key once.
- The key is never in the API or tool response, so it does not land in a chat.
- Existing keys and OAuth connections keep working.
- Links are limited to 5 per hour per account.
- Inbound mail is no longer bounced to the sender when storage fails while a message is being stored: Cooper accepts it, holds it, and stores it within about a minute once storage answers again, without a duplicate.
- GET /api/v1/health reports storage_error as storage_unavailable instead of the provider's error text.
- The catalog is 98 tools when SMS and voice are off, 105 when only SMS is on, 99 when only voice is on, and 106 when both are on.
- With SMS, voice, and chat the catalog is 111.
- MCP server version stays 1.10.0 with SMS and voice off.
- The new tables are additive.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Faster message search indexing and lighter inbox lookups
- New mail is indexed for search without scanning the whole search index, and inbox, owner and attachment lookups use indexes, so polling and listing agents stay fast.
Lighter database load for polling agents
- API key last_used_at now updates at most once a minute.
- A stored time that is still within that minute is left as it is, so last_used_at is accurate to about one minute.
- Null updates on the first use.
- OAuth tokens do not record a per-request last use.
- Internal per-request database load telemetry helps keep polling-heavy agents fast and the service up.
- No new MCP tools.
- The catalog stays at 97 tools when SMS and voice are off, 104 when only SMS is on, 98 when only voice is on, and 105 when both are on.
- With SMS, voice, and chat the catalog is 110.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Setup guides for OpenClaw, Hermes Agent and OpenCode
- Setup guides for OpenClaw, Hermes Agent, and OpenCode are at /integrations/openclaw, /integrations/hermes-agent, and /integrations/opencode.
- The same pages are markdown at /integrations/openclaw.md, /integrations/hermes-agent.md, and /integrations/opencode.md.
- Each guide connects the hosted MCP server at https://cooperemail.com/mcp with Authorization Bearer.
- OpenClaw uses mcp.servers in ~/.openclaw/openclaw.json with transport streamable-http and the key from ~/.openclaw/.env, and openclaw mcp login when auth is oauth.
- Hermes Agent uses mcp_servers in ~/.hermes/config.yaml and the key from ~/.hermes/.env, and auth oauth when the person signs in.
- OpenCode uses mcp.servers in opencode.jsonc with type remote, oauth false, and the key from the process environment, and opencode mcp auth when OAuth stays on.
- POST /api/v1/onboard returns api_key once.
- OpenClaw wakes from a verified message.received webhook that then calls POST /hooks/agent.
- The Gateway hook checks its own token and does not check x-cooper-signature-v2.
- Hermes Agent webhook routes do not accept x-cooper-signature-v2.
- The guide uses Hermes MCP events (events true, subscribe_event for message.received) so the gateway checks Standard Webhooks while hermes gateway run is up.
- OpenCode does not document an inbound webhook, so the guide uses cooper_wait_for_message, cooper_wait_for_code, and GET /api/v1/inboxes/{id}/wait.
- Runnable snippets are in examples/one-inbox-per-run/snippets.
- No new MCP tools.
- The catalog stays at 97 tools when SMS and voice are off, 104 when only SMS is on, 98 when only voice is on, and 105 when both are on.
- With SMS, voice, and chat the catalog is 110.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
New Free accounts have a short send warmup
- A Free account in its first 7 days can send 10 messages an hour, 30 messages a UTC day, and 20 distinct new recipients.
- Send, reply, reply-all, forward, and sending a draft share that cap.
- One message counts once toward the message caps and once per new address toward the recipient cap.
- A client_id replay does not count again.
- The next send returns HTTP 429 new_account_send_limit with Retry-After, retry_after_seconds, and resets_at, and nothing is sent or stored.
- Starter, Pro, grandfathered accounts, and operator accounts are exempt.
- A sub-account uses its parent's plan and age.
- COOPER_NEW_ACCOUNT_DAYS defaults to 7.
- COOPER_NEW_ACCOUNT_HOURLY_SENDS defaults to 10.
- COOPER_NEW_ACCOUNT_DAILY_SENDS defaults to 30.
- COOPER_NEW_ACCOUNT_RECIPIENTS defaults to 20.
- A value of 0 turns that cap off.
- After the window, Free still has no standing daily cap.
- Accounts gain suspended_at and suspended_reason.
- While suspended_at is set, API keys, OAuth access tokens, refresh, MCP, the dashboard, and SMS, voice, and chat return HTTP 403 account_suspended.
- The account cannot un-pause an inbox or mint a key or token.
- Inbound mail is still stored.
- An operator suspends with POST /api/v1/admin/accounts/{id}/suspension and JSON {"suspended":true,"reason":"..."}, and restores with {"suspended":false}.
- The caller must be listed in COOPER_OPERATOR_ACCOUNT_IDS.
- npx tsx scripts/suspend-account.ts writes the same columns without the API.
- A later signup from the same IP as a suspended account sets abuse_signal to repeat_signup_ip and is not blocked.
- The columns and the new_account_sends table are additive.
- No new MCP tools.
- The catalog stays at 97 tools when SMS and voice are off, 104 when only SMS is on, 98 when only voice is on, and 105 when both are on.
- With SMS, voice, and chat the catalog is 110.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Security check: grade an agent inbox before launch
- GET /api/v1/inboxes/{id}/security-check grades one inbox against ten launch checks.
- The response is inbox_id, address, checked_at, summary counts, and checks.
- status is pass, warn, fail, or info.
- info means Cooper does not store that control, and the detail says so.
- The checks are key scope, inbound screening, allowed senders, send limits, webhook signing, human approval, the monthly send cap and Idempotency-Key, domain reputation, tenant isolation, and the event log.
- A shared cooperemail.com address is info.
- Cooper does not publish a separate daily send cap, and the detail says so.
- The result lists key id, key prefix, and webhook ids.
- It does not return the API key, the key hash, or a webhook signing value.
- An inbox-scoped key can grade only its own inbox.
- Another account is HTTP 404 inbox_not_found.
- No key is HTTP 401 unauthorized.
- The route uses inbox_read.
- MCP adds cooper_security_check.
- Omit inbox_id when the key is limited to one inbox.
- The catalog is 97 tools when SMS and voice are off, 104 when only SMS is on, 98 when only voice is on, and 105 when both are on.
- With SMS, voice, and chat the catalog is 110.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Setup guides for Cloudflare Agents and Vercel eve
- Setup guides for the Cloudflare Agents SDK and for Vercel eve are at /integrations/cloudflare-agents and /integrations/vercel-eve.
- The same pages are markdown at /integrations/cloudflare-agents.md and /integrations/vercel-eve.md.
- Each guide connects the hosted MCP server at https://cooperemail.com/mcp with Authorization Bearer, and it describes that framework's documented OAuth client when the client can complete Cooper OAuth.
- A REST fallback calls the API with fetch and the key from a Worker secret or the project environment.
- A message.received webhook, signed with x-cooper-signature-v2 and optional Authorization or X-* headers, wakes the agent.
- Runnable snippets are in examples/one-inbox-per-run/snippets.
- No new MCP tools.
- The catalog stays at 96 tools when SMS and voice are off, 103 when only SMS is on, 97 when only voice is on, and 104 when both are on.
- With SMS, voice, and chat the catalog is 109.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Contact history: everything you've exchanged with one address, in one call
- GET /api/v1/inboxes/{id}/contacts/{address} returns every thread, message, and attachment exchanged with one email address.
- The address is URL-encoded, trimmed, and compared case-insensitively.
- A value that is not an email address is HTTP 400 invalid_address.
- A message counts when that address is the From on inbound mail, or it appears in To or Cc, or it appears in Bcc on mail this account sent.
- The inbox's own address, including a plus address such as local+tag@domain, is not a contact.
- SMS is left out.
- Spam and trash stay out unless folder is set, the same as a thread list.
- limit defaults to 20 and cannot exceed 100.
- before and after are exclusive ISO-8601 bounds.
- cursor pages the messages, newest first.
- The scan keeps the newest 5000 matching messages.
- summary counts that window, and summary.truncated is true when older matches were left out.
- threads lists at most 50 of those threads, newest activity first, and threads_has_more is true when more threads are in the window.
- include=bodies adds text bodies.
- The default omits them.
- Attachments are metadata only: id, filename, content type, and size.
- GET /api/v1/contacts/{address} is the same history for the account.
- inbox_id limits it to one inbox and follows the same inbox pin as GET /api/v1/search.
- Another account's inbox is HTTP 404 inbox_not_found.
- The route uses message_read.
- MCP adds cooper_contact_history.
- The catalog is 96 tools when SMS and voice are off, 103 when only SMS is on, 97 when only voice is on, and 104 when both are on.
- With SMS, voice, and chat the catalog is 109.
- MCP server version stays 1.10.0 with SMS and voice off.
- There is no database migration.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Custom domains: send your human one setup link
- POST /api/v1/domains/{id}/setup-link returns one link the human opens to publish DNS.
- expires_in_hours is an integer from 1 to 168 and defaults to 72.
- The token is random and only its SHA-256 hash is stored.
- A new link revokes the previous link for that domain.
- DELETE /api/v1/domains/{id}/setup-link revokes it and returns HTTP 204, including a repeat call.
- The page shows the hostname, pending or verified, each record with a copy button, the last status and hint, an existing_mail_provider warning when one is present, a zone file, and short steps for the DNS host.
- Check now runs the same verify as POST /api/v1/domains/{id}/verify, including the 60 second limit and domain.verified.
- An expired, revoked, or unknown link returns HTTP 404 and does not show the hostname.
- The link is not an API key.
- A verified domain can still have a link.
- When dns.mode is external, POST /api/v1/domains adds setup_link_hint.
- MCP adds cooper_domain_setup_link.
- The catalog is 95 tools when SMS and voice are off, 102 when only SMS is on, 96 when only voice is on, and 103 when both are on.
- With SMS, voice, and chat the catalog is 108.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Custom domains: hostnames in operator-managed zones are refused
- POST /api/v1/domains returns HTTP 409 domain_reserved when the hostname is inside a zone that Cooper's operator manages.
- Nothing is written for that hostname.
- Your own domains are unchanged: external DNS records as before, and Free still includes 1 custom domain.
- No new MCP tools.
- The catalog stays at 94 tools when SMS and voice are off, 101 when only SMS is on, 95 when only voice is on, and 102 when both are on.
- With SMS, voice, and chat the catalog is 107.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Plus addresses route into the same inbox
- Mail to local+tag@domain is stored in the inbox local@domain when no inbox has that exact address.
- An exact inbox at the plus address wins, and that message has alias null.
- The tag is everything after the first + in the local part, lowercased, and must be 1 to 64 characters of letters, digits, and .
- _ -.
- Any other tag is not delivered (HTTP 404 inbox_not_found), the same as an unknown address.
- An empty tag (local+@domain) is delivered to the base inbox with alias null.
- Reserved names such as hello and postmaster gain this routing only when that address is already a real inbox.
- A paused inbox drops the mail with inbox_paused, the same as mail to the exact address.
- One message addressed to agent+a and agent+b is stored once.
- alias is the first tag in recipient order.
- aliases lists every tag.
- The message gains the label alias: plus that tag, so the existing labels filter still matches.
- GET /api/v1/inboxes/{id}/messages?alias=tag returns that tag.
- alias=none returns mail with no alias.
- A bad tag is HTTP 400 invalid_alias with param alias.
- GET /api/v1/inboxes/{id}/wait, GET /api/v1/inboxes/{id}/wait-for-code, and the MCP waits accept the same alias.
- An inbox rule condition alias matches that tag.
- A reply still sends From the inbox address, not the plus address.
- Inbox JSON adds read-only alias_format, username+{tag}@domain.
- Inbound message JSON, thread message lists, webhooks, and message.received add alias.
- Outbound alias is null.
- Plus addresses are not inboxes.
- They use the same quota, the same keys, and the same owners.
- Allow lists, block lists, require_sender_auth, screening, suppressions, rules, and auto-forward follow the base inbox.
- A plus address cannot reach an inbox on another domain.
- messages.alias is a nullable column, added on an existing database before any index.
- No new MCP tools.
- The catalog stays at 94 tools when SMS and voice are off, 101 when only SMS is on, 95 when only voice is on, and 102 when both are on.
- With SMS, voice, and chat the catalog is 107.
- MCP server version stays 1.10.0 with SMS and voice off.
- Docs: /docs/aliases.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Forward inbound mail to verified external addresses
- An inbox can forward a copy of every received email to up to 5 verified external addresses.
- POST /api/v1/inboxes/{id}/forwarding/verifications with {email} returns HTTP 202 and emails a 6-digit code to that address only.
- The code is not stored in any Cooper inbox and is not in the response.
- The same client_id returns the original destination and does not send another code.
- An address that is already verified returns HTTP 200 and does not send mail.
- POST /api/v1/inboxes/{id}/forwarding/confirm with {email, code} marks it verified.
- A code that is not 6 digits, or that does not match, is HTTP 400 confirm_invalid.
- The code expires in 48 hours, and after five wrong attempts, and then the response is HTTP 400 confirm_expired.
- GET /api/v1/inboxes/{id}/forwarding returns destinations and unverified.
- PUT with {emails} replaces the verified list.
- Every address must already be verified on this inbox, or the response is HTTP 400 forwarding_not_verified.
- Pending rows stay.
- DELETE /api/v1/inboxes/{id}/forwarding/{destinationId} removes one.
- destinationId is the ifd_ id or the email.
- A sixth destination returns HTTP 409 forwarding_limit.
- That cap is technical and does not change Free, Starter, or Pro.
- The inbox itself, an address at cooperemail.com, and any address that is already a Cooper inbox are HTTP 400 forwarding_target_not_allowed.
- Confirmation email is limited to 5 per hour per IP and 3 per day per address, then HTTP 429 rate_limited.
- GET needs message_read.
- Writes need inbox_update.
- An inbox-scoped key only sees its inbox.
- When inbound mail is stored, each verified destination receives a forward through the same send path as POST forward, including quotas, suppressions, sending health, and send_mode.
- Approval mode stores a pending draft.
- The copy sets Auto-Submitted: auto-forwarded, X-Cooper-Auto-Forward, and X-Cooper-Forwarded.
- Cooper does not forward outbound mail, spam or trash, a bounce, a complaint, or an auto report, mail that already has Auto-Submitted other than no or those markers, or a destination equal to the inbox.
- An inbox sends at most 30 of these forwards per rolling hour.
- A skipped forward does not drop the inbound message.
- rules forward_to is unchanged.
- It still accepts only another inbox on this account or a verified owner of this inbox.
- MCP adds cooper_list_forwarding, cooper_request_forwarding, cooper_remove_forwarding, and cooper_set_forwarding.
- Those tools do not accept or return the confirmation code.
- The catalog is 94 tools when SMS and voice are off, 101 when only SMS is on, 95 when only voice is on, and 102 when both are on.
- With SMS, voice, and chat the catalog is 107.
- MCP server version stays 1.10.0 with SMS and voice off.
- Docs: /docs/forwarding.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Free includes 1 custom domain
- Free includes 1 custom domain.
- POST /api/v1/domains on Free adds and verifies one hostname.
- A second distinct domain returns HTTP 402 plan_limit_exceeded.
- The error limit is 1.
- Free cannot buy extra domains with POST /api/v1/billing/addons.
- Starter stays at 15 custom domains and Pro stays at 200.
- Inboxes and monthly emails are unchanged.
- Mail on a custom domain still follows COOPER_CUSTOM_DOMAIN_MAIL.
- This change does not turn that flag on.
- AgentMail's pricing page, re-read 2026-11-05, lists 1 custom domain on Free.
- The AgentMail rate-limits doc still says Free domains None.
- Cooper matches the pricing page.
- No database migration.
- No new MCP tools.
- The catalog stays at 90 tools when SMS and voice are off, 97 when only SMS is on, 91 when only voice is on, and 98 when both are on.
- With SMS, voice, and chat the catalog is 103.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Report a leaked API key and Cooper revokes it
- POST /api/v1/keys/report-leak needs no API key.
- The body is one object or an array of at most 20 objects.
- Each object has key, and may have source_url and reporter.
- token is an alias of key.
- url is an alias of source_url.
- Unknown fields are ignored.
- key is required, trimmed, and at most 200 characters.
- source_url is optional, must be http or https, and is at most 2048 characters.
- reporter is optional plain text of at most 200 characters and is not stored.
- A string that does not match coop_live_ plus 32 base64url characters is accepted and ignored.
- A matching key that is not revoked is revoked immediately.
- revoked_at and leak_reported_at are set to now, revoked_reason is leak_reported, and leak_source_url stores the reported URL or null.
- An already revoked key and an unknown key are left unchanged and no email is sent.
- The response is HTTP 202 {received} for every report that passes validation, including when nothing matched.
- The response does not say whether a key was valid.
- The raw key is not stored and is not returned.
- The route allows 30 requests per hour per IP, then HTTP 429 rate_limited with Retry-After.
- Each verified owner address on the account is emailed once.
- The subject is [Security] Cooper API key revoked: plus the key name.
- The body names the key, the prefix, the key id, the time, and the source URL as plain text.
- It tells the owner to mint a replacement with POST /api/v1/keys.
- An account with no verified owner gets no email.
- The same per-owner send limits as other owner mail apply.
- DELETE /api/v1/keys/{id} sets revoked_reason to manual on a new revocation.
- A key revoked before this change keeps revoked_reason null.
- GET /api/v1/keys and GET /api/v1/keys/{id} add revoked_reason and leak_reported_at.
- api_keys gains revoked_reason, leak_reported_at, and leak_source_url.
- Those columns are on the fresh table and are added with ALTER TABLE for an existing database before any index.
- key.leak_reported is stored in the event log.
- A webhook receives it only when its events list includes that type.
- The payload has no key.
- No new MCP tools.
- The catalog stays at 90 tools when SMS and voice are off, 97 when only SMS is on, 91 when only voice is on, and 98 when both are on.
- With SMS, voice, and chat the catalog is 103.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Uncommitted events stay for up to 90 days
- Uncommitted events for an active durable event consumer are kept for up to 90 days.
- The daily cron still deletes other events after 7 days.
- An event is kept past 7 days only when it is strictly after an active consumer's cursor on the same account, it matches that consumer's inbox when one is set, it matches that consumer's types when a list is set, and it is not older than 90 days.
- Nothing in the event log is kept longer than 90 days.
- A consumer with no create, poll, or commit for 90 days is stale.
- A stale consumer does not keep events.
- The cron does not delete it, and it still counts toward the 50 consumer cap.
- Reset does not count as activity.
- A later poll or commit makes it active again.
- Events that aged out while it was stale are not rebuilt.
- events_may_have_expired stays a boolean.
- It is true when the committed cursor is older than the events that consumer was guaranteed to keep.
- For an active consumer that floor is the later of 90 days ago and 7 days before the consumer was created.
- For a stale consumer the floor is 7 days ago.
- The poll uses activity from before that poll.
- start oldest is 7 days ago, including on reset.
- That is the window every account still has.
- It does not move to rows another consumer kept past 7 days.
- An ISO-8601 start can begin earlier.
- Deleted rows are not rebuilt.
- GET /api/v1/events still defaults after to one hour ago.
- An older after returns events that are still stored.
- An account with no consumers still has only the 7-day log.
- The shell CLI adds events pull, events commit, events list, and events delete.
- events pull creates or reuses the consumer, prints the poll JSON, and with --commit posts that commit_cursor after printing.
- The script version is 1.1.0.
- /cli/cooper.mjs and /cli/cooper-cli.tgz serve that script.
- There is no database migration.
- No new MCP tools.
- The catalog stays at 90 tools when SMS and voice are off, 97 when only SMS is on, 91 when only voice is on, and 98 when both are on.
- With SMS, voice, and chat the catalog is 103.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Ask your owner a question and wait for the answer
- POST /api/v1/questions asks every verified owner of an inbox and returns a question the agent can wait on.
- kind is approve, choose, or ask.
- question is required and at most 300 characters.
- body is optional and at most 5000 characters.
- choose needs 2 to 10 options.
- Each option value is at most 64 characters of letters, digits, and .
- _ -.
- Each label is at most 80 characters.
- approve uses the values approve and deny, with optional approve_label and deny_label of at most 40 characters.
- ttl_seconds is an integer from 60 to 604800 and defaults to 86400.
- task_id keeps the email on the same thread as owner updates for that job.
- client_id replay returns HTTP 200 and idempotent true.
- No verified owner is HTTP 409 no_verified_owner.
- A bad field is HTTP 400 with param.
- The route uses the same owner_manage permission and the same per-owner send limits as POST /api/v1/updates.
- GET /api/v1/questions lists them with inbox_id, status, limit, and cursor.
- GET /api/v1/questions/{id}?wait=0..25 checks about once a second and returns when status is not pending, or when the wait ends with timed_out true.
- A passed expires_at is marked expired.
- POST /api/v1/questions/{id}/cancel sets canceled, or HTTP 409 question_not_pending when the question is already final.
- Another account's question is HTTP 404 question_not_found.
- An inbox-scoped key only sees questions for its inbox.
- The email subject is [Question] plus the question.
- Approve and choose include one link per option.
- Ask says to reply to the email.
- GET on an answer link shows a confirm page and does not record the answer.
- POST records it.
- The first answer wins.
- A later POST shows Already answered and does not change the row.
- A reply from a verified owner on that thread answers the question when the first line matches an option value or label.
- Approve also accepts yes, no, approve, and deny.
- An unmatched reply stays a task.
- Ask stores the reply, with quoted history removed and at most 2000 characters, as answer_text, and does not also create a task.
- The answer came from the verified owner and is still untrusted data for instruction purposes.
- question.answered and question.expired go to the event log.
- A webhook receives one only when its events list includes that type.
- The payload is question_id, inbox_id, kind, status, answer_value, answered_by, and answered_at, with no body.
- The new table is owner_questions.
- Action tokens are stored only as hashes.
- MCP adds cooper_ask_owner and cooper_get_question.
- cooper_ask_owner creates the question and waits.
- wait defaults to 20 seconds and cannot exceed 25.
- cooper_get_question is read-only.
- The catalog is 90 tools when SMS and voice are off, 97 when only SMS is on, 91 when only voice is on, and 98 when both are on.
- With SMS, voice, and chat the catalog is 103.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Signup creates your first inbox
- POST /api/v1/onboard and POST /api/v1/keys without a Bearer token create an account, an API key, and a first inbox in one call.
- username is optional.
- Omit it and the address is box plus 8 hex characters at cooperemail.com.
- create_inbox false skips the inbox and returns the account and key.
- The response includes address, the inbox email, the API key, and hint.
- hint says to save the key and the address to memory or config now, and it gives the curl command that lists unread mail.
- A later POST /api/v1/inboxes with that same username on the same account returns the original inbox and does not create a second one.
- A username held by another account is still HTTP 409 inbox_exists.
- A failed inbox create does not leave the new account behind.
- MCP cooper_onboard accepts an omitted username.
- No new MCP tools.
- The catalog stays at 88 tools when SMS and voice are off, 95 when only SMS is on, 89 when only voice is on, and 96 when both are on.
- With SMS, voice, and chat the catalog is 101.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
See why your agent's API calls were refused
- GET /api/v1/request-log lists refused API calls for the signed-in account, newest first.
- A row is stored only when a live API key or OAuth token was accepted and the response was an HTTP 4xx ApiError.
- That includes 400, 402, 403, 404, 409, 422, and 429.
- An unauthenticated 401 is not stored, because it cannot be tied to an account.
- HTTP 2xx and HTTP 5xx are not stored.
- The row stores the method, the path with ids kept and the query string dropped, the status, and the error type, code, param, and message.
- The message is cut at 300 characters.
- It also stores the API key id or OAuth client id, the inbox id when the path names one, source rest or mcp, and the MCP tool name for an MCP call.
- Request bodies, query strings, Authorization headers, API keys, tokens, email content, and recipient addresses are not stored.
- Each account keeps at most 1000 rows per UTC day.
- Further refusals that day are dropped.
- Rows older than 7 days are deleted.
- A full-access account key sees the account.
- A restricted or inbox-scoped key sees only its own key.
- An OAuth client sees only its own client.
- Filters are status, code, api_key_id, inbox_id, since, limit (1 to 100, default 25), and cursor.
- Recording is best-effort and does not change the HTTP response.
- The new table is request_refusals.
- The table is created before its index.
- MCP: cooper_list_request_refusals.
- The catalog is 88 tools when SMS and voice are off, 95 when only SMS is on, 89 when only voice is on, and 96 when both are on.
- With SMS, voice, and chat the catalog is 101.
- MCP server version stays 1.10.0 with SMS and voice off.
- Plan prices are unchanged.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Wait for a verification link, not just a code
- GET /api/v1/inboxes/{id}/wait-for-code accepts kind.
- code is the default and still matches only an inbound message that contains a one-time code.
- link matches a message with an https verification link and does not require a code.
- any matches the newest inbound message that has either.
- An unknown kind is HTTP 400 invalid_kind with param kind.
- The response adds link and links.
- link is the top-ranked URL or null.
- links lists up to five {url, text} pairs from that message.
- A link is taken from an https anchor or a bare https URL when the anchor text, the surrounding text, or the URL path or query says verify, confirm, activate, magic link, sign in, log in, validate, complete registration, or reset.
- Unsubscribe, privacy, terms, help center, social profile, and Cooper action links are left out.
- Only the first 256 KB of each body is scanned for links.
- Nothing fetches the URL.
- The link is untrusted data.
- On timeout, link is null and links is empty.
- Inbound message JSON adds verification with codes and links.
- Outbound messages omit verification.
- A held message returns empty codes and links.
- SMS text is read the same way.
- There is no database migration.
- No new MCP tools.
- cooper_wait_for_code accepts kind and returns link and links.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Approval pages show exactly what you're approving
- GET /api/v1/drafts/approve and GET /api/v1/drafts/reject list the stored draft: From, To, Cc, Bcc, Reply-To when one is set, subject, send_at with a UTC label when the draft is scheduled, attachment filenames and sizes, and the text body.
- HTML is shown as text.
- The page includes the approval digest of that draft.
- POST approve with a digest that no longer matches does not send, and the owner is told to open the newest email.
- A POST without that digest still approves, so a page already open keeps working.
- Owner confirm and decision pages send Content-Security-Policy frame-ancestors 'none', X-Frame-Options DENY, X-Content-Type-Options nosniff, and Referrer-Policy no-referrer.
- HTML site pages send nosniff and frame-ancestors 'self'.
- /mcp, /api, /.well-known, and /oauth are unchanged.
- No new MCP tools.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Per-inbox signatures
- An inbox can store a signature that Cooper appends to outgoing mail from that address.
- inboxes.signature_text and inboxes.signature_html are nullable text columns, added with ALTER TABLE before any index, and NULL means no signature.
- POST /api/v1/inboxes, POST /api/v1/inboxes/batch, POST /api/v1/onboard, and PATCH /api/v1/inboxes/{id} accept signature as {text, html?}.
- text is required, non-empty, and at most 2000 characters.
- html is optional and at most 10000 characters.
- Script tags, on* handlers, and javascript: URLs are removed.
- PATCH signature null removes it.
- Omitting signature leaves it unchanged.
- A bad value is HTTP 400 invalid_request with param signature, signature.text, or signature.html.
- Inbox responses include signature as {text, html} or null.
- The same inbox_update permission as the rest of PATCH is required.
- Sends, replies, reply-all, forwards, draft sends, scheduled flushes, approval releases, task replies, and inbox-rule auto-replies place the signature after the caller's content and above any quoted or forwarded original.
- Plain text uses a blank line, "-- ", and the signature text.
- HTML uses a div with class cooper-signature.
- A text-only signature is escaped into HTML when the message already has an HTML part.
- A text-only message uses the text signature.
- A body that already contains the signature text is sent as written.
- include_signature false on send, reply, reply-all, forward, and draft create or update skips it, and that choice is kept until a draft is sent.
- The stored message matches what was sent.
- Sign-in mail, owner alerts, and approval requests are not signed.
- SMS, voice, and chat are not signed.
- No new MCP tools.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Scheduling a draft now requires send permission
- Scheduling a draft (send_at) counts as sending and needs message_send or draft_send.
- POST /api/v1/inboxes/{id}/drafts with a non-null send_at, and PATCH that sets send_at to a non-null time, return HTTP 403 permission_denied with param send_at when the key has neither.
- The message says scheduling a draft sends it and the key needs message_send or draft_send.
- Nothing is written.
- PATCH send_at null still unschedules with draft_write.
- A key with only draft_send can PATCH send_at on an existing draft and cannot change other fields.
- Editing recipients, subject, body, or attachments of a draft whose send_status is scheduled needs message_send or draft_send.
- Labels on that draft stay on draft_write.
- Full-access keys, OAuth tokens, and keys with message_send keep the previous create, edit, schedule, and send behavior.
- drafts.scheduled_by_key_id and drafts.scheduled_at record who scheduled it.
- A null scheduled_by_key_id is a full-access key, an OAuth token, or a draft scheduled before this column, and those rows still flush.
- When scheduled_by_key_id is set and that key is revoked, expired, deleted, or no longer has message_send or draft_send, the minute flush does not send.
- send_status becomes blocked, the scheduled label is removed, and send_error records why.
- POST /api/v1/inboxes/{id}/drafts/{draftId}/send can still send that draft when the caller has message_send or draft_send.
- A scheduled draft on an approval inbox still waits for owner approval before flush.
- Creating a rule with forward_to or auto_reply, replacing actions with either, or enabling a disabled rule that has them, needs message_send.
- That refusal is HTTP 403 permission_denied with param actions.
- Disabling a rule, removing those actions, and rules already stored keep working on message_update.
- POST /messages, reply, reply-all, forward, inbound, SMS, calls, and agent-to-agent send stay on message_send.
- Task reply stays on task_reply.
- Idempotency release and resolve stay on message_send.
- send_mode stays on inbox_update.
- No new MCP tools.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
AI Catalog and MCP Server Card discovery
- GET /.well-known/ai-catalog.json returns an AI Catalog 1.0 document with Content-Type application/ai-catalog+json.
- The host display name is Cooper Email, the host identifier is did:web:cooperemail.com, and documentationUrl is https://cooperemail.com/docs/discovery.
- The entry identifier is urn:air:cooperemail.com:mcp:cooper-email, the type is application/mcp-server-card+json, and the url is https://cooperemail.com/mcp/server-card.
- GET /mcp/server-card returns a SEP-2127 MCP Server Card with Content-Type application/mcp-server-card+json when that type is accepted, and application/json when the client asks only for JSON.
- The card name is com.cooperemail/cooper-email.
- Its version is the same version initialize reports in serverInfo.
- remotes is one streamable-http URL, https://cooperemail.com/mcp.
- supportedProtocolVersions is 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26, the revisions the MCP route accepts.
- The card does not list tools.
- Both URLs send Access-Control-Allow-Origin *, allow GET, HEAD, and OPTIONS, Cache-Control public, max-age=3600, a strong ETag, 304 when If-None-Match matches, and OPTIONS 204.
- HEAD returns the same headers.
- /.well-known/mcp.json and /.well-known/mcp/server-card.json keep the same JSON body and add a Link header to the AI Catalog.
- /.well-known/cooper-email.json adds ai_catalog and mcp_hosted_server_card.
- Docs: /docs/discovery and /docs/discovery.md.
- No new MCP tools.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Signup attribution and install pages
- POST /api/v1/onboard and POST /api/v1/inboxes accept an optional ref slug, an X-Client header, and heard_from.
- The account stores the first values.
- A later inbox does not change them.
- ref is also accepted as ?ref= or X-Cooper-Ref.
- heard_from is also the X-Cooper-Heard-From header.
- Pages: /for/grok-bot, /for/claude, /for/cursor, /agentmail-alternative, and /guides/human-in-the-loop-email-for-agents.
- Hosted MCP stays at https://cooperemail.com/mcp.
- No new MCP tools.
- The catalog stays at 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Idempotency keys survive ambiguous send failures
- An Idempotency-Key stays in the state unknown when a send may have been accepted.
- A timeout, a network error, a provider 5xx, and HTTP 502 smtp_provider_error, sms_provider_error, or voice_provider_error from those failures keep the key.
- The same key and the same request then returns HTTP 409 idempotency_outcome_unknown and does not send again.
- The error includes state, since, last_error, and message_id when a stored row is linked.
- Check the sent folder or GET messages, then POST /api/v1/idempotency-keys/{key}/resolve with message_id or DELETE the key, or retry with a new key.
- A validation or policy refusal still removes the key, including HTTP 400, 402, 403, 404, 409, and 422, plus smtp_not_configured, sms_not_configured, and voice_not_configured, and a provider 4xx rejection.
- A fresh in_progress row still returns HTTP 409 idempotency_request_in_progress.
- An in_progress row older than 10 minutes is treated as unknown.
- Done keys expire after 24 hours.
- Unknown keys are kept for 7 days, then the daily cron deletes them.
- GET /api/v1/idempotency-keys/{key} needs message_read.
- DELETE and POST /resolve need message_send.
- Cloudflare Email Sending falls through to Resend only on an auth or permission refusal.
- A timeout or 5xx does not fall through.
- A Resend send under an Idempotency-Key also sends Idempotency-Key cooper-<account>-<key>.
- MCP adds cooper_get_idempotency_key, cooper_release_idempotency_key, and cooper_resolve_idempotency_key.
- The catalog is 87 tools when SMS and voice are off, 94 when only SMS is on, 88 when only voice is on, and 95 when both are on.
- With SMS, voice, and chat the catalog is 100.
- MCP server version stays 1.10.0 with SMS and voice off.
- Docs: /docs/idempotency.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Custom domains on external DNS
- A custom domain whose DNS is not a zone on the operator Cloudflare account uses dns.mode external.
- POST /api/v1/domains still writes records when that hostname is an active zone on the account, and dns.mode is automatic.
- A zone on the account that is not active stays manual and keeps nameserver instructions.
- External mode returns the receiving MX, the return-path MX and one SPF TXT with a single include, the DKIM TXT, a DMARC TXT (an existing record is left as published), and the _cooper-verify TXT.
- Each record has host, type, value, priority for MX, and ttl.
- You add them at your DNS host.
- Cooper checks them with public DNS.
- An existing SPF is merged into that one record.
- warnings include spf_dash_all when an SPF ends in -all without the include, and dmarc_reject when DMARC is p=reject.
- mail.receiving becomes true after the receiving MX verifies and the operator has set RESEND_WEBHOOK_SECRET and RESEND_DOMAINS_API_KEY (or RESEND_API_KEY).
- mail.sending becomes true after the return-path and DKIM records verify.
- POST /api/v1/inboxes with domain still requires the domain to be verified and mail.receiving true.
- Receiving on a Cloudflare zone goes live within a few minutes.
- DELETE removes a Resend domain only when Cooper created it, and a cleanup that does not finish keeps status cleanup_failed and deleted false.
- Inbound for external DNS is stored from the Resend email.received webhook.
- Outbound from an external-DNS domain uses Resend (RESEND_DOMAINS_API_KEY, or RESEND_API_KEY) and does not try the operator Cloudflare Email Sending account.
- Reserved local parts such as hello, support, and postmaster stay reserved on the shared platform domain; a customer's own verified custom domain may use them.
- No new MCP tools.
- The catalog stays at 84 tools when SMS and voice are off.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Inbox rules
- An inbox can run deterministic rules when mail arrives.
- POST /api/v1/inboxes/{id}/rules stores a rule.
- GET lists them.
- GET, PATCH, and DELETE /api/v1/inboxes/{id}/rules/{ruleId} read, change, and remove one.
- POST /api/v1/inboxes/{id}/rules/test is a dry run and writes nothing.
- Conditions are combined with AND: from (an email, @domain, or a domain), to, subject_contains, body_contains, has_attachment, auth pass or fail (DMARC), and list.
- Actions are add_labels, folder (inbox, archive, spam, or trash), mark_read, forward_to, and auto_reply.
- stop_processing ends later rules.
- Rules run in position order, then created_at.
- An inbox stores at most 20 rules.
- The next create returns HTTP 409 rule_limit.
- That cap is technical and does not change Free, Starter, or Pro.
- forward_to must be another inbox on the same account or a verified owner of this inbox.
- Anything else is HTTP 400 forward_target_not_allowed, and the address is checked again when mail arrives.
- Auto-reply and forward use the normal send path, including quotas, suppressions, sending health, and send_mode.
- Approval mode stores a pending draft.
- Auto-reply sets Auto-Submitted: auto-replied, defaults the subject to Re: plus the original subject, and waits cooldown_hours per sender.
- cooldown_hours defaults to 24 and must be from 1 to 720.
- Both sends are skipped for list blocks, held or suspicious mail, a DMARC failure, a sender on this account, Auto-Submitted other than no or another auto-responder header, Precedence bulk, junk, list, or auto_reply, List-Id or List-Unsubscribe, an empty Return-Path, and a sender local part of mailer-daemon, postmaster, no-reply, noreply, do-not-reply, donotreply, bounce, or bounces.
- An inbox sends at most 30 rule forwards, auto-replies, and approval drafts per rolling hour.
- A rule error does not drop the mail.
- Message JSON adds rules_applied when a rule matched.
- rule.matched is stored in the event log with inbox_id, message_id, thread_id, rule_id, actions, and skipped, and no message body.
- A webhook receives it only when its events list names rule.matched.
- MCP adds cooper_list_rules, cooper_create_rule, cooper_update_rule, cooper_delete_rule, and cooper_test_rule.
- The catalog is 84 tools when SMS and voice are off, 91 when only SMS is on, 85 when only voice is on, and 92 when both are on.
- With SMS, voice, and chat the catalog is 97.
- MCP server version stays 1.10.0 with SMS and voice off.
- Docs: /docs/rules.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Thread folders: archive, spam, and trash
- A thread can sit in inbox, archive, spam, or trash.
- No folder row means inbox.
- PATCH /api/v1/inboxes/{id}/threads/{threadId} accepts folder with or without label changes.
- Moving to inbox deletes the row.
- The same folder twice does not change moved_at and does not emit an event.
- POST /api/v1/inboxes/{id}/threads/move accepts 1 to 100 thread ids and returns {moved, not_found}.
- GET thread, both thread lists, thread search, message lists, and message search include folder.
- purge_after is set only for trash, to moved_at plus 30 days.
- When the folder query parameter is absent, those lists return inbox and archive and hide spam and trash.
- folder=all returns every folder.
- A bad value is HTTP 400 invalid_folder.
- Existing filters still combine.
- A new inbound message on an archived thread returns it to inbox and emits thread.folder_updated with reason new_message.
- Spam and trash stay where they are.
- An outbound send or reply does not change the folder.
- block_sender true is accepted only with folder spam.
- It adds the latest inbound From address to that inbox's receive block list and returns blocked_sender.
- The daily cron hard-deletes trash whose purge_after has passed, through the same path as DELETE thread, at most 100 threads per run.
- DELETE thread stays an immediate permanent delete.
- Deleting a thread, an inbox, or a workspace removes its folder rows and does not emit thread.folder_updated.
- The event data is {inbox_id, thread_id, folder, previous_folder, reason, purge_after} and has no message body.
- A webhook receives thread.folder_updated only when its events list names that type.
- A webhook created without an events list still receives only message.received.
- Omitting types on GET /api/v1/events, the SSE stream, and an event consumer returns every stored type.
- message.received, tasks, and MCP Events still fire for mail on any folder.
- MCP Events stays message.received only.
- The owner thread, owner digests, chat, wait, and wait-for-code do not apply the folder filter.
- MCP adds cooper_move_threads.
- cooper_update_thread accepts folder and block_sender.
- cooper_list_threads, cooper_search_threads, cooper_list_messages, cooper_search_messages, and cooper_search accept folder.
- The catalog is 79 tools when SMS and voice are off, 86 when only SMS is on, 80 when only voice is on, and 87 when both are on.
- MCP server version is 1.10.0 with SMS and voice off, 1.10.0 when only SMS tools are visible, and 1.11.0 when voice tools are visible.
- Docs: /docs/folders.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Instant replies from the owner
- An owner message can wake an agent within seconds.
- PUT /api/v1/inboxes/{id}/wake registers one webhook for task.received, owner.reply, and chat.message on that inbox.
- The same call updates the URL.
- DELETE turns it off and is safe to repeat.
- headers is optional and accepts Authorization or X-* names.
- Omit headers to keep the stored ones.
- An empty object clears them.
- The signing secret is returned on create and redacted after that.
- Localhost and private addresses are rejected.
- MCP adds cooper_enable_instant_replies.
- initialize tells the agent to subscribe to message.received with events/subscribe, or to long-poll with cooper_wait_for_message or cooper_list_messages wait_seconds, or to register that wake webhook.
- Nothing new is required at signup.
- An agent that still polls gets one optional instant_replies field when it lists messages, unread mail, or tasks and nothing is listening.
- That field is omitted from MCP text for 24 hours after it is shown.
- The owner app shows a green dot when the agent replies instantly and a gray dot when it checks periodically.
- The catalog is 78 tools when SMS and voice are off, 85 when only SMS is on, 79 when only voice is on, and 86 when both are on.
- MCP server version stays 1.9.0 with both off, 1.10.0 with only SMS on, and 1.11.0 when voice tools are visible.
- Docs: /docs/instant-replies.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Owner and agent chat
- A verified owner and an agent inbox can keep a live thread.
- POST /api/v1/owner/pair-codes mints a single-use code.
- The agent calls cooper_chat_join, then cooper_chat_wait in a loop, and answers with cooper_chat_send.
- REST is GET and POST /api/v1/inboxes/{id}/chat/messages, POST /api/v1/inboxes/{id}/chat/typing, and POST /api/v1/chat/join.
- The owner listens on GET /api/v1/owner/stream.
- A console task reply is stored in the thread and does not send mail.
- An email task still sends mail.
- The owner's full address is not returned.
- The printed join command is for a later CLI release and this release does not run it.
- The catalog is 82 tools when SMS and voice are off, 89 when only SMS is on, 83 when only voice is on, and 90 when SMS, voice, and chat are on.
- Docs: /docs/chat.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Thread assignment and claims
- Assign a thread to a named handle, or take an exclusive claim so two workers do not reply to the same conversation.
- PUT /api/v1/inboxes/{id}/threads/{threadId}/assignment accepts assignee (required, 1 to 64 characters: letters, digits, and .
- _ @ + : -), note (optional, at most 500 characters), lease_seconds (optional integer from 30 to 86400), and force (optional boolean, default false).
- assignee is a free-form handle chosen by the caller, such as an agent name, a worker id, or an owner email.
- There is no seats model.
- GET returns {assignment:null} when the thread exists and nobody is assigned, and HTTP 404 thread_not_found when the thread does not.
- The public object is {object:"thread_assignment", inbox_id, thread_id, assignee, note, claimed_until, claim_active, assigned_at, updated_at}.
- When lease_seconds is set, claimed_until is now plus that many seconds and the assignment is an exclusive claim.
- A different assignee that writes while claimed_until is still in the future receives HTTP 409 thread_claimed, and the error includes assignee and claimed_until.
- The same assignee can renew the claim, and that renew does not emit an event.
- force true overwrites an active claim.
- Omitting lease_seconds stores a plain assignment and sets claimed_until to null.
- A plain assignment is not exclusive.
- Two concurrent claims from different assignees resolve in one conditional upsert, so exactly one wins.
- DELETE releases the assignment.
- Optional assignee releases the row only when it is assigned to that handle, or when the claim has expired.
- A release that does not match returns HTTP 409 thread_claimed.
- Nothing assigned returns {assignment:null, released:false}.
- GET thread, the inbox thread list, GET /api/v1/threads, and thread search include assignment, null when none is stored.
- List filters assignee, unassigned=true, and claimable=true (unassigned or the claim has expired) apply to the inbox list and the account list.
- Existing paging and fields stay.
- Deleting a thread, an inbox, or a workspace deletes its assignment rows.
- A new inbound message does not change an assignment.
- Events thread.assigned and thread.unassigned are stored in the event log and delivered to webhooks whose events list includes that type.
- A webhook created without an events list still receives only message.received.
- Omitting types on GET /api/v1/events, the SSE stream, and an event consumer returns every stored type, including thread.assigned and thread.unassigned once they exist.
- thread.assigned fires when the assignee changes or a new claim starts.
- A renew by the same assignee does not fire.
- The payload is the assignment object plus previous_assignee and does not include message bodies.
- MCP Events stays message.received only.
- MCP adds cooper_assign_thread and cooper_unassign_thread.
- cooper_list_threads accepts assignee, unassigned, and claimable.
- The catalog is 77 tools when SMS and voice are off, 84 when only SMS is on, 78 when only voice is on, and 85 when both are on.
- MCP server version is 1.9.0 with both off, 1.10.0 with only SMS on, and 1.11.0 when voice tools are visible.
- Docs: /docs/thread-assignment.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Durable event consumers
- Scheduled agents can read Cooper events without a public webhook URL and without storing a cursor.
- POST /api/v1/event-consumers creates a consumer for a client_id of 1 to 64 characters (letters, digits, and .
- _ : -).
- The same client_id returns the existing consumer with HTTP 200 and does not move its cursor.
- A new consumer is HTTP 201.
- start is now (the default), oldest, or an ISO-8601 timestamp, and it applies only when the consumer is created.
- types is an optional subset of the webhook event types.
- inbox_id pins the consumer to one inbox (an id or an address).
- A later call that asks for different types or a different inbox returns HTTP 409 consumer_conflict and leaves the consumer unchanged.
- Filters are not edited in place.
- Delete the consumer and create it again to change them.
- GET /api/v1/event-consumers lists them.
- GET and DELETE /api/v1/event-consumers/{id} accept the evcon_ id or the client_id.
- GET /api/v1/event-consumers/{id}/events returns events strictly after the committed cursor, oldest first, in the same shape as GET /api/v1/events.
- limit is 1 to 100 and defaults to 50.
- wait is 0 to 25 seconds, the same cap as GET /api/v1/events.
- There is no separate requests-per-minute cap.
- The response is {object:"list", data, commit_cursor, has_more, events_may_have_expired, consumer}.
- Reading does not advance the cursor.
- POST /api/v1/event-consumers/{id}/commit with {cursor} advances the committed cursor.
- An older cursor is a no-op and the response keeps the current cursor.
- The update compares created_at and id in one statement, so two workers cannot move the cursor backwards.
- A cursor that is not an evc1 cursor is HTTP 400 invalid_cursor.
- POST /api/v1/event-consumers/{id}/reset with {start} moves the cursor to now, oldest, or an ISO-8601 time, including backwards.
- The daily cron deletes events older than 7 days.
- When the committed cursor is older than that window, events_may_have_expired is true.
- An account can store at most 50 consumers.
- The next create returns HTTP 409 consumer_limit.
- That cap is a technical limit, not a plan limit.
- Every event-consumer route requires message_read, the same permission as GET /api/v1/events.
- Create, list, poll, commit, reset, and delete all use message_read.
- A full-access key and an OAuth token can call them.
- An inbox-scoped key can only create, list, read, commit, reset, and delete consumers pinned to its inbox.
- A different inbox_id is HTTP 404 inbox_not_found.
- Another account's consumer is HTTP 404 consumer_not_found.
- Delivery is at least once until commit.
- If the process stops after a side effect and before commit, the next poll returns that event again, so dedupe by event id when the side effect can run twice.
- GET /api/v1/events, GET /api/v1/events/stream, webhooks, and MCP Events are unchanged.
- MCP adds cooper_poll_events, cooper_commit_events, cooper_list_event_consumers, and cooper_delete_event_consumer.
- The catalog is 75 tools when SMS and voice are off, 82 when only SMS is on, 76 when only voice is on, and 83 when both are on.
- MCP server version stays 1.8.0 with both off, 1.9.0 with only SMS on, and 1.10.0 when voice tools are visible.
- Docs: /docs/event-consumers.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Paid add-ons for extra inboxes, domains, and email
- Starter and Pro can buy extra inboxes, extra custom domains, and extra email.
- POST /api/v1/billing/addons accepts inboxes, domains, and email_packs.
- Each field is optional, at least one is required, and the number replaces the previous quantity, from 0 to 100.
- One extra inbox is $1 per month (lookup key cooper_overage_inbox_monthly).
- One extra custom domain is $1 per month (cooper_overage_domain_monthly).
- One email pack is $1 per month and adds 1,000 emails (cooper_overage_sends_1000_monthly).
- npm run stripe:setup creates those prices.
- An increase is invoiced immediately, and the cap rises only after Stripe confirms payment.
- A decrease is not credited.
- A quantity below live inboxes, domains, or emails already used returns HTTP 409 addon_below_usage.
- Email packs already used stay locked until the Stripe period ends, so a calendar-month rollover before renewal cannot remove them.
- Grandfathered accounts return HTTP 402 plan_limit_exceeded and are not charged.
- A past_due, unpaid, or incomplete subscription returns HTTP 402 subscription_not_current and buys nothing.
- The same payment and usage rules apply to POST /api/v1/billing/sms-segments and POST /api/v1/billing/voice-minutes.
- The caller's key is prefixed with the account id before Stripe sees it.
- Free returns HTTP 402 plan_limit_exceeded and buys nothing.
- An account with no Stripe subscription returns the same 402.
- A sub-account key returns HTTP 403 workspace_billing_forbidden.
- HTTP 402 addon_payment_failed means the invoice was not paid and the quantity was not saved.
- HTTP 503 stripe_not_configured means Stripe is unset.
- HTTP 503 stripe_price_missing means that price is absent.
- HTTP 503 usage_addon_failed means Stripe refused the change for another reason and that quantity was not saved.
- A 402 on a paid plan names POST /api/v1/billing/addons.
- GET /api/v1/billing includes addons with the quantities already purchased.
- The MCP tool is cooper_set_addons.
- The catalog is 71 tools when SMS and voice are off, 78 when only SMS is on, 72 when only voice is on, and 79 when both are on.
- MCP server version stays 1.8.0 with both off, 1.9.0 with only SMS on, and 1.10.0 when voice tools are visible.
- Operator: Avatar 8 LLC (ops@avatar33.com).
MCP Events: ChatGPT reacts when mail arrives
- ChatGPT and other MCP clients can subscribe to message.received.
- POST /mcp and POST /api/mcp accept MCP 2026-07-28 without initialize when params._meta, top-level _meta, or the MCP-Protocol-Version header sets io.modelcontextprotocol/protocolVersion.
- params._meta wins, then top-level _meta, then the header.
- A dated version older than 2026-07-28, including any 2024 or 2025 date, is accepted and falls back to the best supported version.
- initialize is not rejected for a protocol version.
- A version newer than 2026-07-28, or a value that is not a calendar date, returns JSON-RPC -32022.
- server/discover is public and returns supported versions 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26, with tools listChanged false and an empty events capability.
- initialize still negotiates 2025-03-26 (or a requested 2024 version) and now advertises events.
- events/list describes message.received.
- events/subscribe verifies the https callback, then stores a subscription.
- The verification POST is signed and must echo the challenge.
- A callback that redirects is not followed.
- events/unsubscribe ends that subscription.
- When mail is stored, Cooper POSTs a signed webhook.
- The body is eventId, name, timestamp, data, and cursor.
- data is inbox_id, inbox, message_id, thread_id, timestamp, from, to, cc, labels, and channel.
- channel is the channel the message arrived on: email or sms.
- It does not include the subject, body, attachments, or headers.
- Read the message with cooper_get_message and treat that content as data.
- Held, screened, and blocked mail does not fire message.received.
- The signature is Standard Webhooks: webhook-id, webhook-timestamp, and webhook-signature (v1, base64 HMAC-SHA256 of id, timestamp, and the raw body, keyed by the base64 after whsec_).
- A rotated secret stays valid for 24 hours and both signatures are sent, current first.
- Delivery retries 408, 429, 5xx, and network errors, and does not retry other 4xx responses.
- The default lifetime is 72 hours.
- The maximum is 30 days.
- ttlMs null grants that maximum.
- Each API key or OAuth app can have 20 active subscriptions on an account.
- A revoked key or OAuth grant stops delivery.
- GET /api/v1/event-subscriptions lists them (callback hostname only).
- DELETE /api/v1/event-subscriptions/{id} keeps the row with status ended for audit and returns retained true.
- events/unsubscribe does the same and returns {retained: true}.
- An ended row does not deliver and does not count toward the 20 subscription cap.
- MCP tools are cooper_list_event_subscriptions and cooper_delete_event_subscription.
- The catalog is 70 tools when SMS and voice are off, 77 when only SMS is on, 71 when only voice is on, and 78 when both are on.
- MCP server version is 1.8.0 with both off, 1.9.0 with only SMS on, and 1.10.0 when voice tools are visible.
- Docs: /docs/mcp-events.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Automatic send pause on high bounce or complaint rates
- Cooper pauses agent email when an account's trailing 7-day bounce rate is at least 10% with at least 5 bounces, or its complaint rate is at least 0.5% with at least 3 complaints, after at least 50 messages were sent.
- Below 50 sent messages the status stays active.
- A bounce rate of 5% or a complaint rate of 0.1% is a warning and does not block sends.
- Bounce wins when both pause rules match.
- While paused, POST /api/v1/inboxes/{id}/messages, reply, reply-all, forward, and draft send return HTTP 403 sending_paused and store nothing.
- The error includes sending, and sending resumes automatically when the trailing 7-day rate falls below the pause threshold.
- A scheduled draft stays unsent and its send_status is failed.
- An Idempotency-Key or client_id rejected this way is not a completed send, so the same key sends after the rate recovers.
- Receiving, reading, labels, draft create and edit, SMS, voice, and owner notification mail keep working.
- GET /api/v1/sending-status and the sending field on GET /api/v1/me return the status.
- MCP cooper_get_sending_status reads the same object.
- The catalog is 68 tools when SMS and voice are off, 75 when only SMS is on, 69 when only voice is on, and 76 when both are on.
- MCP server version stays 1.5.0 with both off.
- Events account.sending_paused and account.sending_resumed fire once each, with inbox_id null, to webhooks that are not filtered to specific inboxes.
- The daily cron reevaluates accounts even when nobody is sending.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Voice calls and voicemail
- An inbox phone number takes voicemail and can place calls.
- A caller hears a short greeting, then a recording of at most 120 seconds.
- The recording is stored as a message with channel voicemail, the caller number, the duration, the transcript, and the recording URL.
- message.received and GET /api/v1/inboxes/{id}/wait include that message.
- PATCH /api/v1/inboxes/{id}/phone-number sets voice_greeting and voice_max_seconds (15 to 300; empty uses the default greeting and 120 seconds).
- POST /api/v1/inboxes/{id}/calls places a call from that number.
- say is spoken with text-to-speech.
- mode say_and_record speaks, then records a reply as a voicemail.
- The MCP tool is cooper_place_call.
- Status callbacks store queued, ringing, completed, no-answer, or failed, and the duration in seconds.
- Recipients must be US or Canada numbers.
- Premium-rate numbers return HTTP 400 premium_rate_blocked.
- Other countries return HTTP 400 international_not_allowed.
- Each account can place at most 100 calls per UTC day (HTTP 409 daily_call_cap).
- Free has no voice minutes.
- Starter includes 30 minutes per active number each month.
- Pro includes 300 minutes, plus 30 for each active number past the 3 included numbers.
- Outbound calls past that allowance return HTTP 402 plan_limit_exceeded with upgrade_url.
- Inbound calls still record a voicemail, capped at 60 seconds.
- Extra minutes are $10 per 250, lookup key cooper_voice_250_monthly.
- npm run stripe:setup does not create that price.
- POST /api/v1/billing/voice-minutes sets the pack count from 0 to 100.
- That route returns HTTP 404 when voice billing is off, and HTTP 402 when the account has no Starter or Pro subscription.
- Reference pages are /docs/reference/place-call, /docs/reference/update-voice-settings, and /docs/reference/set-voice-minutes, and the same pages are markdown at the .md URL.
- The catalog stays at 67 tools when SMS and voice are off, 74 when only SMS is on, 68 when only voice is on, and 75 when both are on.
- MCP server version stays 1.5.0 with both off, 1.6.0 with only SMS on, and 1.7.0 when voice tools are visible.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Cooper CLI
- A shell CLI is served at /cli/cooper.mjs and /cli/cooper-cli.tgz.
- curl -fsSL https://cooperemail.com/cli/cooper.mjs -o cooper.mjs && node cooper.mjs help downloads the script.
- npx -y https://cooperemail.com/cli/cooper-cli.tgz help runs the same script from the tarball.
- The script is one file, uses Node 18 or newer, and calls the existing REST API.
- Commands are help, version, onboard, me, inboxes list, inboxes create, inboxes get, messages list, messages get, send, reply, wait, code, threads list, drafts create, drafts list, drafts send, and api.
- onboard --save writes the key to the credentials file with mode 0600.
- --api-key, COOPER_API_KEY, and that file are the key sources, in that order.
- --idempotency-key sends the Idempotency-Key header.
- JSON goes to stdout.
- An API error goes to stderr and exits 1.
- A usage error exits 2.
- A network error exits 3.
- HTTP 429 includes retry_after_seconds and resets_at when the API sends them.
- Docs are /docs/cli and /docs/cli.md.
- No new API routes.
- No new MCP tools.
- The catalog stays at 67 tools when SMS is off and 74 when SMS is on.
- MCP server version stays 1.5.0 with SMS off and 1.6.0 with SMS on.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Agent reference pages, quickstarts, and recipes
- Each HTTP endpoint has a reference page at /docs/reference with a request example, a response example, the error codes named for that route, and idempotency when the route uses it.
- The same page is markdown at /docs/reference/{id}.md.
- /docs/quickstarts shows curl, Python, TypeScript, and MCP for creating an inbox, sending, waiting for a code, webhooks, buying a number and receiving SMS, and approve-before-send.
- /docs/recipes matches the use cases on /use-cases.
- /llms-full.txt includes the full docs.
- /changelog.atom is the Atom feed.
- No new MCP tools.
- The catalog stays at 67 tools when SMS is off and 74 when SMS is on.
- MCP server version stays 1.5.0 with SMS off and 1.6.0 with SMS on.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Phone numbers described on the site
- The site describes a US phone number for an agent on the homepage, /phone, /use-cases, /pricing, and a curl on /docs.
- POST /api/v1/inboxes/{id}/phone-number buys the number.
- Inbound SMS is stored on the inbox.
- Each billable number is $3 per month.
- Pro includes 3 numbers.
- No new MCP tools.
- The catalog stays at 67 tools when SMS is off and 74 when SMS is on.
- MCP server version stays 1.5.0 with SMS off and 1.6.0 with SMS on.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Use cases by plan
- The use-case page at /use-cases and /use-cases.md lists what each plan is for.
- Free is a personal agent address, signup codes, and approve-before-send.
- Starter is a support or invoice inbox on your domain.
- Pro is an inbox per customer, agent fleets, and outbound across domains.
- No new MCP tools.
- The catalog stays at 67 tools when SMS is off and 74 when SMS is on.
- MCP server version stays 1.5.0 with SMS off and 1.6.0 with SMS on.
Paid phone numbers and SMS segment packs
- Paid plans can hold US local phone numbers when SMS is on for this deployment.
- POST /api/v1/inboxes/{id}/phone-number provisions a number.
- Free includes no numbers and returns HTTP 402 plan_limit_exceeded.
- Starter can hold up to 3 numbers.
- Pro includes 3 numbers and 1,500 segments and can hold up to 25.
- Each billable number is $3 per month and includes 100 segments.
- With COOPER_SMS_BILLING=stripe, Cooper adds that number to the Stripe subscription before it buys the number, and Stripe prorates the charge.
- Releasing the number lowers the quantity, which is also prorated.
- If Stripe refuses, nothing is bought and the call returns HTTP 503 sms_billing_failed.
- Without that setting, the provision response is a billing stub and this route does not call Stripe.
- npm run stripe:setup creates the phone-number price (cooper_phone_number_monthly) and the 500-segment price (cooper_sms_500_monthly).
- POST /api/v1/billing/sms-segments sets how many 500-segment packs are on the subscription, from 0 to 100, at $10 per pack per month.
- That route returns HTTP 404 when SMS billing is off, and HTTP 402 when the account has no Starter or Pro subscription.
- A grandfathered account is treated as Free for numbers unless it has a Starter or Pro subscription while SMS billing is on.
- A provisioned number can receive SMS.
- Account notification texts (a confirmation code, an approval-needed alert, and an unread-over-24-hours alert) are sent on Avatar 8 LLC's verified campaign.
- POST /api/v1/inboxes/{id}/sms from a customer number returns HTTP 409 outbound_not_registered.
- Cooper stores STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, and REVOKE as an opt-out for that number pair, and START, YES, or UNSTOP clears it.
- A Twilio delivery callback sets the message status to delivered, undelivered, or failed.
- delivery_events includes the numeric error code when Twilio sends one.
- No new MCP tools.
- The catalog stays at 67 tools when SMS is off and 74 when SMS is on.
- MCP server version stays 1.5.0 with SMS off and 1.6.0 with SMS on.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Custom-domain setup hints
- Each record on a custom domain now includes hint.
- hint is null when the record is valid or no specific mistake was found.
- Otherwise hint is an object with code, message, and found_at when the value was found on a different host.
- message is one short sentence describing what to change.
- Codes are duplicated_suffix, wrong_host, wrong_type, wrong_token, value_typo, multiple_spf, mx_priority, and other_provider_mx.
- The domain object includes warnings, which is an empty array when there is nothing to report.
- warnings includes existing_mail_provider when that hostname already has MX records that are not Cooper or Cloudflare Email Routing.
- The provider name is included when it is recognizable.
- The message says that pointing that hostname's MX at Cooper would move mail away from the existing provider and suggests a subdomain such as agents.example.com.
- POST /api/v1/domains fills warnings as a best effort and still creates the domain when DNS does not answer.
- POST /api/v1/domains/{id}/verify and the daily cron store hints and warnings in the existing records_status JSON.
- Older rows that omit those fields still parse, with hint null and warnings empty.
- Which records are valid, missing, or invalid is unchanged, and so are domain.verified, the 60 second verify limit, and plan limits.
- No new database columns.
- No new MCP tools.
- The catalog stays at 67 tools total.
- MCP server version stays 1.5.0.
Public rate limits stay enforced
- GET /api/v1/usernames/check still allows 30 requests per minute per IP.
- The next request returns HTTP 429 rate_limited with Retry-After, and the JSON error includes retry_after_seconds and resets_at.
- Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset.
- RateLimit-Reset is the number of seconds until that window ends, and on HTTP 429 it matches Retry-After.
- A username lookup that cannot be completed returns HTTP 503 username_check_unavailable with those same retry fields, instead of HTTP 500.
- The shared counter also guards owner sign-in, owner code checks, account recovery, owner confirmation email, SMS opt-in, and SMS confirmation codes.
- When that counter is slow or unavailable, the same limit is still enforced.
- If the limit cannot be checked, the response is HTTP 503 rate_limit_unavailable with Retry-After, retry_after_seconds, and resets_at.
- Owner sign-in still returns HTTP 202 with status accepted when the limit is reached, and does not send mail.
- No new MCP tools.
- The catalog stays at 67 tools total.
- MCP server version stays 1.5.0.
Webhook secret rotation
- POST /api/v1/webhooks/{id}/rotate-secret mints a new signing secret and returns it once.
- The previous secret stays valid for 24 hours.
- The response includes previous_secret_expires_at (ISO-8601) and previous_secret_active true.
- The previous secret value is not returned.
- GET and the list keep the current secret redacted, include previous_secret_expires_at only while that time is still in the future, and set previous_secret_active false after it.
- PATCH /api/v1/webhooks/{id} with a secret that differs from the current secret does the same 24 hour overlap.
- A webhook with no secret just stores the new one.
- Rotating again moves the current secret to previous_secret, drops the older previous secret, and resets the window to 24 hours from that call.
- The route uses webhook_write, the same permission as PATCH.
- During the window each delivery sends x-cooper-signature as sha256=<hex>,sha256=<hex> and x-cooper-signature-v2 as v1=<hex>,v1=<hex>, current secret first.
- Verify by splitting the header on the comma and accepting the delivery when any segment matches.
- After expiry only the current secret is signed, and the stored previous secret is cleared on the next delivery or update.
- A hook with no previous secret signs exactly as before.
- The webhooks table gains previous_secret and previous_secret_expires_at.
- There is no new index.
- MCP adds cooper_rotate_webhook_secret, 67 tools total.
- MCP server version stays 1.5.0.
Connected apps: list and revoke OAuth access
- GET /api/v1/oauth/grants lists the OAuth apps that currently hold access on this account.
- One row is one client.
- The row includes the client id, client name, redirect hostnames, scope, resource, connected_at, last_refreshed_at, and how many tokens are still usable.
- An access token that has expired still counts while its refresh token can be used.
- GET /api/v1/oauth/grants/{client_id} returns that one row.
- DELETE /api/v1/oauth/grants/{client_id} removes every token and every unused authorization code for that client on this account, in one transaction.
- The app registration stays, so it can connect again.
- Those tokens stop working immediately, and their refresh tokens fail at /oauth/token.
- Other apps and API keys stay valid.
- Another account's client returns HTTP 404 oauth_grant_not_found.
- Listing needs key_read.
- Revoking needs key_write.
- An inbox-scoped key receives HTTP 403 permission_denied.
- MCP adds cooper_list_oauth_grants and cooper_revoke_oauth_grant, 66 tools total.
- MCP server version stays 1.5.0.
- HTTP 429 rate_limited and HTTP 503 responses that send Retry-After now also include retry_after_seconds and resets_at in the JSON error body.
- Both match that header.
- They are omitted when no retry time is known.
Draft-only API key permissions
- API keys can include draft_write and draft_send.
- draft_write creates, edits, and deletes drafts and does not send mail.
- draft_send sends a draft and does not create, edit, or delete drafts.
- POST and PATCH /api/v1/inboxes/{id}/drafts accept message_send or draft_write.
- DELETE accepts message_delete or message_send or draft_write.
- POST /api/v1/inboxes/{id}/drafts/{draftId}/send accepts message_send or draft_send.
- GET drafts stays on message_read.
- POST /api/v1/inboxes/{id}/messages, reply, reply-all, forward, inbound inject, SMS send, and agent-to-agent send stay on message_send.
- A full-access key and a key that already has message_send keep creating, editing, and sending drafts.
- A key that has message_delete can still delete drafts.
- MCP cooper_create_draft, cooper_update_draft, cooper_delete_draft, and cooper_send_draft honor the same rules.
- A key with only draft_write cannot send.
- No new MCP tools.
- The catalog stays at 64 tools total.
- MCP server version stays 1.5.0.
Batch update message labels
- POST /api/v1/inboxes/{id}/messages/batch-update adds or removes the same labels on 1 to 50 messages in one inbox.
- message_ids must be unique.
- An empty list is HTTP 400 missing_message_ids.
- Duplicates are HTTP 400 duplicate_message_ids.
- More than 50 ids is HTTP 400 too_many_ids.
- add_labels or remove_labels must include at least one label, or the call is HTTP 400 missing_labels.
- read and unread can change.
- Other system labels return protected_label, invalid_label, or label_conflict, the same as PATCH on one message.
- Ids that are not in this inbox are left out.
- The messages that are in this inbox all update, or none do.
- The response is {object:"list", limit, count, data} with the same message JSON as a single get, in request order.
- limit is the number of ids sent.
- count is how many updated.
- A held message can be labeled, the held label stays, and the body stays withheld.
- A paused inbox still accepts the call.
- An inbox-scoped key for another inbox is HTTP 404 inbox_not_found.
- MCP adds cooper_update_messages, 64 tools total.
- MCP server version stays 1.5.0.
- GET /rss.xml returns HTTP 301 to /blog/rss.xml and keeps the query string.
- The weekly product note counts a webhook only when enabled is 1, so a disabled hook no longer hides the automatic-checks tip.
Simpler concise owner email
- The default concise owner email is now a short note: one headline, then at most a small table or a few bullets, then one button when you need to act.
- Subjects are the one fact, such as founder-agent: 1 update, or Approve: Quote to a recipient.
- Concise digests omit a zero counts row, idle inboxes, deploy ids, commit ids, the new-this-week line, and unread counts.
- An account at its plan limit gets one upgrade line, at most once a week.
- Detailed keeps the fuller digest, the full draft, and the 80 percent limit line.
- Agents should write owner updates as one plain sentence without deploy ids or internal ids.
- No new MCP tools.
- The catalog stays at 63 tools.
- MCP server version stays 1.5.0.
Shorter owner email and an email style setting
- Every email Cooper sends to a human owner now leads with the answer.
- The daily digest is a table of inbox, new, sent, and needs approval, with the latest updates below it.
- Approval requests show the recipient, subject, and a quoted preview above the Approve and Reject buttons.
- Progress updates, owner confirmations, recovery, and send-mode and delete confirmations use the same layout and keep a plain-text part.
- Subjects carry the key fact, for example Daily updates: 3 updates, 1 needs input, 2 awaiting approval.
- style is concise (the default), detailed, or casual, with an optional note of at most 280 characters for the agent.
- PATCH /api/v1/inboxes/{id}/owners/{ownerId} with email_style and email_style_note sets one owner.
- PATCH /api/v1/me with owner_email_style and owner_email_style_note sets the account default and needs an unscoped key with owner_manage.
- Each owner email has a Change email style link.
- That page uses the owner's token from the email, rejects an API key, and needs the button on the page.
- A style the owner picks there cannot be overridden through the API (HTTP 409 owner_style_locked).
- The link token is redacted from the copy stored in the agent inbox.
- MCP adds cooper_get_owner_preferences (read-only) and cooper_set_owner_preferences, 63 tools total.
- MCP server version 1.5.0.
Phone numbers that receive SMS
- US local numbers on this deployment receive SMS.
- POST /api/v1/inboxes/{id}/phone-number provisions a US local number.
- Free includes no numbers.
- Starter can add up to 3 numbers at $3 per month, and each number includes 100 SMS segments.
- Pro includes 3 numbers and 1,500 segments, and caps at 25 numbers.
- Each number past the 3 included ones is $3 per month and adds 100 segments.
- Extra segments are $10 per 500.
- GET and DELETE /api/v1/inboxes/{id}/phone-number read and release that number.
- GET /api/v1/phone-numbers lists the account's numbers.
- GET /api/v1/phone-numbers/available searches US local numbers.
- POST /api/v1/inboxes/{id}/sms returns HTTP 409 outbound_not_registered.
- A recipient who replied STOP returns HTTP 409 recipient_opted_out.
- The first message to a recipient adds an opt-out footer.
- SHAFT content and URL shorteners are rejected.
- A body over 320 characters returns HTTP 400 body_too_long.
- An account can provision at most 3 numbers per 24 hours, and the same account waits 30 days before provisioning an E.164 it released.
- A verified owner is required.
- Owners who opted in at /sms can confirm a phone with a code from the toll-free number.
- A verified phone receives an approval-needed alert and an unread-over-24-hours alert.
- Those alerts count toward the segment allowance, contain no action link, and do not block the email when SMS fails.
- HELP and STOP are answered by the Messaging Service, and STOP is mirrored into sms_suppressions.
- MCP lists cooper_provision_phone_number, cooper_get_phone_number, cooper_release_phone_number, cooper_send_sms, cooper_list_sms_threads, cooper_get_sms_thread, and cooper_wait_for_sms when SMS is on for that account, and initialize reports version 1.3.0.
- With SMS off, the catalog stays at 60 tools and version 1.2.2.
- Stripe price ids for the phone number and the 500-segment pack are environment stubs and are not created by stripe:setup.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Wait for a verification code
- GET /api/v1/inboxes/{id}/wait-for-code holds up to 55 seconds until an inbound message with a one-time code is stored, then returns the code, every candidate code in that message, and the message id.
- after defaults to 5 minutes before the call, and from and subject narrow the match.
- The body is not returned and nothing is marked read.
- MCP adds cooper_wait_for_code (read-only), 61 tools total.
- MCP server version 1.4.0.
Recommended owner email and account recovery
- Owner email stays optional.
- POST /api/v1/onboard, inbox create, cooper_onboard, and cooper_create_inbox include next_steps.recommended.
- The line suggests adding a human owner email.
- GET /api/v1/me and cooper_whoami add owner_recommended when the account has no verified owner.
- That hint names POST /api/v1/inboxes/{id}/owners, the onboard owner_email field, and the existing 50 percent Free send increase for a verified external owner.
- The weekly product note adds one product-tip line for an account with no verified owner.
- POST /api/v1/recover with {address} is public.
- It always returns HTTP 202 with the same body, so an address that is not an inbox looks the same as one that is.
- The lookup and the email run after that response.
- The route is limited to 5 requests per hour per IP and 3 per day per address in the shared public rate window.
- When the address is an inbox, Cooper emails each verified external owner a single-use link that expires in 2 hours.
- Owner addresses are stored in lowercase with a trailing dot removed.
- An address at cooperemail.com or any subdomain is refused.
- Recovery also skips an address that is an inbox on any account, and an address on any domain in the domains table, including a pending domain.
- A pending owner is not emailed.
- If there is no verified external owner, nothing is sent.
- GET /api/v1/recover/confirm shows a confirm page.
- POST on that page revokes the account API keys and the account's OAuth access and refresh tokens in the same transaction, and shows a new full-access key once.
- The page includes a nonce that expires within minutes, and a POST without that nonce does not mint a key.
- Owner confirmation by token and draft approval use the same nonce.
- A 6-digit owner code does not.
- The key is not in the email.
- The email is not stored in an agent inbox.
- The recovery email uses the same From as an owner confirmation, the inbox address, and sets Reply-To only through the provider reply_to field.
- Cloudflare Email Sending drops Reply-To, Message-ID, and its other rejected headers before the request.
- Reply-To is noreply@cooperemail.com.
- GET /api/v1/owners/confirm writes a page nonce only for a live confirmation token.
- The daily digest cron deletes expired confirm nonces.
- A recovery, owner-confirm, or draft-approval token is redacted and marked used when it arrives in inbound mail, including when it is percent-encoded inside another URL or written in quoted-printable, plain text, or HTML.
- Opening the link does not revoke keys.
- A second POST does not show the key again.
- An API key cannot submit the link.
- A display name in From or To that contains a comma, a quotation mark, an angle bracket, a semicolon, or a character outside ASCII is sent as an RFC 5322 quoted-string, or as an RFC 2047 encoded-word when the name is not ASCII.
- Cloudflare Email Sending and Resend both receive that form.
- No new MCP tools.
- The catalog stays at 60 tools total.
Inboxes on your own domain
- Inboxes on your own domain are included on Starter (15 custom domains) and Pro (200 custom domains).
- Free includes 0 custom domains and returns HTTP 402 plan_limit_exceeded.
- POST /api/v1/domains looks up the hostname on the operator Cloudflare account and does not create a zone.
- When that zone is already there, Cooper writes the records and dns.mode is automatic.
- Any other zone stays manual: publish the routing MX hosts, TXT SPF v=spf1 include:_spf.mx.cloudflare.net ~all, the routing DKIM TXT, the cf-bounce MX, SPF, and DKIM records, a DMARC TXT (an existing DMARC record is left as it is), and the verify TXT.
- mail.receiving stays false until those receiving records check out and the catch-all is live.
- Receiving goes live within a few minutes, and status_detail says so while you wait.
- POST /api/v1/inboxes with domain creates username@domain once mail.receiving is true.
- DELETE /api/v1/domains/{id} puts back the previous catch-all, deletes only the DNS records Cooper created, turns Email Routing off only if Cooper turned it on, and removes the sending domain only if Cooper created it.
- A cleanup that does not finish keeps the row with status cleanup_failed and deleted false so a later delete can finish it.
- Inbound message JSON includes auth.spf, auth.dkim, and auth.dmarc.
- SPF is the smtp.mailfrom result, then a plain spf= result.
- smtp.helo is used only when both are absent.
- No new MCP tools.
- The catalog stays at 60 tools total.
Lifecycle notes in the agent inbox
- Cooper writes a weekly product note into each eligible account's oldest active inbox from Cooper <hello@cooperemail.com>.
- hello is reserved and POST /api/v1/inboxes, POST /api/v1/onboard, and every other inbox create return HTTP 400 reserved_username.
- The note is stored as inbound mail with the labels cooper-system and newsletter.
- It does not go out over SMTP and it does not increment monthly sends or metrics usage.
- message.received still fires, and the label is how an agent filters it.
- At most one note per account per week is stored in lifecycle_sends with account_id, campaign_key, and sent_at, and a unique constraint on account_id plus campaign_key.
- The daily cron GET /api/v1/internal/digests/flush sends on Monday UTC only when COOPER_LIFECYCLE_EMAILS is on.
- One failed account is logged and the run continues.
- The campaign is marked done when that Monday run finishes.
- An inbox needs activity in the last 30 days.
- Paused, expired, and deleted inboxes are skipped.
- Operator test accounts are skipped unless COOPER_LIFECYCLE_PREVIEW lists the account id or the inbox email.
- PATCH /api/v1/me accepts lifecycle_emails on or off.
- cooper_whoami accepts the same flag.
- The catalog stays at 60 tools.
- GET /api/v1/lifecycle/unsubscribe shows a confirm page.
- POST on that path turns product notes off.
- A request that only GETs the link does not opt the account out.
- List-Unsubscribe and List-Unsubscribe-Post are stored on the message.
- The note is plain text and simple HTML, labelled From the Cooper team, product update, no action required, and inbound screening leaves it clean.
- GET /api/v1/me and cooper_whoami add notices when usage is at 80 percent of inboxes, monthly sends, or custom domains, and whats_new with the latest changelog titles and URLs.
- A successful send, inbox create, or domain add includes notices.
- The daily owner digest adds one line at that same threshold, with the upgrade URL, and one new-this-week changelog line.
- Owner unsubscribe is unchanged.
- Stripe Checkout does not update the customer email.
- When checkout includes an email and the Stripe customer has none, Cooper sets that email on the customer before creating the session and leaves an existing email unchanged.
- billing_customers keeps the Stripe customer id.
- GET /api/v1/billing reads stripe.billing_email from Stripe and does not store that address.
- That field is returned only to an unscoped full-access key of the account that owns the Stripe customer.
- POST /api/v1/onboard and cooper_onboard accept optional owner_email and send the existing owner confirmation.
- The address stays pending until the human confirms.
- A verified owner on an external domain on the Free plan raises the monthly send limit by 50 percent.
- An address at cooperemail.com, on a verified custom domain hosted on Cooper, or already used by an inbox on the same account does not count.
- Prices are unchanged.
- Owner confirmation email is limited to 5 per hour per IP and 3 per day per address.
- GET /api/v1/admin/lifecycle is operator-only and previews the weekly note and the eligible account count without sending.
- POST /api/v1/admin/lifecycle with inbox_id delivers one preview note to an inbox listed in COOPER_LIFECYCLE_PREVIEW.
- That preview ignores the kill switch and is idempotent for the week.
- POST /api/v1/inboxes/{id}/notify registers a message.received webhook for that inbox, signed the same way as other webhooks.
- A second call with the same inbox updates the URL and returns the secret only the first time.
- POST /api/v1/inboxes and cooper_create_inbox accept notify_url and do that registration in the same call.
- Webhook URLs must be a public http or https address.
- Localhost, a private IP, benchmarking, multicast, reserved, NAT64, and 6to4 addresses, and a delivery redirect are rejected.
- Delivery connects to the address that was checked and keeps the original Host header.
- GET /api/v1/inboxes/{id}/wait holds until unread mail arrives, at most 55 seconds, and returns immediately when unread mail is already stored.
- A key can hold at most 5 of those waits at once.
- The next one returns HTTP 429 rate_limited.
- cooper_list_messages accepts wait_seconds.
- POST /api/v1/onboard and inbox create include next_steps.
- The guide is /docs/stay-in-sync.
- The daily owner digest names an inbox with unread mail older than 24 hours.
- The weekly product note uses a set up automatic checks how-to when that inbox has unread mail older than 24 hours and the account has no webhook.
- No new MCP tools.
- The catalog stays at 60 tools total.
- Operator: Avatar 8 LLC (ops@avatar33.com).
Grok Bot inbox and a username check
- Grok Bot, Grok Build, and the Grok API can use a Cooper inbox from /integrations/grokbot, with the same page as markdown at /integrations/grokbot.md.
- The page documents the hosted MCP URL https://cooperemail.com/mcp, OAuth 2.1 with PKCE, Authorization Bearer, and the x-api-key header, plus public POST /api/v1/onboard.
- GET /api/v1/usernames/check?name= needs no API key.
- It returns name, normalized, available, an optional reason, and up to 5 suggestions.
- A suggestion passes the same username rules as inbox create, is not reserved, and is not already in the inboxes table.
- The route allows 30 requests per 60 seconds per IP and then returns HTTP 429 rate_limited with Retry-After.
- The body does not include an account id or who holds a name.
- cooper_onboard and cooper_create_inbox accept check_username true and return that same object without creating an inbox.
- No new MCP tools.
- The catalog stays at 60 tools total.
Approval requires an owner and scheduled sends flush on traffic
- PATCH /api/v1/inboxes/{id} with send_mode approval returns HTTP 409 owner_required when that inbox has no verified owner, and send_mode stays direct.
- PATCH /api/v1/inboxes/batch and cooper_update_inbox use the same check.
- An inbox that was put in approval and has never had a verified owner can be set back to direct by the API key, and that call returns HTTP 200.
- DELETE of a verified owner on an approval inbox returns HTTP 409 owner_required.
- An owner who unsubscribed still blocks that switch, and a username pinned by an owner-confirmed delete stays in approval until a verified owner confirms.
- DELETE /api/v1/workspaces/{id} with delete_inboxes returns HTTP 409 owner_required when any inbox in the workspace is in approval mode.
- When a verified owner exists, leaving approval still returns HTTP 202 and waits for the owner link.
- Opening an expired Approve link sends at most one replacement email per draft every 10 minutes.
- A conditional update claims that resend, so ten simultaneous opens send one email.
- A draft is capped at 3 replacement emails per day.
- The copy stored in the agent inbox still has the new link removed.
- Due scheduled drafts are also flushed during normal API traffic, at most once every 30 seconds on each instance, using the same row claim as /api/v1/internal/drafts/flush.
- That flush does not delay GET /api/v1/health or the API response.
- The inbound worker schedule calls that flush and /api/v1/internal/digests/flush with Authorization Bearer CRON_SECRET.
- No new MCP tools.
- The catalog stays at 60 tools total.
Reserved mailbox names and a fresh approval link
- POST /api/v1/inboxes, POST /api/v1/onboard, and every other inbox create reject mailer-daemon, mailerdaemon, bounce, bounces, daemon, nobody, noc, info, billing, and help.
- The check is the same lowercase compare already used for noreply, hostmaster, webmaster, root, and ops, so Mailer-Daemon is reserved too.
- The response is HTTP 400 reserved_username.
- Addresses already stored are left as they are.
- When an owner replies to an approval email and then opens Approve, the page says this link expired and a new approval email was sent.
- That replacement goes to the verified owner.
- The copy saved in the agent inbox has the new link removed.
- Opening the old link again does not send another email.
- A cold start that finds the database locked retries the owner-notice redaction.
- If another start already recorded owner_notice_secret_redaction, this start skips it.
- A failed start does not stick, so the next request tries again.
- No new MCP tools.
- The catalog stays at 60 tools total.
Quoted owner replies do not keep action links
- Approval, leave-approval, inbox-delete, and owner-confirm emails set Reply-To to noreply@cooperemail.com, which is not an agent inbox.
- A reply to those messages does not arrive in the agent inbox.
- Progress notes, digests, and task replies still set Reply-To to the agent inbox so an owner can answer the agent.
- Every stored inbound message redacts Cooper action links for owners/confirm, owners/unsubscribe, drafts/approve, drafts/reject, inboxes/send-mode, and inboxes/delete, and it redacts a confirmation code, in the text, html, extracted text, preview, headers, raw message, attachment text, and search index.
- A password-reset link on another site is left as the sender wrote it.
- A token that appears in inbound mail is marked used, so a later POST of that quoted token does not approve, reject, confirm, or delete.
- The decision itself is single-use: the first POST claims the token, and a second POST does not apply it again.
- The one-time schema_migrations pass owner_notice_secret_redaction also redacts inbound rows that were already stored.
- Concurrent startups claim that marker with one insert, and only the startup that inserts the row rotates unsubscribe tokens.
- No new MCP tools.
- The catalog stays at 60 tools total.
Stored owner mail is redacted once
- Messages already stored in an agent inbox with the labels owner-confirm, owner-update, or owner-digest are redacted once on startup.
- Confirm links, confirmation codes, and unsubscribe links are removed from the saved text, html, preview, headers, raw message, and attachment text.
- Search rows for those messages are rebuilt from the redacted text.
- Event payloads and webhook delivery payloads are redacted only when they contain an owner confirm, unsubscribe, approve, reject, or inbox action link.
- Outstanding owner confirmation tokens and codes are cleared, and a pending owner can be registered again to receive a new confirmation email.
- Unsubscribe tokens already issued are replaced, so an old link stops working.
- New owner mail still includes a one-click unsubscribe link that uses the replacement token.
- The pass is recorded in schema_migrations.
- A later startup sees that row and skips the pass.
- No new MCP tools.
- The catalog stays at 60 tools total.
Owner action links stay out of the agent inbox
- Owner mail stored in the agent inbox no longer includes action tokens.
- Approve, reject, confirm, cancel, unsubscribe, and owner confirmation codes are stripped from the saved text, html, preview, and headers before insert.
- The owner still receives the real link by email.
- An API key on POST /api/v1/drafts/approve, POST /api/v1/drafts/reject, POST /api/v1/inboxes/send-mode/confirm, POST /api/v1/inboxes/send-mode/cancel, POST /api/v1/inboxes/delete/confirm, and the owner-confirm or unsubscribe link is rejected.
- The 6-digit owner code still works when a human reads it from their own email and gives it to the agent.
- PATCH /api/v1/inboxes/batch cannot set send_mode to direct on an approval inbox.
- Every leave goes through the owner confirm link, including that shadow route.
- DELETE of an approval inbox returns HTTP 202 until the owner confirms, and recreating the same username on that account stays in approval mode.
- The confirmation email and the unsubscribe link on progress mail and digests were already stored in the agent inbox, and those copies are now redacted too.
- No new MCP tools.
- The catalog stays at 60 tools total.
Owner approval stays bound to the draft
- Changing to, cc, bcc, reply_to, subject, text, html, or attachments on a pending, approved, or rejected draft sets approval_status back to pending and emails verified owners again.
- Cooper stores a hash of the approved recipients, subject, body, attachments, and reply target, and checks that hash when the draft is claimed or sent.
- A mismatch is not sent, and the draft returns to pending.
- Labels and send_at do not change the hash.
- PATCH send_mode from approval to direct emails verified owners and keeps send_mode approval until they confirm with POST /api/v1/inboxes/send-mode/confirm.
- Entering approval mode still applies immediately.
- A draft scheduled while send_mode was direct is not sent after approval mode is on unless a verified owner approved that exact content.
- POST /api/v1/inboxes/{id}/messages, reply, reply-all, forward, and draft send re-check send_mode and the approval hash, including MCP.
- An Idempotency-Key replay returns the stored result and does not send a second copy.
- GET /api/v1/drafts/approve and GET /api/v1/drafts/reject show a confirm page.
- POST on those paths records the decision.
- Opening the link does not approve or reject.
- No new MCP tools.
- The catalog stays at 60 tools total.
Drafts, owner approval, and scheduled send
- POST and GET /api/v1/inboxes/{id}/drafts create and list drafts.
- GET, PATCH, and DELETE /api/v1/inboxes/{id}/drafts/{draftId} read, update, and delete one draft.
- POST /api/v1/inboxes/{id}/drafts/{draftId}/send sends it.
- GET /api/v1/drafts lists drafts on the account.
- GET /api/v1/inboxes/{id}/drafts/{draftId}/attachments/{attId} downloads a file.
- Fields are to, cc, bcc, reply_to, subject, text, html, attachments, and labels.
- in_reply_to or forward_of derives the subject, threading, and recipients from that message with the same reply and forward rules.
- A held source returns HTTP 409 message_held.
- send_at is an ISO timestamp that sets the scheduled label and send_status to scheduled.
- PATCH send_at null removes the schedule.
- DELETE cancels a scheduled send.
- A draft whose send_status is sending returns HTTP 409 draft_sending.
- A sent draft becomes a message and the draft is deleted.
- Inbox send_mode is direct or approval, and the default is direct.
- In approval mode, POST /api/v1/inboxes/{id}/messages and the reply, reply-all, and forward routes create a pending draft and email verified owners Approve and Reject links.
- Webhooks are draft.created, draft.approved, draft.rejected, and draft.sent.
- New MCP tools cooper_create_draft, cooper_get_draft, cooper_list_drafts, cooper_update_draft, cooper_delete_draft, and cooper_send_draft (60 tools total).
- Due drafts are sent by a Vercel cron every minute and by the inbound worker scheduled handler.
- Both call /api/v1/internal/drafts/flush, and a row-level claim keeps a draft from sending twice.
- Allow and block lists and the suppression list still apply.
- Idempotency-Key follows the same 24 hour rules.
- The drafts table adds columns before its indexes.
Outbound attachment content types
- POST /api/v1/inboxes/{id}/messages stores an attachment content_type that contains NUL or another control character as application/octet-stream.
- Reply, reply-all, forward, and task reply store that same type.
- Message JSON reports the stored content_type.
- GET /api/v1/inboxes/{id}/messages/{msgId}/attachments/{attId} and GET /api/v1/inboxes/{id}/threads/{threadId}/attachments/{attId} serve a content type that contains a control character as application/octet-stream.
- A comma in a content type is still served as application/octet-stream.
- No new MCP tools (54 tools total).
Inbox limits hold under parallel creates
- POST /api/v1/inboxes, POST /api/v1/inboxes/batch, and POST /api/v1/onboard apply the workspace inbox quota and the parent plan limit in the same write as the insert.
- Parallel creates on one account, or across a parent and its sub-accounts, cannot leave the family with more inboxes than the plan allows.
- Calls past that limit return HTTP 402 plan_limit_exceeded.
- A batch that would exceed the workspace quota or the plan returns HTTP 402 and creates no inboxes.
- workspace_quota_exceeded still counts only that sub-account.
- The same client_id still returns the original inbox and does not take another slot.
- No new MCP tools (54 tools total).
Safer attachment downloads
- GET /api/v1/inboxes/{id}/messages/{msgId}/attachments/{attId} and GET /api/v1/inboxes/{id}/threads/{threadId}/attachments/{attId} return the same bytes as before.
- Content-Disposition is inline only when the stored disposition is inline and the content type is image/png, image/jpeg, image/gif, image/webp, image/avif, audio/*, or video/*.
- Every other type is attachment, including image/svg+xml, text/html, application/xhtml+xml, text/xml, application/xml, application/javascript, and any unknown type.
- Those html, xhtml, svg, xml, and javascript types are served with content-type application/octet-stream.
- Message JSON still reports the stored content_type.
- ?download=1 forces attachment.
- GET /api/v1/inboxes/{id}/messages/{msgId}/raw stays message/rfc822 with content-disposition attachment and filename {msgId}.eml.
- GET /api/v1/inboxes/{id}/messages/{msgId}/attachments/{attId}/text stays text/plain; charset=utf-8 with content-disposition attachment.
- All four responses set X-Content-Type-Options to nosniff, Content-Security-Policy to default-src 'none'; sandbox; frame-ancestors 'none', X-Frame-Options to DENY, and Referrer-Policy to no-referrer.
- Cache-Control stays private.
- There is no Cross-Origin-Resource-Policy header.
- Filenames drop quotes, carriage returns, line feeds, other control characters, and path separators.
- A filename that is not ASCII also sends filename* as RFC 5987 UTF-8.
- URLs and status codes are unchanged.
Manage workspaces
- GET /api/v1/workspaces/{id} returns one sub-account: id, name, inbox_quota, inboxes_used, account_id, api_key_prefix, and created_at.
- The API key secret is not returned.
- Another parent's workspace returns HTTP 404 workspace_not_found.
- PATCH /api/v1/workspaces/{id} accepts name and inbox_quota.
- An inbox_quota below the number of live inboxes returns HTTP 409 quota_below_usage and changes nothing.
- Expired inboxes do not count toward that check.
- DELETE /api/v1/workspaces/{id} removes an empty workspace.
- When it still has inboxes, the call returns HTTP 409 workspace_not_empty unless delete_inboxes=true.
- That flag deletes the inboxes through the same path as inbox delete, including messages, attachments, owners, and tasks, then removes the workspace API keys, OAuth tokens, webhooks, domains, and the child account.
- The response is id, deleted true, and inboxes_deleted.
- The child key then returns HTTP 401.
- Parent plan usage no longer counts that sub-account.
- GET /api/v1/workspaces/{id}/inboxes lists that sub-account's inboxes in the same shape as GET /api/v1/inboxes.
- DELETE /api/v1/workspaces/{id}/inboxes/{inboxId} removes one of those inboxes.
- inboxId accepts an inbox id, username, or email on that workspace.
- An inbox on another workspace returns HTTP 404 inbox_not_found.
- A sub-account key calling any of these returns HTTP 403 permission_denied.
- An inbox-scoped key returns HTTP 403 permission_denied.
- A workspace cannot read another workspace's mail, events, threads, search, webhooks, or metrics.
- Held message bodies stay withheld until release, and a suppressed address still cannot be mailed.
- New MCP tools cooper_get_workspace, cooper_update_workspace, and cooper_delete_workspace (54 tools total).
- The messages body_bytes fill runs once.
- A schema_migrations row records that it finished, so a later start does not scan the messages table again.
Metrics API
- GET /api/v1/metrics/events returns counts in UTC hour or day buckets.
- types is a comma-separated list of message.received, message.sent, message.bounced, and message.complained.
- received and sent count messages.direction inbound and outbound.
- bounced and complained count messages whose labels include those names, and a missing label is zero.
- period defaults to day.
- start and end default to the last 30 days and must be ISO-8601.
- A range longer than 90 days, or a start that is not before end, returns HTTP 400 invalid_range.
- A bad timestamp returns HTTP 400 invalid_date.
- A bad period returns HTTP 400 invalid_period.
- An unknown type returns HTTP 400 invalid_type.
- GET /api/v1/metrics/usage returns inbox_count, message_count, thread_count, and storage_bytes.
- storage_bytes is the UTF-8 byte length of text plus html, plus attachment size_bytes.
- An inbox id, or an inbox-scoped key, omits domain_count and workspace_count.
- An account key also gets domain_count and workspace_count for this account only.
- GET /api/v1/metrics/rates returns sent, bounced, complained, bounce_rate, and complaint_rate for the same time window.
- Rates are zero when nothing was sent.
- A sub-account sees only its own mail, inboxes, domains, and workspaces.
- An inbox-scoped key sees only that inbox.
- Another account's inbox, or a different inbox on a scoped key, returns HTTP 404 inbox_not_found.
- A key without message_read returns HTTP 403 permission_denied.
- Responses are counts only and never include a message body, including held mail.
- Queries always filter by this account and, for events and rates, by a start and end at most 90 days apart.
- The messages table gains body_bytes, then indexes for account and inbox time ranges, body bytes, and attachment sizes.
- GET /api/v1/stats is unchanged.
- New MCP tool cooper_get_metrics (51 tools total).
Raw .eml download and attachment text
- GET /api/v1/inboxes/{id}/messages/{msgId}/raw downloads the message as message/rfc822 with content-disposition attachment and filename {msgId}.eml.
- Inbound mail that includes a raw body is stored in the new message_raw table.
- When that raw body is 200,000 characters or longer Cooper stores only the first 200,000 characters, marks the row truncated, and the response sets x-cooper-raw-truncated to 1.
- Inbound mail stored without a raw body returns HTTP 404 raw_not_available.
- Outbound mail is rebuilt on demand from the stored fields: Date, From, To, Cc, Subject, Message-ID, In-Reply-To, References, a text and html body, and base64 attachments.
- A subject that is not ASCII is encoded with RFC 2047.
- The rebuilt response sets X-Cooper-Reconstructed to 1.
- GET /api/v1/inboxes/{id}/messages/{msgId}/attachments/{attId}/text returns text/plain for text, JSON, CSV, PDF text, DOCX, XLSX, and XLS.
- The input cap is 10 MB and a larger file returns HTTP 400 attachment_too_large.
- The output cap is 200,000 characters, and a longer result sets x-cooper-text-truncated to 1.
- An image-only PDF returns HTTP 200 with an empty body and x-cooper-text-empty set to 1.
- An unsupported type returns HTTP 415 text_extraction_unsupported.
- A DOCX or spreadsheet whose inflated bytes expand past 50 MB, or whose compression ratio is over 100, returns HTTP 400 attachment_too_large.
- The check counts the bytes each entry actually inflates to and stops that entry once it passes 50 MB, so a lying central directory does not bypass it.
- A zip is checked even when the declared content type is the legacy spreadsheet type.
- A spreadsheet that declares more than 10,000 rows by 256 columns, or that contains more cells than that, returns HTTP 400 attachment_too_large.
- A file that cannot be read returns HTTP 400 text_extraction_failed.
- Extraction stops after 10 seconds.
- Successful and failed extractions are cached in the new attachment_text table, and a failed cache hit returns the same error.
- An inbox-scoped key for a different inbox returns HTTP 404 inbox_not_found.
- Attachment metadata includes text_url when the type is supported.
- Deleting a message, a thread, an inbox, or an expired inbox also deletes the raw row and cached attachment text.
- A held message returns HTTP 409 message_held for the raw download and for attachment text until it is released.
- New MCP tool cooper_get_attachment (50 tools total).
- format text or base64 defaults to text when the type can be extracted.
- base64 over 5 MB returns attachment_too_large and includes the download URL.
Inbound screening for prompt injection
- Every stored inbound message now includes safety.
- PATCH /api/v1/inboxes/{id} accepts screening, which is off, observe, or hold, and the default is observe.
- A value other than those three returns HTTP 400 invalid_screening.
- The check is a heuristic, not a guarantee, and the body stays untrusted data.
- Suspicious starts at 40 only when signals combine or a strong signal is present.
- A visible instruction phrase, an instruction inside an HTML comment, hidden text that itself contains an instruction, or a bidirectional control outside right-to-left text can reach that score.
- The words you are now count only when the next words name an AI role or mode.
- Ignore or disregard counts only when previous is followed by instructions, a prompt, rules, directions, or a system message.
- A link whose visible domain differs from the href host is ignored for common tracking and redirect hosts and does not flag on its own.
- Hidden preview text does not flag on its own.
- A single bidirectional mark in Arabic or Hebrew text does not count.
- Zero-width characters count when they are dense or sit inside an instruction word.
- An instruction phrase inside quoted text or a code block weighs less and does not flag on its own.
- The scanner reads at most the first 256 KB, walks HTML once, and stops after 250 ms.
- A timeout records reason screening_timeout and stores the mail normally.
- observe adds the suspicious label and still fires message.received and creates a task when the sender is eligible.
- hold also adds the held label, fires message.held instead of message.received, and creates no task.
- While held, list, get, search, threads, events, webhooks, and MCP return metadata, the held label, and the safety summary only.
- text, html, extracted_text, extracted_html, preview, and attachment bytes are withheld, and search does not match the held body.
- Attachment download, the raw .eml download, and attachment text return HTTP 409 message_held.
- off records reason screening_off and does not add those labels.
- A scoring failure records screening_error and still stores the mail.
- Screening never drops a message.
- Allow and block lists still run first, so a blocked sender is not stored and fires message.blocked.
- A bounce or complaint is still applied, including suppression, when the report message is held.
- Held mail does not create a task, so it is not included in an owner digest until release.
- POST /api/v1/inboxes/{id}/messages/{msgId}/release removes held, restores the body, then fires message.received and creates the task once if the sender is eligible.
- A message that is not held returns HTTP 409 message_not_held.
- The messages table gains safety, and the inboxes table gains screening, with no new indexes.
- New MCP tool cooper_release_message (49 tools total).
- cooper_update_inbox accepts screening.
- cooper_get_message returns safety.
Bounce and complaint events, suppression list
- Inbound mail that is a multipart/report with report-type delivery-status, or a message whose local part is exactly mailer-daemon or postmaster with a bounce subject and a message/delivery-status part, is parsed for Final-Recipient, Action, Status, Diagnostic-Code, and the original Message-ID.
- Lines in a text body are not a bounce.
- A multipart/report with report-type feedback-report is a complaint.
- When that Message-ID matches an outbound message on this account, Cooper writes a message_events row, sets status to bounced or complained, and adds that label.
- Only Action failed with Status 5.x.x marks the original message bounced and suppresses that address, and only when it was a To, Cc, or Bcc on that message.
- A complaint suppresses with reason complaint on the same recipient rule.
- A named address that was not a recipient is not suppressed.
- An unmatched report suppresses nothing.
- Status 4.x.x is stored as a delayed delivery event and does not mark the message bounced or suppress.
- Status 2.x.x is ignored.
- A blocked sender is dropped before the report is applied.
- The report itself is stored with labels bounce and auto, or complaint and auto, and it does not create a task.
- An unmatched report is stored only.
- Webhooks message.bounced and message.complained carry message_id, inbox_id, thread_id, bounce_type, and recipients with address, status, action, and diagnostic.
- Outbound message JSON includes delivery_events, and detail is JSON text.
- GET /api/v1/suppressions lists the account list.
- POST /api/v1/suppressions with {address} adds reason manual and returns HTTP 201, or HTTP 200 when the address is already listed.
- DELETE /api/v1/suppressions/{address} removes it.
- A missing row returns HTTP 404 suppression_not_found.
- A bad address returns HTTP 400 invalid_address.
- An inbox-scoped key receives HTTP 403 permission_denied.
- Agent sends, replies, forwards, and task replies to a suppressed address return HTTP 403 recipient_suppressed with the list, and nothing is sent, stored, or counted.
- Owner confirmation and progress mail are not checked.
- Both live outbound paths set the visible From and do not set a Return-Path or a delivery callback, so Cooper does not accept a provider POST and does not record delivered events.
- A bounce that never arrives as inbound mail is not applied.
- New tables message_events, with indexes on message_id and on account_id plus created_at, and suppressions, with primary key account_id and address.
- New MCP tools cooper_list_suppressions and cooper_delete_suppression (48 tools total).
Idempotency-Key for sends
- POST /api/v1/inboxes/{id}/messages, POST /api/v1/inboxes/{id}/messages/{msgId}/reply, POST /api/v1/inboxes/{id}/messages/{msgId}/reply-all, POST /api/v1/inboxes/{id}/messages/{msgId}/forward, and POST /api/v1/tasks/{id}/reply accept an Idempotency-Key header.
- The value must be 1 to 256 characters of letters, digits, and - .
- _ ~.
- An empty or invalid value returns HTTP 400 invalid_idempotency_key.
- The first use of a key sends the message and stores the key for 24 hours.
- The same key and the same request returns that message with HTTP 200, idempotent true, and the response header Idempotent-Replayed: true, and does not send again.
- The same key with a different request returns HTTP 409 idempotency_key_conflict.
- A second request while the first is still running returns HTTP 409 idempotency_request_in_progress.
- If the send fails, the key is removed so a retry can proceed.
- client_id still makes a send idempotent, and when both are present client_id is checked first.
- A task-reply replay returns the stored message with idempotent true.
- The daily cron deletes expired keys.
- The new table is idempotency_keys, with an index on expires_at.
- No new MCP tools.
- cooper_send_message and cooper_reply_task accept idempotency_key (46 tools total).
Inbox metadata, display names, search, and paging
- POST /api/v1/inboxes can omit username.
- Cooper then picks box plus 8 hex characters, the same generator as a batch with no prefix.
- The body may include metadata and client_id.
- The same client_id on this account returns the original inbox with HTTP 200 and idempotent true and does not create another inbox.
- POST /api/v1/inboxes/batch accepts metadata and stores that object on every inbox in the batch.
- PATCH /api/v1/inboxes/{id} accepts display_name, including null to clear it, and metadata.
- A metadata null value removes that key.
- A metadata object allows at most 256 keys, keys of at most 256 characters, and values that are a string, number, or boolean.
- The stored JSON must be at most 16 KB.
- Anything else returns HTTP 400 invalid_metadata.
- GET /api/v1/inboxes accepts q, a case-insensitive substring of the email, username, or display name, and returns prefix matches first.
- limit defaults to 100 and cannot exceed 500.
- A limit outside 1 to 500 returns HTTP 400 invalid_limit.
- page_token continues the list and the response includes next_page_token.
- A bad page_token returns HTTP 400 invalid_page_token.
- Inbox JSON now includes metadata and client_id.
- The inboxes table gains metadata and client_id.
- A unique index idx_inboxes_client covers account_id and client_id where client_id is not null.
- New MCP tools cooper_get_inbox and cooper_confirm_owner (46 tools total).
- cooper_list_inboxes accepts q, label, limit, and page_token.
- cooper_create_inbox accepts metadata and client_id, and username is optional.
- cooper_update_inbox accepts display_name and metadata.
Webhooks: get, enable/disable, signed timestamps, delivery log
- GET /api/v1/webhooks/{id} returns one webhook with the secret redacted the same way as the list.
- PATCH /api/v1/webhooks/{id} accepts enabled.
- enabled false disables the hook, sets disabled_at, and sets disabled_reason to manual.
- A disabled hook receives no deliveries.
- enabled true turns it back on and sets consecutive_failures to 0.
- A delivery that finishes as a non-2xx after retries increments consecutive_failures.
- At 20 the hook sets enabled to 0, disabled_at, and disabled_reason consecutive_failures.
- Any 2xx resets consecutive_failures to 0.
- Deliveries add x-cooper-timestamp (unix seconds) and x-cooper-signature-v2, which is v1= plus the hex HMAC-SHA256 of the secret over the timestamp, a dot, and the raw body.
- x-cooper-signature is unchanged and is still sha256= of the raw body.
- Verify the v2 header within 5 minutes and dedupe on x-cooper-delivery.
- inbox_ids accepts at most 10 inbox ids.
- inbox_id is still accepted and stored into inbox_ids.
- A hook matches when inbox_ids is empty or contains the event inbox.
- More than 10 ids returns 400 too_many_inboxes.
- POST /api/v1/webhooks with the same client_id returns the original hook with HTTP 200 and the secret redacted.
- Every delivery is stored with status delivered or failed, attempts, and the last response code.
- The stored payload is capped at 256 KB.
- POST /api/v1/webhooks/{id}/test sends {type:webhook.test, data:{webhook_id}} and returns {delivery:{id, status, response_status, attempts, event_id}}.
- GET /api/v1/webhooks/{id}/deliveries lists them with limit from 1 to 100 and an optional status.
- A bad limit returns 400 invalid_limit.
- A bad status returns 400 invalid_status.
- POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver sends the same event id with a new timestamp and signature.
- A missing webhook returns 404 webhook_not_found.
- A missing delivery returns 404 delivery_not_found.
- A disabled hook returns 409 webhook_disabled for test and redeliver.
- The daily cron deletes delivery rows older than 7 days.
- The webhooks table gains enabled, consecutive_failures, disabled_at, disabled_reason, inbox_ids, and client_id, and then the unique index idx_webhooks_client.
- New MCP tools cooper_list_webhooks, cooper_update_webhook, cooper_delete_webhook, and cooper_test_webhook (44 tools total).
Message filters, paging, and per-inbox search
- GET /api/v1/inboxes/{id}/messages filters with before and after (ISO-8601 exclusive bounds on created_at), from, to, subject, direction (inbound or outbound), thread_id, and ascending.
- A bad timestamp returns HTTP 400 invalid_date.
- A bad direction returns HTTP 400 invalid_direction.
- ascending must be true or false, and anything else returns HTTP 400 invalid_ascending.
- page_token is the base64url of created_at and id, ordered with the id so equal timestamps do not skip or repeat a message, and a bad token returns HTTP 400 invalid_page_token.
- The response includes next_page_token, limit stays at most 200, and labels and unread still filter on the server before that limit.
- from, to, and subject are case-insensitive substrings, to matches To and Cc, and LIKE wildcards in those filters match the character itself.
- GET /api/v1/inboxes/{id}/messages/search?q= searches that inbox, and GET /api/v1/search accepts inbox_id, before, and after.
- Each search result includes highlights, with matched words wrapped in ** and about 80 characters of context in subject and text.
- An empty q returns HTTP 400 missing_query, and search limit stays at most 100.
- POST /api/v1/inboxes/{id}/messages/batch-get takes 1 to 500 unique message ids and returns the messages plus not_found.
- Duplicate ids return HTTP 400 duplicate_message_ids.
- More than 500 ids return HTTP 400 too_many_ids.
- An empty message_ids array returns HTTP 400 missing_message_ids.
- Another account's inbox returns HTTP 404 inbox_not_found.
- cooper_list_messages accepts the new filters and returns next_page_token.
- cooper_search accepts inbox_id.
- New MCP tool cooper_search_messages (40 tools total).
Custom-domain mail behind a flag
- Custom-domain mail follows COOPER_CUSTOM_DOMAIN_MAIL.
- Adding or verifying a domain looks up the zone on the operator account and never creates one.
- A missing zone returns zone_status domain_zone_not_onboarded and nameserver instructions.
- A zone on the account is enabled for routing, the catch-all goes to the existing inbound worker, and sending is onboarded.
- Returned records are the routing MX hosts, TXT SPF v=spf1 include:_spf.mx.cloudflare.net ~all, the routing DKIM TXT, the cf-bounce MX, SPF, and DKIM records, a DMARC suggestion, and the verify TXT.
- mail.receiving, mail.sending, and mail.inboxes turn true only after the matching records verify.
- POST /api/v1/inboxes accepts domain when that domain is verified and mail.receiving is true.
- Otherwise the codes are 404 domain_not_found, 409 domain_not_verified, and 409 domain_receiving_not_ready.
- Inbound matches the full address.
- An unknown address is not stored.
- Sending from a custom domain uses the operator sender.
- The fallback sender is used only when that domain is verified there too, otherwise the code is domain_sending_not_ready.
- The domains table gains mail_json with no new index.
- No new MCP tools.
- cooper_create_inbox accepts an optional domain (39 tools total).
API key management and scoped keys
- List keys with GET /api/v1/keys.
- Each row has id, name, prefix, inbox_id, permissions, created_at, last_used_at, expires_at, and revoked_at.
- The secret is never returned.
- GET /api/v1/keys/{id} returns one key.
- PATCH /api/v1/keys/{id} with {name} renames it.
- DELETE /api/v1/keys/{id} sets revoked_at and the key stops working on the next request, including when you revoke the key you are calling with.
- POST /api/v1/keys with a Bearer key accepts name, inbox_id, permissions, and ttl_hours or expires_at.
- A restricted key needs key_write and can only mint a key whose permissions are a subset of its own and whose inbox scope is not wider.
- Unknown permission names return 400 invalid_permission.
- A missing permission returns 403 permission_denied with param set to that permission.
- Revoked keys return 401 api_key_revoked.
- Expired keys return 401 api_key_expired.
- POST /api/v1/inboxes/{id}/keys mints a key scoped to that inbox.
- An inbox-scoped key can use its own inbox.
- Another inbox returns 404 inbox_not_found.
- Listing inboxes, search, tasks, events, threads, and webhooks returns only that inbox.
- Creating an inbox, a workspace, a domain, or a billing checkout returns 403 permission_denied.
- A webhook created by a scoped key is stored on that inbox.
- GET /api/v1/me returns account_id, parent_account_id, auth_type api_key or oauth, the key fields or null, and workspace id plus inbox_quota when this account is a sub-account.
- POST /api/v1/keys without a Bearer key is unchanged: it still creates an account and a full-access key.
- New MCP tool cooper_whoami (39 tools total).
- Mint and revoke keys over HTTP.
- MCP does not mint keys, so a secret is not written into a chat transcript.
Allow and block lists
- Allow and block lists guard who an agent may email and which senders are stored.
- GET and POST /api/v1/lists/{direction}/{type} manage account-wide entries, and the same paths under /api/v1/inboxes/{id}/lists manage one inbox.
- direction is send, receive, or reply.
- type is allow or block.
- An entry is a lowercase email or domain, up to 1000 per list.
- Posting an existing entry returns HTTP 200 with that row.
- A bad direction or type returns 400 invalid_list.
- A bad entry returns 400 invalid_entry.
- A missing entry returns 404 list_entry_not_found.
- A full list returns 400 list_full.
- When an inbox has any entries for a direction, only that inbox's lists apply.
- A block match wins.
- A non-empty allow list blocks everyone else.
- Sends, including reply, reply-all, and forward, check every to, cc, and bcc address before the provider is called.
- A blocked recipient returns HTTP 403 recipient_blocked and nothing is sent, stored, or counted.
- Progress email to a verified owner is exempt.
- Inbound mail uses reply when In-Reply-To matches an outbound Message-ID in that inbox, and receive otherwise.
- A blocked sender is not stored and does not fire message.received or create a task.
- POST /api/v1/internal/inbound returns HTTP 200 with dropped true and reason sender_blocked.
- The test injector returns HTTP 403 sender_blocked.
- Blocked inbound fires message.blocked with inbox_id, from, subject, direction, and reason.
- The per-inbox task allowlist is unchanged.
- New MCP tools cooper_list_list_entries, cooper_get_list_entry, cooper_create_list_entry, and cooper_delete_list_entry (38 tools total).
Threads API
- Read a whole conversation with GET /api/v1/inboxes/{id}/threads and GET /api/v1/threads.
- A thread is computed from messages that share a thread_id.
- Lists are ordered by updated_at, newest first, with limit 1 to 100 (default 20), before, after, and ascending.
- page_token is the base64url of updated_at and thread_id.
- A bad token returns HTTP 400 invalid_page_token.
- GET /api/v1/inboxes/{id}/threads/{threadId} and GET /api/v1/threads/{threadId} return the thread plus messages from oldest to newest, including extracted_text, up to 200 (default 100).
- An unknown thread returns HTTP 404 thread_not_found.
- GET /api/v1/inboxes/{id}/threads/search?q= returns threads with a matching message, at most 50.
- An empty q returns HTTP 400 missing_query.
- DELETE /api/v1/inboxes/{id}/threads/{threadId} removes every message in the thread plus attachments and search rows, and leaves owner tasks and updates in place.
- DELETE /api/v1/inboxes/{id}/messages/{msgId} removes one message.
- GET /api/v1/inboxes/{id}/threads/{threadId}/attachments/{attId} downloads an attachment on that thread.
- PATCH /api/v1/inboxes/{id}/threads/{threadId} adds or removes labels on every message, with the same rules as message labels.
- New MCP tools cooper_list_threads, cooper_get_thread, cooper_search_threads, cooper_delete_thread, and cooper_update_thread (34 tools total).
Event log and wait-for-mail
- GET /api/v1/events and GET /api/v1/inboxes/{id}/events return this account's event log in ascending order of created_at and id.
- Query types filters the list, after accepts an opaque cursor or an ISO timestamp, limit defaults to 50 and cannot exceed 100, and wait long-polls from 0 to 25 seconds.
- When after is omitted the window starts one hour ago.
- An unknown type returns HTTP 400 invalid_event_type.
- An inbox on another account returns inbox_not_found.
- GET /api/v1/events/stream is Server-Sent Events for up to 25 seconds, honors Last-Event-ID, and ends with a timeout event so the client reconnects.
- There is no WebSocket endpoint.
- message.received and message.sent store a summary whose extracted_text is capped at 4,000 characters, while webhook bodies stay the full payload and share the same evt_ id in x-cooper-delivery.
- The daily cron deletes events older than 7 days.
- New MCP tools cooper_wait_for_message and cooper_list_events (29 tools total).
Reply, reply-all, and forward
- Reply to a stored message with POST /api/v1/inboxes/{id}/messages/{msgId}/reply.
- Inbound replies go to the original Reply-To or From, and replies to mail you sent go to the original To.
- The subject is prefixed with Re: unless it already starts with re:.
- In-Reply-To and References use the original Message-ID, the last 20 reference ids are kept, and the reply stays on the same thread_id.
- POST /api/v1/inboxes/{id}/messages/{msgId}/reply-all adds the other recipients, merges your cc, drops this inbox address, and dedupes.
- A reply with neither text nor html returns 400 missing_body.
- An empty recipient list returns 400 missing_to.
- POST /api/v1/inboxes/{id}/messages/{msgId}/forward starts a new thread with a Fwd: subject unless the original already starts with fwd: or fw:, a forwarded header block, and the original attachments unless include_attachments is false.
- Copied attachments over 10 files or the size caps return 400 attachments_too_large.
- An unknown message returns 404 message_not_found.
- A paused inbox returns 403 inbox_paused and does not send.
- The same client_id returns the original message with idempotent true and does not send again.
- POST /api/v1/inboxes/{id}/messages now treats in_reply_to of a msg_ id as that message: the wire In-Reply-To uses its Message-ID and the send keeps its thread_id.
- New MCP tools cooper_reply_message and cooper_forward_message (27 tools total).
- cooper_send_message accepts cc, bcc, reply_to, headers, labels, and in_reply_to.
Custom domains: verify now, delete, zone file
- POST /api/v1/domains/{id}/verify checks that domain now and stores per-record status valid, missing, or invalid with the values found.
- The daily cron uses the same check.
- A pending domain that passes fires domain.verified once.
- A second verify within 60 seconds returns HTTP 429 rate_limited with Retry-After.
- DELETE /api/v1/domains/{id} removes the domain, and when dns.mode is automatic it deletes only the DNS records Cooper wrote.
- GET /api/v1/domains/{id}/zone-file returns text/plain BIND lines.
- Another account's domain returns 404 domain_not_found.
- The domains table gains a records_status column with no new index.
- New MCP tools cooper_list_domains, cooper_verify_domain (25 tools total).
Mark messages read and filter unread
- Mark a message read with PATCH /api/v1/inboxes/{inbox}/messages/{id} and {"remove_labels":["unread"]}.
- You can also add the read label in the same call.
- POST /api/v1/inboxes/{inbox}/messages/{id}/read removes unread and adds read.
- read and unread can be changed.
- Other system labels, including inbox, sent, untrusted, and auth_failed, cannot.
- Label updates work on a paused inbox.
- GET /api/v1/inboxes/{inbox}/messages?labels=unread and ?unread=true filter on the server before limit.
- New MCP tool cooper_update_message.
- cooper_list_messages accepts labels and unread (23 tools total).
Pause and resume inboxes
- Pause or resume an inbox with PATCH /api/v1/inboxes/{id} and {"status":"paused"} or {"status":"active"}.
- Pausing sets paused_at and keeps the address, threads, and history.
- Resuming clears paused_at.
- Pausing again keeps the original paused_at.
- Sends from a paused inbox return HTTP 403 inbox_paused and are not stored or counted.
- Inbound mail to a paused inbox is dropped and does not fire webhooks.
- GET /api/v1/inboxes?status= filters by active or paused.
- POST /api/v1/inboxes and POST /api/v1/inboxes/batch accept an optional status.
- New MCP tool cooper_update_inbox (22 tools total).
Batch & temporary inboxes, custom domains, sub-accounts
- Batch inbox creation POST /api/v1/inboxes/batch with per-plan caps (Free 5, Starter 25, Pro 100).
- Temporary inboxes via ttl_hours/expires_at with auto-cleanup.
- Label filter GET /api/v1/inboxes?label=.
- DELETE /api/v1/inboxes/{id}.
- One-call custom domains POST /api/v1/domains returning SPF/DKIM/DMARC/MX/verify records, with a domain.verified webhook (Starter+).
- Sub-accounts POST/GET /api/v1/workspaces with scoped keys and quotas rolling up to the parent.
- New MCP tools cooper_create_inboxes, cooper_add_domain, cooper_create_workspace, cooper_list_workspaces, cooper_delete_inbox (21 tools total).
- New /quickstart 'Disposable email inbox per AI agent run'.