Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.
TypeScript
/**
* cumora-email-gate — Cloudflare Email Worker.
*
* For every inbound email Cloudflare Email Routing routes to this worker:
* 1. Reject (550) if the recipient domain isn't in EMAIL_ROOT_DOMAINS.
* 2. Stream the raw MIME, parse with postal-mime.
* 3. Build a JSON payload (message-id, in-reply-to, references, from,
* to, cc, subject, text, html, raw size, autoSubmitted,
* authVerdict, envelopeFrom, and attachments[] as base64 — see
* MAX_ATTACHMENT_BYTES / the total cap). authVerdict comes from
* Cloudflare's Authentication-Results header, not from the sender's
* copy of that header. See auth-verdict.ts.
* 4. Sign with HMAC-SHA256(EMAIL_INBOUND_HMAC_SECRET, body) and POST
* to CUMORA_INBOUND_URL.
* 5. Reject (550) if the server says "no recipient resolved" so the
* sending MTA gets a real bounce instead of a silent black hole.
*
* NOTE: Cloudflare Email Workers can't *send* mail — only receive. Outbound
* goes through Resend on the server side.
*/
import PostalMime from 'postal-mime'
import { deriveAuthVerdict, type InboundAuthVerdict } from './auth-verdict.js'
interface Env {
EMAIL_INBOUND_HMAC_SECRET: string
CUMORA_INBOUND_URL: string
/** Comma-separated. e.g. "cumora.ai,cumora.dev". The recipient must
* end with `.<root>` (subdomain) OR equal `<root>` (apex). */
EMAIL_ROOT_DOMAINS: string
}
interface InboundAttachment {
filename: string
mimeType: string
/** Decoded byte count (we send `content` base64-encoded; this is the
* pre-encode size so the server can pre-check totals without decoding). */
sizeBytes: number
/** Base64-encoded body. Capped per-attachment so a single rogue 50MB
* PDF doesn't blow the 25MB JSON limit. The server uploads from here
* into object storage and clears it before persisting. */
contentBase64: string
/** True when the source attachment was rejected — present only as
* metadata so the user still sees "[filename] (skipped — too large)". */
truncated?: boolean
}
interface InboundPayload {
messageId: string
envelopeTo: string
inReplyTo: string | null
references: string[]
from: string
to: string[]
cc: string[]
subject: string
text: string
html: string | null
rawSizeBytes: number
/** RFC 3834 Auto-Submitted header value (lowercased). Forwarded so the
* server can flag the row + refuse heartbeat auto-reply on it. null
* when the header was absent or set to "no". */
autoSubmitted: string | null
/** `aligned` only when Cloudflare's own Authentication-Results record
* authenticated this message. The server will not map `from` onto a
* workspace member for any other value. */
authVerdict: InboundAuthVerdict
/** SMTP MAIL FROM, as Email Routing reported it in `message.from`. */
envelopeFrom: string
attachments: InboundAttachment[]
}
/** Cap per-attachment + cumulative to keep the JSON POST under the
* server's 25MB body limit with comfortable headroom for base64 expansion
* (~33% overhead). 10MB raw per attachment, 18MB raw across all of them. */
export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024
export const MAX_TOTAL_ATTACHMENT_BYTES = 18 * 1024 * 1024
export function toBase64(bytes: Uint8Array): string {
// CF Workers have no Buffer; build base64 from a binary string. Chunk the
// String.fromCharCode call so we don't blow the argument-count limit on
// multi-megabyte buffers.
let bin = ''
const chunk = 0x8000
for (let i = 0; i < bytes.length; i += chunk) {
bin += String.fromCharCode(...bytes.subarray(i, i + chunk))
}
return btoa(bin)
}
export function recipientAccepted(rcpt: string, env: Env): boolean {
const lc = rcpt.toLowerCase()
const at = lc.indexOf('@')
if (at < 0) return false
const dom = lc.slice(at + 1)
for (const root of env.EMAIL_ROOT_DOMAINS.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)) {
if (dom === root || dom.endsWith('.' + root)) return true
}
return false
}
async function hmacHex(secret: string, body: string): Promise<string> {
const enc = new TextEncoder()
const key = await crypto.subtle.importKey(
'raw',
enc.encode(secret),
{ name: 'HMAC', hash: 'SHA-256' },
false,
['sign'],
)
const sig = await crypto.subtle.sign('HMAC', key, enc.encode(body))
return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, '0')).join('')
}
function fmtAddress(a: { address?: string; name?: string }): string {
const addr = (a.address ?? '').trim()
const name = (a.name ?? '').trim()
if (!addr) return ''
return name ? `${name.replace(/"/g, '\\"')} <${addr}>` : addr
}
export function readArrayHeader(raw: string | undefined): string[] {
if (!raw) return []
// References / In-Reply-To headers are <id1> <id2> ... — split on
// whitespace, drop the angle brackets. postal-mime's parsed headers
// return raw strings here.
return raw
.split(/\s+/)
.map((s) => s.replace(/^<+|>+$/g, '').trim())
.filter(Boolean)
}
export function getHeader(headers: { key: string; value: string }[] | undefined, name: string): string | undefined {
if (!headers) return undefined
const lc = name.toLowerCase()
for (const h of headers) {
if (h.key.toLowerCase() === lc) return h.value
}
return undefined
}
/** Fallback time bucket for a message that carries no `Date:` of its own.
* Wide enough to cover an MTA's first retries, which is when a tempfail is
* most likely to be retried at all. */
export const SYNTH_ID_BUCKET_MS = 60 * 60 * 1000
/** A Message-Id for a message that arrived without one. The server's dedup
* index requires a non-null id.
*
* It has to be DERIVED, not random. This worker throws on an upstream 5xx or a
* network failure precisely so the sending MTA tempfails and retries — and
* that retry runs this worker again on the same physical message. The server
* dedups on `smtp_message_id`, so a fresh random id per attempt is a fresh
* delivery per attempt: the recipient sees the same email once per retry. The
* comment here always claimed the id included "the recipient + a coarse
* timestamp"; the string it built included neither.
*
* The raw bytes are not a safe input. A retry is a new SMTP transaction and
* arrives with its own `Received:` headers, so identical mail hashes
* differently. These five fields survive that, and still tell two genuinely
* different messages apart.
*
* `Date:` is what separates two otherwise identical sends. RFC 5322 requires
* it and nearly every MTA adds it, but a sender that omitted Message-Id may
* have omitted this too — then fall back to a coarse bucket, which is the
* original intent and the best available when the message carries no time of
* its own. A retry that straddles a bucket boundary still duplicates. That
* residue is deliberate: merging two genuinely distinct alerts would lose
* mail, and losing mail is worse than showing it twice. */
export async function synthesizeMessageId(parts: {
envelopeFrom: string
envelopeTo: string
date: string | undefined
subject: string
body: string
}): Promise<string> {
const stamp = parts.date?.trim() || `bucket:${Math.floor(Date.now() / SYNTH_ID_BUCKET_MS)}`
// NUL-joined so a field boundary cannot be forged by content.
const material = [parts.envelopeFrom, parts.envelopeTo, stamp, parts.subject, parts.body].join('\u0000')
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(material))
const hex = Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
return `synth-${hex}@cumora-email-gate`
}
export default {
async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> {
if (!recipientAccepted(message.to, env)) {
message.setReject('Recipient domain not served')
return
}
if (!env.EMAIL_INBOUND_HMAC_SECRET || !env.CUMORA_INBOUND_URL) {
message.setReject('Email gate misconfigured')
console.error('[email-gate] missing EMAIL_INBOUND_HMAC_SECRET or CUMORA_INBOUND_URL')
return
}
// Read the raw RFC 5322 message into a Buffer-equivalent we can both
// measure and parse. Cloudflare's `message.raw` is a ReadableStream.
let rawBytes: Uint8Array
try {
rawBytes = await new Response(message.raw).bytes()
} catch (e) {
message.setReject('Failed to read message')
console.error('[email-gate] read raw failed:', e instanceof Error ? e.message : String(e))
return
}
let parsed: Awaited<ReturnType<InstanceType<typeof PostalMime>['parse']>>
try {
parsed = await new PostalMime().parse(rawBytes)
} catch (e) {
message.setReject('Unparseable MIME')
console.error('[email-gate] parse failed:', e instanceof Error ? e.message : String(e))
return
}
// postal-mime exposes structured headers as parsed.headers (array of
// {key, value}). messageId / inReplyTo come pre-parsed at top-level
// but References doesn't, so dig the header manually.
// Attachments — pull every file part out, encode within budget, drop
// anything beyond the per-message ceiling with a truncated marker so
// the recipient at least sees the filename.
const attachments: InboundAttachment[] = []
let totalAttachmentBytes = 0
for (const a of parsed.attachments ?? []) {
// postal-mime's `content` is Uint8Array. `disposition` distinguishes
// inline vs attachment but we forward both — inline images that the
// HTML view references via cid: become user-visible files too.
const raw = a.content instanceof Uint8Array ? a.content : new Uint8Array(a.content as ArrayBuffer)
const filename = (a.filename ?? 'attachment').slice(0, 200)
const mimeType = (a.mimeType ?? 'application/octet-stream').slice(0, 120)
if (raw.byteLength > MAX_ATTACHMENT_BYTES || totalAttachmentBytes + raw.byteLength > MAX_TOTAL_ATTACHMENT_BYTES) {
attachments.push({ filename, mimeType, sizeBytes: raw.byteLength, contentBase64: '', truncated: true })
continue
}
attachments.push({
filename, mimeType, sizeBytes: raw.byteLength,
contentBase64: toBase64(raw),
})
totalAttachmentBytes += raw.byteLength
}
const referencesHeader = getHeader(parsed.headers, 'References')
// RFC 3834: "no" or missing → human, anything else (auto-replied /
// auto-generated / auto-notified) → automation. Vacation responders,
// ticket-system bots, AND other cumora installations all set this.
const autoSubmittedRaw = (getHeader(parsed.headers, 'Auto-Submitted') ?? '').trim().toLowerCase()
const autoSubmitted = autoSubmittedRaw && autoSubmittedRaw !== 'no' ? autoSubmittedRaw : null
const payload: InboundPayload = {
messageId: (parsed.messageId ?? '').replace(/^<+|>+$/g, ''),
inReplyTo: parsed.inReplyTo ? parsed.inReplyTo.replace(/^<+|>+$/g, '') : null,
references: readArrayHeader(referencesHeader),
from: parsed.from ? fmtAddress(parsed.from) : message.from,
// To / Cc — postal-mime returns Address[]. Fall back to the envelope
// recipient if the header is missing (rare but happens).
to: (parsed.to ?? []).map(fmtAddress).filter(Boolean),
// The address SMTP actually delivered to, and the one this worker
// admitted the message on two dozen lines up. It is absent from the
// headers whenever the agent was Bcc'd or reached through an alias or a
// forwarding rule, and then it is the ONLY thing identifying the
// recipient — so send it always, not just when To: happens to be empty.
envelopeTo: message.to,
cc: (parsed.cc ?? []).map(fmtAddress).filter(Boolean),
subject: parsed.subject ?? '',
text: (parsed.text ?? '').trim(),
html: parsed.html ?? null,
rawSizeBytes: rawBytes.byteLength,
autoSubmitted,
authVerdict: deriveAuthVerdict(message.headers),
envelopeFrom: message.from,
attachments,
}
if (payload.to.length === 0) payload.to = [message.to]
if (!payload.messageId) {
payload.messageId = await synthesizeMessageId({
envelopeFrom: message.from,
envelopeTo: message.to,
date: getHeader(parsed.headers, 'Date'),
subject: payload.subject,
body: payload.text,
})
}
const body = JSON.stringify(payload)
const sig = await hmacHex(env.EMAIL_INBOUND_HMAC_SECRET, body)
let res: Response
try {
res = await fetch(env.CUMORA_INBOUND_URL, {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-cumora-signature': `sha256=${sig}`,
},
body,
})
} catch (e) {
console.error('[email-gate] POST failed:', e instanceof Error ? e.message : String(e))
// Transient network or connection error — throw to signal a temporary failure
// (SMTP 4xx tempfail) in Cloudflare Email Routing so the sending MTA retries delivery later.
throw new Error(`Upstream unreachable: ${e instanceof Error ? e.message : String(e)}`)
}
if (res.status === 404) {
// Server says no agent matches this recipient — permanent rejection (SMTP 550 bounce).
message.setReject('No such recipient')
return
}
if (res.status >= 500) {
// 5xx upstream failure (server restarting, deploy in progress, database blip).
// Cloudflare Email Routing signals a temporary SMTP failure (4xx tempfail) when the
// handler throws, allowing sending MTAs (Gmail, Outlook, etc.) to retry delivery later.
const errorText = await res.text().catch(() => '')
console.error(`[email-gate] upstream ${res.status}: ${errorText.slice(0, 400)}`)
throw new Error(`Upstream temporary failure (${res.status}): ${errorText.slice(0, 200)}`)
}
if (!res.ok) {
// 4xx other than 404 (e.g. 400 bad request, 401 unauthorized HMAC, 413 payload too large).
// Permanent client rejection — retrying will not change the outcome.
ctx.waitUntil(res.text().then((t) => console.error(`[email-gate] upstream ${res.status}: ${t.slice(0, 400)}`)))
message.setReject(`Upstream ${res.status}`)
return
}
// 2xx — accepted. Email Worker has no `accept()`, just returning
// without setReject is acceptance.
ctx.waitUntil(res.text().then((t) => console.log(`[email-gate] delivered: ${t.slice(0, 200)}`)))
},
}