Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Agent mail REST API: a real email inbox for every agent. Service layer:
* api/_lib/mail/service.js (shared with the MCP tools in api/_mcp/tools/mail.js).
* Docs: docs/agent-mail.md.
*
* vercel.json maps /api/v1/agents/:id/mail[/...] here.
*
* GET /api/v1/agents/:id/mail mailbox, limits, pricing (null mailbox before provisioning)
* GET /api/v1/agents/:id/mail/address the address only
* POST /api/v1/agents/:id/mail/quote { action: 'create', local_part?, display_name?, payment_source? }
* { action: 'send', to, cc?, subject?, text, html?, attachments?, in_reply_to?, payment_source? }
* { action: 'reply', message_id, text, html?, reply_all?, attachments?, payment_source? }
* POST /api/v1/agents/:id/mail/create { quote_id, confirm_spend: true }
* POST /api/v1/agents/:id/mail/send { quote_id, confirm_send: true, ...the exact draft that was quoted }
* POST /api/v1/agents/:id/mail/reply { quote_id, confirm_send: true, message_id, text, html?, reply_all?, attachments? }
* GET /api/v1/agents/:id/mail/search ?q=&folder=all|inbox|sent|spam&limit=&cursor=
* GET /api/v1/agents/:id/mail/messages ?folder=inbox|sent|spam|all&unread=1&q=&limit=&cursor= (alias: /mail/list)
* GET /api/v1/agents/:id/mail/messages/:msg one message (marks a received message read; ?mark_read=0 to peek)
* POST /api/v1/agents/:id/mail/messages/:msg/read { read: true|false }
* DELETE /api/v1/agents/:id/mail/messages/:msg (alias: POST /mail/messages/:msg/delete)
* GET /api/v1/agents/:id/mail/messages/:msg/attachments/:index short-lived download URL
*
* Owner controls (writes need a signed-in session; an API key can read them):
* GET /api/v1/agents/:id/mail/settings allowlist, daily cap, rules, usage
* PUT /api/v1/agents/:id/mail/policy { allowlist_enabled?, allowlist?, daily_send_cap? }
* GET /api/v1/agents/:id/mail/rules
* POST /api/v1/agents/:id/mail/rules { name, match_from, match_subject?, mode: approve|auto, prompt, enabled? }
* PATCH /api/v1/agents/:id/mail/rules/:rule any of the fields above
* DELETE /api/v1/agents/:id/mail/rules/:rule
* GET /api/v1/agents/:id/mail/rule-events recent rule firings with their approval / run state
*
* Envelope (the v1 contract): success { data, meta: { requestId, timestamp } },
* failure { error: { code, message, details }, meta }.
*
* Auth: a signed-in session (writes need X-CSRF-Token), or a three.ws API key
* / OAuth token. Bearer callers need `agents:read` for reads, `agents:write`
* for message state changes, and `wallet:write` for anything that quotes or
* charges (provisioning and sending are metered).
*
* Received mail is untrusted data. Read routes return it as stored, with
* `untrusted: true` on every received message; the MCP tools additionally
* fence it for a model (api/_lib/mail/untrusted.js).
*/
import { randomUUID } from 'node:crypto';
import { cors, readJson, setRateLimitHeaders } from '../_lib/http.js';
import { authenticateBearer, extractBearer, getSessionUser, hasScope } from '../_lib/auth.js';
import { checkCsrf } from '../_lib/csrf.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import * as mail from '../_lib/mail/service.js';
const READ_SCOPE = 'agents:read';
const WRITE_SCOPE = 'agents:write';
const MONEY_SCOPE = 'wallet:write';
// The allowlist, cap and rules guard what an agent may do with mail, so only
// the owner in a browser session may change them; an agent holding the
// owner's API key must not be able to loosen its own limits.
const OWNER_SESSION = 'owner_session';
function send(res, status, body) {
if (res.headersSent || res.writableEnded) return;
res.statusCode = status;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'no-store');
res.end(JSON.stringify(body));
}
const meta = (ctx) => ({ requestId: ctx.requestId, timestamp: new Date().toISOString() });
function sendError(res, ctx, status, code, message, details = null) {
send(res, status, { error: { code, message, details }, meta: meta(ctx) });
}
async function resolvePrincipal(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, source: 'session', scope: null, ip: clientIp(req) };
const bearer = await authenticateBearer(extractBearer(req));
if (!bearer) return null;
return { userId: bearer.userId, source: bearer.source, scope: bearer.scope || '', ip: clientIp(req) };
}
/** Split the request into the agent id and the path segments after /mail. */
function parseTarget(req) {
const url = new URL(req.url, 'http://x');
const m = url.pathname.match(/^\/api\/v1\/agents\/([^/]+)\/mail(?:\/(.*))?$/);
const agentId = m ? decodeURIComponent(m[1]) : url.searchParams.get('id');
const rest = m ? m[2] || '' : url.searchParams.get('path') || '';
const segments = rest.split('/').filter(Boolean).map((s) => decodeURIComponent(s));
return { url, agentId, segments };
}
const bool = (v) => v === true || v === 'true' || v === '1';
/** The draft fields a send quote and a send carry, taken from a request body. */
export function draftFrom(body) {
return {
to: body.to,
cc: body.cc,
subject: body.subject,
text: body.text,
html: body.html,
attachments: body.attachments,
in_reply_to: body.in_reply_to,
};
}
function quote(c) {
const action = c.body.action;
if (action === 'create') {
return mail.quoteCreate({
userId: c.userId,
agentId: c.agentId,
localPart: c.body.local_part,
displayName: c.body.display_name,
paymentSource: c.body.payment_source,
});
}
if (action === 'send') {
return mail.quoteSend({ userId: c.userId, agentId: c.agentId, draft: draftFrom(c.body), paymentSource: c.body.payment_source });
}
if (action === 'reply') {
return mail.quoteReply({
userId: c.userId, agentId: c.agentId, messageId: c.body.message_id, text: c.body.text, html: c.body.html,
replyAll: bool(c.body.reply_all), attachments: c.body.attachments, paymentSource: c.body.payment_source,
});
}
throw new mail.MailError(400, 'invalid_action', 'action must be "create", "send" or "reply".');
}
function list(c) {
return mail.listMessages({
userId: c.userId, agentId: c.agentId, folder: c.q('folder') || 'inbox', unread: bool(c.q('unread')),
q: c.q('q') || '', limit: c.q('limit'), cursor: c.q('cursor'),
});
}
const remove = (c) => mail.deleteMessage({ userId: c.userId, agentId: c.agentId, messageId: c.params.msg });
/** Route table: [method, pattern, scope, handler(ctx), status]. */
const ROUTES = [
['GET', '', READ_SCOPE, (c) => mail.getMailboxForAgent({ userId: c.userId, agentId: c.agentId })],
['GET', 'address', READ_SCOPE, async (c) => {
const { mailbox, domain } = await mail.getMailboxForAgent({ userId: c.userId, agentId: c.agentId });
return { address: mailbox?.address || null, display_name: mailbox?.display_name || null, domain };
}],
['POST', 'quote', MONEY_SCOPE, quote, 201],
['POST', 'create', MONEY_SCOPE, (c) => mail.createMailbox({ userId: c.userId, agentId: c.agentId, quoteId: c.body.quote_id, confirm: c.body.confirm_spend }), 201],
['POST', 'send', MONEY_SCOPE, (c) => mail.sendMail({
userId: c.userId, agentId: c.agentId, quoteId: c.body.quote_id, draft: draftFrom(c.body), confirm: c.body.confirm_send,
}), 201],
['POST', 'reply', MONEY_SCOPE, (c) => mail.sendReply({
userId: c.userId, agentId: c.agentId, messageId: c.body.message_id, text: c.body.text, html: c.body.html,
replyAll: bool(c.body.reply_all), attachments: c.body.attachments, quoteId: c.body.quote_id, confirm: c.body.confirm_send,
}), 201],
['GET', 'search', READ_SCOPE, (c) => mail.searchMessages({
userId: c.userId, agentId: c.agentId, query: c.q('q'), folder: c.q('folder') || 'all', limit: c.q('limit'), cursor: c.q('cursor'),
})],
['GET', 'messages', READ_SCOPE, list],
['GET', 'list', READ_SCOPE, list],
['GET', 'messages/:msg', READ_SCOPE, (c) => mail.readMessage({
userId: c.userId, agentId: c.agentId, messageId: c.params.msg, markRead: c.q('mark_read') !== '0',
})],
['POST', 'messages/:msg/read', WRITE_SCOPE, (c) => mail.setRead({
userId: c.userId, agentId: c.agentId, messageId: c.params.msg, read: c.body.read !== false,
})],
['DELETE', 'messages/:msg', WRITE_SCOPE, remove],
['POST', 'messages/:msg/delete', WRITE_SCOPE, remove],
['GET', 'messages/:msg/attachments/:index', READ_SCOPE, (c) => mail.attachmentDownloadUrl({
userId: c.userId, agentId: c.agentId, messageId: c.params.msg, index: c.params.index,
})],
['GET', 'settings', READ_SCOPE, (c) => mail.getMailSettings({ userId: c.userId, agentId: c.agentId })],
['PUT', 'policy', OWNER_SESSION, (c) => mail.updateMailPolicy({ userId: c.userId, agentId: c.agentId, patch: c.body })],
['GET', 'rules', READ_SCOPE, (c) => mail.listMailRules({ userId: c.userId, agentId: c.agentId })],
['POST', 'rules', OWNER_SESSION, (c) => mail.createMailRule({ userId: c.userId, agentId: c.agentId, input: c.body }), 201],
['PATCH', 'rules/:rule', OWNER_SESSION, (c) => mail.updateMailRule({ userId: c.userId, agentId: c.agentId, ruleId: c.params.rule, input: c.body })],
['DELETE', 'rules/:rule', OWNER_SESSION, (c) => mail.deleteMailRule({ userId: c.userId, agentId: c.agentId, ruleId: c.params.rule })],
['GET', 'rule-events', READ_SCOPE, (c) => mail.listMailRuleEvents({ userId: c.userId, agentId: c.agentId, limit: c.q('limit') })],
].map(([m, pattern, scope, handler, status = 200]) => ({ method: m, parts: pattern.split('/').filter(Boolean), scope, handler, status }));
/** Match method + segments. Returns { route, params }, { methodMismatch }, or null. */
export function matchRoute(method, segments) {
let pathSeen = false;
for (const r of ROUTES) {
if (r.parts.length !== segments.length) continue;
const params = {};
let ok = true;
for (let i = 0; i < r.parts.length; i++) {
const p = r.parts[i];
if (p.startsWith(':')) params[p.slice(1)] = segments[i];
else if (p !== segments[i]) {
ok = false;
break;
}
}
if (!ok) continue;
pathSeen = true;
if (r.method === method) return { route: r, params };
}
return pathSeen ? { methodMismatch: true } : null;
}
export default async function handler(req, res) {
const ctx = { requestId: randomUUID() };
res.setHeader('x-request-id', ctx.requestId);
if (cors(req, res, { methods: 'GET,POST,PUT,PATCH,DELETE,OPTIONS', credentials: true })) return;
const { url, agentId, segments } = parseTarget(req);
const hit = matchRoute(req.method, segments);
if (!hit?.route) {
if (hit?.methodMismatch) return sendError(res, ctx, 405, 'method_not_allowed', `${req.method} is not supported on this path`);
return sendError(res, ctx, 404, 'not_found', 'unknown agent mail route');
}
try {
const principal = await resolvePrincipal(req);
if (!principal) return sendError(res, ctx, 401, 'unauthorized', 'Sign in or send a three.ws API key.');
const scope = hit.route.scope;
if (scope === OWNER_SESSION && principal.source !== 'session') {
return sendError(res, ctx, 403, 'owner_session_required', 'Mail allowlist, cap and rules can only be changed by the owner while signed in at three.ws, never with an API key.');
}
// A write scope implies its read scope, as it does everywhere else in v1.
const scoped =
scope === OWNER_SESSION ||
principal.source === 'session' ||
hasScope(principal.scope, scope) ||
(scope === READ_SCOPE && hasScope(principal.scope, WRITE_SCOPE));
if (!scoped) return sendError(res, ctx, 403, 'insufficient_scope', `This key needs the ${scope} scope.`, { required: scope });
const rl = await limits.apiV1(`mail:${principal.userId}`);
setRateLimitHeaders(res, rl);
if (!rl.success) return sendError(res, ctx, 429, 'rate_limited', 'Too many requests. Slow down and retry shortly.');
let body = {};
const writes = req.method !== 'GET';
if (writes) {
if (principal.source === 'session') {
const v = await checkCsrf(req, principal.userId);
if (!v.ok) return sendError(res, ctx, 403, v.code, v.message);
}
}
if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
try {
body = (await readJson(req)) || {};
} catch (e) {
return sendError(res, ctx, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid JSON body');
}
if (typeof body !== 'object' || Array.isArray(body)) body = {};
}
const c = { agentId, userId: principal.userId, params: hit.params, body, q: (k) => url.searchParams.get(k) };
const data = await hit.route.handler(c);
return send(res, hit.route.status, { data, meta: meta(ctx) });
} catch (e) {
if (e instanceof mail.MailError) return sendError(res, ctx, e.status, e.code, e.message, e.details);
console.error('[agent-mail]', ctx.requestId, e?.message);
return sendError(res, ctx, 500, 'internal_error', 'Something went wrong on our side. Nothing was charged unless the response said so; check the mailbox before retrying.');
}
}