# AI Email Insights

_AI Features_

Per-contact email intelligence: best time to send, response likelihood prediction, engagement trends, and AI-generated subject lines. Pure computation over your existing TrackingEvent + Message data — no AI cost for the metrics, only for subject-line generation.

## Steps
1. When composing an email to any contact (Conversations > New Email), the compose modal automatically shows a "Best time: Tue 10am" hint near the send button if there's enough engagement data.
2. Below the To field: response likelihood badge — HIGH / MEDIUM / LOW based on the contact's historical reply rate + recency.
3. Subject-line field: click "✨ Suggest" to get 3 AI-generated subject options with reasoning and a predicted open-rate band (high/medium/low). Uses the light tier (one cheap call per click).
4. On the contact detail page, the Conversation Intelligence card's engagement metrics grid shows: open rate, reply rate, avg response time, message frequency.
5. Org-level: GET /ai/email-insights/org returns aggregate open/click/response rates, best send time across the org, and contacts with declining engagement (early-warning).

## Tips
- Best send time is bucketed by hour of day from the contact's historical opens. Contacts with <5 opens fall back to the org's average best time, with a "low confidence" caveat.
- Response likelihood: HIGH = reply rate > 60% AND last reply <7 days, MEDIUM = 30–60% OR last reply 7–30 days, LOW = <30% OR last reply >30 days.
- Subject-line suggestions are tuned by the contact's industry + any past subjects that got opens. Quality compounds as your sent-mail history grows.
- Device preference (mobile vs desktop) is inferred from User-Agent on TrackingEvent rows. Useful for choosing copy length: mobile readers skim subject lines harder.

## Example
A salesperson is composing a weekly check-in to a long-time customer. Compose modal shows: "Best time: Thursday 7am". She schedules instead of sending. Reply rate on her batch goes from her usual 18% to 34% — same emails, better timing.

## Troubleshooting
- **No best-time hint on the compose modal** — Contact has fewer than 5 email opens in their TrackingEvent history — too few signal points to recommend a time. Fix: Either send normally and let the data accumulate, or rely on the org's aggregate best time (Settings > Communications > AI Email Insights).
- **"✨ Suggest" subject-line button does nothing** — Either AI quota exhausted, the message context is empty, or the contact isn't set as a recipient yet. Fix: Set the To field first; type a sentence or two of body so the model has context; check Settings > AI Usage for quota.
- **Response likelihood always says "LOW"** — You're sending to contacts who genuinely don't reply often — the metric is honest, not motivational. Fix: Audit the contact list — if you're emailing a stale segment, run a re-engagement campaign first or move them to a nurture sequence.

## Plans
Included in every plan. Metrics are pure computation (free). Subject-line suggestions use the light tier (small per-click cost on any provider). Toggleable per-org under Settings > AI Usage > AI Features (key: email_insights).