Mail Inboxes API

withPermissionRoute(req, {
  anyPermission: ['mail_inboxes.read'],  // reads
  anyPermission: ['mail_inboxes.manage'], // mutations
  authMode: 'lightweight',               // reads only
}, handler)

interface MailInbox {
  id: string;
  organizationId: string;
  name: string;
  alias: string;           // e.g., "a1b2c3d4" → a1b2c3d4@mail.zappway.ai
  agentId: string | null;  // assigned AI Employee
  aiEnabled: boolean;      // whether AI auto-responds
  datastoreIds: string[];  // connected knowledge
  datasourceIds: string[]; // connected knowledge
  createdAt: string;
  updatedAt: string;
}

// Format: {randomHex}@mail.zappway.ai
// Stored in: mail_inbox.alias
// Inbound emails sent to this address are processed by the inbox

// POST /api/mail-inboxes/check-alias-availability
// Body: { alias: string }
// Returns: { available: boolean }
// Use before custom alias requests (if feature enabled)

// PATCH /api/mail-inboxes/[id]
// Body: {
//   aiEnabled: true,
//   agentId: 'agent_123',
//   datastoreIds: ['ds_abc'],
//   datasourceIds: ['dsc_xyz'],
// }

Email → Forwarded to {alias}@mail.zappway.ai
     ↓
ZappWay email receiving service (MX records)
     ↓
POST to internal webhook (not public API)
     ↓
Lookup inbox by alias
     ↓
Create contact (if new sender)
Create conversation (channel: 'email')
     ↓
If aiEnabled + agentId: trigger AI response
If aiEnabled + no agentId: queue for human
     ↓
AI response → sent via transactional email service

// GET /api/mail-inboxes/unread
// Returns: { [inboxId]: number }
// Used by sidebar badge indicator
// authMode: 'lightweight' for performance