Email Agent

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

2. For Each Email

Step A: Extract Sender Email

From: "[email protected]"
Extract: sender_email = "[email protected]"

Step B: Link to Contact

Call: convex query contacts.getByEmail({
  orgId: "k57akqzf14r07d9q3pbf9kebvn7v7929",
  workspaceId: "kh72b1cng9h88691sx4x7krt2h7v7dehh",
  email: "[email protected]"
})

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: "[email protected]", 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: [email protected]
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: [email protected]
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