# Email Platform Integration -- Technical Implementation Guide

## META
- relevance: ENGINEERING -- how LLMHosts platform uses email accounts
- created: 2026-02-13
- updated: 2026-02-19 — transactional now Resend (live)

## CURRENT STATE (2026-02-19)

- **Transactional (live)**: Resend API. Implementation: `frontend/src/lib/email/send.ts` (verification, password reset, contact form to hello@). Requires `RESEND_API_KEY` in env; production key + domain verification = issue #187 (see `docs/launch/NEED-FROM-YOU.md`).
- **Support / founder**: Zoho Mail (manual or future IMAP/Conductor) per below.

## ARCHITECTURE OVERVIEW

```
User Actions (signup, support, etc.)
  │
  ├─→ Transactional Emails (no-reply@llmhosts.com)
  │     └─→ Resend API (live) — frontend/src/lib/email/send.ts
  │           └─→ verification, password reset, contact → hello@llmhosts.com
  │
  ├─→ Support Emails (support@llmhosts.com)
  │     └─→ Zoho IMAP polling (Phase 3 — not yet implemented)
  │           ├─→ AI Auto-Reply (Conductor classifies + responds)
  │           └─→ Escalation → Admin Dashboard ticket queue
  │
  └─→ Founder Email (brendon@llmhosts.com)
        └─→ Manual via Zoho webmail or IMAP client (not programmatic)
```

## INTEGRATION POINTS

### 1. Transactional Email — Resend (Live)

**How**: Next.js frontend sends via Resend SDK. Single client in `frontend/src/lib/email/send.ts`: `sendVerificationEmail`, `sendPasswordResetEmail`, `resendVerificationEmail`, `sendContactEmail`.

**Env**: `RESEND_API_KEY` (required in production for real delivery). Optional: `EMAIL_FROM` (default `LLMHosts <noreply@llmhosts.com>`).

**Production**: Set key in production env and verify domain in Resend (SPF, DKIM, DMARC). See issue #187 and `docs/launch/NEED-FROM-YOU.md`.

**Legacy note**: Zoho SMTP was Phase 1 plan; we use Resend only for transactional now.

### 2. Support Email Polling (Phase 3)

**How**: FastAPI service polls support@llmhosts.com via IMAP, classifies incoming emails, auto-replies or escalates.

```python
# services/api/support_poller.py (conceptual)
import imaplib
import email

IMAP_HOST = "imap.zoho.com"
IMAP_PORT = 993
IMAP_USER = "support@llmhosts.com"
IMAP_PASS = os.environ["ZOHO_SUPPORT_PASSWORD"]

async def poll_support_inbox():
    mail = imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT)
    mail.login(IMAP_USER, IMAP_PASS)
    mail.select("INBOX")
    
    # Search for unread emails
    status, messages = mail.search(None, "UNSEEN")
    
    for msg_id in messages[0].split():
        status, data = mail.fetch(msg_id, "(RFC822)")
        raw = email.message_from_bytes(data[0][1])
        
        sender = raw["From"]
        subject = raw["Subject"]
        body = extract_body(raw)
        
        # Classify with Conductor Brain
        classification = await classify_support_request(subject, body)
        
        if classification.confidence > 0.8 and classification.can_auto_resolve:
            await send_auto_reply(sender, subject, classification.response)
            await log_ticket(sender, subject, status="auto_resolved")
        else:
            await create_escalation_ticket(sender, subject, body, classification)
    
    mail.logout()
```

**Env vars needed**:
```
ZOHO_SUPPORT_EMAIL=support@llmhosts.com
ZOHO_SUPPORT_PASSWORD=<from docs/secure/email-credentials.md>
```

### 3. Admin Dashboard Email Integration (Phase 3)

**What the admin sees**:
- Ticket queue: all support requests (auto-resolved + escalated)
- Each ticket shows: sender, subject, AI classification, AI draft response
- Admin can: approve AI response, edit and send, reply manually, close ticket

## DOCKER CONFIGURATION

All email credentials go in `.env` file (gitignored):

```env
# .env (NEVER COMMITTED)
ZOHO_NOREPLY_EMAIL=no-reply@llmhosts.com
ZOHO_NOREPLY_PASSWORD=8XXjQuJ4CHNfCcitR#aD!Eoc
ZOHO_SUPPORT_EMAIL=support@llmhosts.com
ZOHO_SUPPORT_PASSWORD=PXUa24DXM9xagc^PyiyR=E=7
```

Docker Compose mounts .env:
```yaml
services:
  api:
    env_file: .env
    # ...
```

## DNS RECORDS SUMMARY (Post-Setup State)

After Brendon completes setup, LLMHosts.com DNS at GoDaddy should have:

| Type | Host | Value |
|------|------|-------|
| MX | @ | mx.zoho.com (priority 10) |
| MX | @ | mx2.zoho.com (priority 20) |
| MX | @ | mx3.zoho.com (priority 50) |
| TXT | @ | v=spf1 include:zohomail.com -all |
| TXT | zoho._domainkey | v=DKIM1; k=rsa; p=[generated key] |
| TXT | _dmarc | v=DMARC1; p=none; rua=mailto:brendon@llmhosts.com |

**Future additions** (when adding Resend for transactional):
- Update SPF: `v=spf1 include:zohomail.com include:resend.com -all`
- Add Resend DKIM record (provided during Resend setup)

## ZOHO FREE TIER SENDING LIMITS

| Metric | Limit | Impact |
|--------|-------|--------|
| External emails/hour | 50-500 (reputation-based) | Fine for Phase 1 (<50 users). Upgrade to Resend API before Phase 3 launch. |
| Internal emails/hour | 1,000 | Not relevant (no internal team email) |
| Recipients per message | 100 external | Fine for transactional (1:1 emails) |
| Attachment size | 25 MB | Fine for text emails |

## IMPLEMENTATION PHASES

### Phase 1 (MVP): Basic Transactional
- Send signup confirmation, password reset via Zoho SMTP (no-reply@)
- brendon@ used manually via Zoho webmail
- support@ not yet programmatic (manual monitoring)

### Phase 3 (Growth): Full Email Integration
- AI auto-reply system on support@
- Admin dashboard ticket queue
- Upgrade transactional to Resend API (higher volume, better analytics)
- Email templates with LLMHosts branding

### Phase 4 (Scale): Production Hardening
- Move to Zoho Mail Lite ($1/mo) if hitting free tier limits
- Advanced email analytics and monitoring
- SLA tracking for support response times
