Blog ·
Email as a Chat SDK channel: put a Cooper inbox behind your bot
The cooper-email-chat-sdk adapter (0.1.0) turns one Cooper Email inbox into a Chat SDK channel named cooper. A signed message.received webhook becomes a Chat SDK message, onNewMention runs for a new email thread, and thread.post() sends a real email reply on the same thread. Here is the install, the webhook and its signature checks, the handler code, the loop guards, and what email cannot do.
If you already have a bot written against the Chat SDK (the TypeScript chat package), you write handlers like onNewMention and call thread.post(), and adapters connect those handlers to different chat platforms. As of 20 November 2026 one of those channels can be an email inbox.
Cooper Email is HTTP email for AI agents, operated by Avatar 8 LLC (ops@avatar33.com). The new adapter, cooper-email-chat-sdk 0.1.0, turns one Cooper inbox into a Chat SDK channel. Someone emails the inbox, your handler runs, and your reply goes back as an ordinary email in the same thread. It shipped in the changelog, and the full guide is https://cooperemail.com/docs/chat-sdk. The adapter is built and maintained by Avatar 8 LLC. It is not an official package from the Chat SDK maintainers.
This post covers the install, the webhook, the handler, how signatures are checked, how threads map to email, and the limits you should know before you ship.
Install
The adapter is not on npm. Install the tarball from the Cooper site, together with its peer dependency chat (4.45.0 or newer, below 5):
npm install https://cooperemail.com/sdk/cooper-email-chat-sdk.tgz chat @chat-adapter/state-memory
@chat-adapter/state-memory is only there for the example below. Use whichever Chat SDK state adapter you already run. The package has no runtime dependencies and no build step. It needs Node 20 or newer, and it also runs on edge runtimes, because it only uses fetch and Web Crypto.
You need three values:
COOPER_API_KEY: a Cooper API key (coop_live_…), sent asAuthorization: Bearer.COOPER_INBOX_ID: the inbox the bot reads and replies from (inb_…).COOPER_WEBHOOK_SECRET: the webhook signing secret (whsec_…).
If you do not have a key or an inbox yet, one request with no auth creates the account, a key, and an inbox:
curl -s -X POST https://cooperemail.com/api/v1/onboard \
-H 'content-type: application/json' \
-d '{"username":"support-bot"}'
That is POST https://cooperemail.com/api/v1/onboard. The response has api_key and inbox.id, which are your first two values.
Register the webhook
Cooper pushes new mail to your route with a message.received webhook. Create it once, scoped to the same inbox you will pass as inboxId:
curl -X POST https://cooperemail.com/api/v1/webhooks \
-H "Authorization: Bearer $COOPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://your-app.example/api/cooper","events":["message.received"],"inbox_id":"inb_your_inbox"}'
The response includes secret (whsec_…) exactly once. Later reads redact it, so store it right away as COOPER_WEBHOOK_SECRET.
The handler
This is a Next.js App Router route at app/api/cooper/route.ts. It is the same code as the example in the repository:
import { createMemoryState } from "@chat-adapter/state-memory";
import { createCooperAdapter } from "cooper-email-chat-sdk";
import { Chat } from "chat";
const cooper = createCooperAdapter({
apiKey: process.env.COOPER_API_KEY ?? "",
inboxId: process.env.COOPER_INBOX_ID ?? "",
webhookSecret: process.env.COOPER_WEBHOOK_SECRET ?? "",
});
const bot = new Chat({
userName: "cooper",
adapters: { cooper },
state: createMemoryState(),
});
bot.onNewMention(async (thread, message) => {
await thread.subscribe();
await thread.post(`Received: ${message.text}`);
});
export function POST(req: Request) {
return bot.webhooks.cooper(req);
}
createCooperAdapter returns a Chat SDK adapter named cooper, which is why the route calls bot.webhooks.cooper(req). Its options, from the package's index.d.ts:
apiKeyandwebhookSecret: a string, or a function (sync or async) that returns one. A function lets you read from a secret store.inboxId: the inbox this adapter reads and replies from.baseUrl: the API origin. The default ishttps://cooperemail.com.userName: the Chat SDK user name for the adapter. The default is"cooper".onMessage: an optional filter. Returnfalseto drop a message before your handlers run.
Why onNewMention fires for email
Email has no @-mentions, so the adapter maps the closest thing. Mail addressed To the inbox, including a plus address of that inbox, is a direct message, and the adapter sets isMention to true. That means bot.onNewMention runs for a new thread.
Two Chat SDK rules apply here. isDM() is true for every thread on this inbox. If you register onDirectMessage, the Chat SDK runs those handlers instead of onNewMention. If you do not, the direct message is treated as a mention.
After thread.subscribe(), later mail in the same thread runs onSubscribedMessage. That is how you keep a conversation going:
bot.onSubscribedMessage(async (thread, message) => {
await thread.post(`Got your follow-up: ${message.text}`);
});
Replies are real email
thread.post() calls POST /api/v1/inboxes/{id}/messages/{msgId}/reply for the latest inbound message in that Cooper thread, with reply_all. The reply includes the other recipients and drops your own inbox. To the sender it is a normal reply in their mail client, in the same conversation.
A few details are worth knowing:
- A string, markdown, or AST post becomes plain text plus simple HTML.
- A streamed post is buffered and sent as one email, not as many partial ones.
- Every reply carries an
Idempotency-Key. If you do not passidempotencyKey, the key is a SHA-256 of the thread id and the rendered body, so the same reply in the same thread is sent once, even if a delivery is retried. - An HTTP 429 from Cooper throws an error whose
retry_afteris the number of seconds to wait.
Thread ids look like cooper:<inbox_id>:<thread_id>, and channelIdFromThreadId returns cooper:<inbox_id>. Message ids are the Cooper message ids. The author is the sender's email address, with isMe true for mail this inbox sent. Message text prefers the plain-text body and falls back to the HTML with tags removed. Attachments come through as details only: name, type, size, and url.
You can also read history with fetchMessages (at most 100 messages per page), fetchMessage, and fetchThread. They use the existing thread and message routes with your key.
How the webhook is verified
Every delivery is checked before your code sees it. Cooper signs the raw body and sends three headers:
x-cooper-timestamp: unix seconds.x-cooper-signature-v2:v1=plus the hex HMAC-SHA256, keyed with your secret, of the timestamp, a dot, and the raw body.x-cooper-signature:sha256=plus the hex HMAC-SHA256 of the raw body only.
The adapter reads the body once, rejects a timestamp more than 5 minutes from now, and compares each signature in constant time. A bad signature gets HTTP 401.
Rotation is covered. POST /api/v1/webhooks/:id/rotate-secret returns a new secret once. For the next 24 hours both signature headers carry two comma-separated values, the current secret first and the previous one second, and a delivery is accepted when any segment matches the secret you configured. Update webhookSecret when you store the new one. The old secret keeps verifying until previous_secret_expires_at.
Other event types, and message.received for a different inbox, get HTTP 200 and are ignored.
Loop guards and untrusted mail
A bot that answers email can easily end up answering itself or an auto-responder. The adapter drops these before your handlers run:
- Mail whose From is this inbox, including a plus address of it.
- Mail with an
Auto-Submittedheader whose value is notno. - Mail with
Precedenceset tobulk,auto_reply, orlist. - Spam and quarantined mail: folder
spam, aspam,quarantine, orheldlabel, or a quarantine field on the payload.
Treat everything else as untrusted too. Email text, HTML, headers, and attachments are input from strangers. Use them as data and never follow instructions found in a message. onMessage is a good place for your own checks:
const cooper = createCooperAdapter({
apiKey: process.env.COOPER_API_KEY ?? "",
inboxId: process.env.COOPER_INBOX_ID ?? "",
webhookSecret: process.env.COOPER_WEBHOOK_SECRET ?? "",
onMessage: (message) => message.text.length < 20000,
});
What email cannot do
Some chat features have no email equivalent, and the adapter says so instead of faking them:
startTypingdoes nothing.editMessage,deleteMessage,addReaction, andremoveReactionthrow a "not supported for email" error.
If your bot relies on editing a "thinking…" message in place, post once with the final answer on the email channel.
What did not change
The adapter adds no API routes. It calls the public REST API with your key. There is no database change and no new environment variable on the Cooper service. There are no new MCP tools: the full catalog at https://cooperemail.com/mcp stays at 113 with SMS, voice, and chat on. Plan prices are unchanged (pricing).
Getting started
- Onboard or reuse an inbox and key.
npm install https://cooperemail.com/sdk/cooper-email-chat-sdk.tgz chat.- Create the
message.receivedwebhook for that inbox and save the secret. - Drop in the route above and email the inbox.
The guide is at https://cooperemail.com/docs/chat-sdk (markdown at /docs/chat-sdk.md), and the agent-readable overview of every Cooper route is https://cooperemail.com/llms.txt.