CRM: Email integration

Technical specification for email integration in the PestControlOS CRM (PWA).

Architecture

Gmail API: Secure Gmail API integration via Firebase Cloud Functions. Client does not hold Gmail credentials; all send operations go through a callable Cloud Function that uses server-side OAuth or service account to send email.
Shared account: Optional shared organisational email account (e.g. support@company.com). Credentials or tokens stored securely (e.g. Firebase config or Secret Manager); access restricted to super_admin. Token storage restricted to super_admin; other roles cannot view or change email credentials.

Compose and send: User composes in CRM UI; payload (to, subject, body, optional attachment refs) sent to callable. Function validates, rate-limits, then calls Gmail API to send. Attachments: documents from Firebase Storage; function fetches via admin SDK and attaches to message.
Template-based messaging: Templates stored in Firestore or config; body and subject filled from template + variables. Used for quotes, follow-ups, standard communications.
Recent email history: Log sent emails in Firestore (e.g. emailHistory collection) for audit and "recent sent" UI. Fields: to, subject, timestamp, userId. Optional: store message ID for threading.
Server-side rate limiting: Limit sends per user or per org per hour to avoid Gmail quotas and abuse. Counters in Firestore or in-memory; function rejects when exceeded.
Role-restricted access: Technicians cannot send emails (UI hidden or disabled; callable rejects if role is tech). Only admin and super_admin can trigger send. Enforced in callable: check context.auth.token.role or Firestore staff lookup.

No client-side OAuth for Gmail; no exposure of tokens to browser. All token access server-side. Validate to/from and content in callable to prevent abuse (e.g. no arbitrary recipient lists, size limits).