email-agent

# Email Agent Skill

## Overview
The Email Agent is responsible for:
1. **Processing unprocessed emails** from a workspace
2. **Extracting sender information** and linking to existing contacts
3. **Analyzing email content** for intents and sentiment
4. **Updating CRM contacts** with interaction data
5. **Creating audit logs** for all actions

## How to Use This Agent

### Trigger
User says: "Process emails for Duncan's workspace" or "Analyze unprocessed emails"

### What the Agent Does

#### 1. Fetch Unprocessed Emails
```
Call: convex query emails.getUnprocessed({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  workspaceId: "kh72b1cng9h88691sx4x7krt2h7v7dehh",
  limit: 50
})
```

Returns array of emails not yet processed (`isProcessed: false`)

#### 2. For Each Email

**Step A: Extract Sender Email**
```
From: "john@techstartup.com"
Extract: sender_email = "john@techstartup.com"
```

**Step B: Link to Contact**
```
Call: convex query contacts.getByEmail({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  workspaceId: "kh72b1cng9h88691sx4x7krt2h7v7dehh",
  email: "john@techstartup.com"
})
```

If exists → `contactId = found_contact._id`
If NOT exists → Create new contact with:
  - email: sender_email
  - name: extracted from email or "Unknown"
  - source: "email"
  - status: "lead"

**Step C: Analyze Email Content**

Extract these intent keywords:
- "interested" / "partnership" / "collaboration" → intent: **inquiry**
- "proposal" / "quote" / "pricing" → intent: **proposal**
- "issue" / "problem" / "help" → intent: **complaint**
- "?" / "how" / "what" / "when" → intent: **question**
- "follow up" / "re:" → intent: **followup**
- "meeting" / "call" / "sync" / "schedule" → intent: **meeting**

Multiple intents can apply to one email.

**Step D: Analyze Sentiment**

Read email tone:
- Positive indicators: "excited", "love", "great", "thank you", "appreciate"
- Negative indicators: "problem", "issue", "concerned", "unhappy", "urgent"
- Neutral: Standard business tone

Classify as: **positive**, **neutral**, or **negative**

**Step E: Generate Summary**

Create 1-2 sentence summary of email intent:
```
Example: "John from TechStartup is inquiring about Q4 marketing services and partnership opportunities."
```

**Step F: Mark as Processed**

Call: convex mutation emails.markProcessed({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  emailId: "email_id_from_step_1",
  contactId: "contact_id_from_step_b",
  intents: ["inquiry", "partnership"],
  sentiment: "positive",
  summary: "John inquiring about Q4 partnership"
})

**Step G: Update Contact**

If this is a NEW interaction, update:
```
Call: convex mutation contacts.updateAiScore({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  contactId: "contact_id",
  score: 75  // Increase score based on engagement
})

Call: convex mutation contacts.addNote({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  contactId: "contact_id",
  note: "Email from John: Inquiring about Q4 partnership. Sentiment: positive. Intents: inquiry, partnership"
})
```

**Step H: Log Audit Event**

Call: convex mutation system.logAudit({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  action: "email_processed",
  resource: "email",
  resourceId: "email_id",
  agent: "email-agent",
  details: JSON.stringify({
    from: "john@techstartup.com",
    intents: ["inquiry", "partnership"],
    sentiment: "positive",
    contactLinked: true
  }),
  status: "success"
})

### Error Handling

If something fails:
```
Call: convex mutation system.logAudit({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  action: "email_processing_error",
  resource: "email",
  resourceId: "email_id",
  agent: "email-agent",
  details: JSON.stringify({ error: "error message" }),
  status: "error",
  errorMessage: "description"
})
```

Then continue to next email (don't stop).

## Summary Output

After processing all emails, provide:
```
✅ Email Processing Complete

Total processed: X
Successfully linked: X
New contacts created: X
Intents extracted: X
Average sentiment: X

Contacts engaged:
- John Smith (TechStartup) - positive, inquiry
- Lisa Johnson (eCommerce) - positive, proposal
- Carlos Rodriguez (Agency) - positive, collaboration

Next steps:
1. Review high-priority contacts (positive sentiment + inquiry)
2. Generate followup emails for warm leads
3. Schedule meetings with decision-makers
```

## Key Points

- **Org isolation**: All operations scoped to `orgId`
- **Workspace scope**: Process only emails from target workspace
- **Contact linking**: Always try to link email to existing contact
- **AI scoring**: Increase contact score when they engage (email received)
- **Audit trail**: Log every action for compliance

---

## Example: Processing One Email

**Input Email:**
```
From: john@techstartup.com
Subject: Interested in your services
Body: Hi Duncan, we're looking to revamp our marketing strategy for Q4. Would love to chat about partnership opportunities.
```

**Agent Process:**

1. ✅ Extract sender: `john@techstartup.com`
2. ✅ Query contact: Found "John Smith" in contacts
3. ✅ Extract intents: `["inquiry", "partnership"]`
4. ✅ Analyze sentiment: `"positive"` (enthusiastic tone)
5. ✅ Generate summary: "John inquiring about Q4 marketing strategy and partnership"
6. ✅ Mark email processed with contact link
7. ✅ Increase contact AI score from 68 → 78
8. ✅ Add note with timestamp and details
9. ✅ Log audit event with full context

**Result:**
- Contact updated with fresh interaction data
- Audit trail shows agent processed email
- Contact now appears in "high-value prospects" due to increased score