gb/EMAIL-CRM-CAMPAIGNS-INTEGRATION.md

Email + CRM + Campaigns Integration Specification

AI-Powered Cross-App Features (Optional)

Architecture Principle

Email (Standalone)
  ↓ (optional integration)
  ├─→ CRM (if enabled)
  └─→ Campaigns (if enabled)

Rules:

• Email works independently
• CRM features appear ONLY if CRM is enabled
• Campaign features appear ONLY if Campaigns is enabled
• All integrations are AI-powered

🔗 Email → CRM Integration (When CRM Enabled)

1. Auto-Create Lead from Email

What: AI detects potential leads in emails and suggests creating CRM lead

Implementation:

<!-- Only shows if CRM is enabled -->
<div class="email-crm-suggestion" style="background: #f0f9ff; padding: 12px;">
    <svg><!-- lightbulb icon --></svg>
    <span>This looks like a sales inquiry. Create a lead?</span>
    <button onclick="createLeadFromEmail()">Create Lead</button>
    <button onclick="dismissSuggestion()">Dismiss</button>
</div>

<script>
async function createLeadFromEmail() {
    const email = getCurrentEmail();
    
    // AI extracts lead info
    const response = await fetch('/api/ai/extract-lead', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            from: email.from,
            subject: email.subject,
            body: email.body
        })
    });
    
    const leadData = await response.json();
    
    // Pre-fill lead form
    openLeadForm(leadData);
}

// Check if CRM is enabled
if (window.crmEnabled) {
    analyzeEmailForLeads();
}
</script>

2. Link Email to Existing Contact/Deal

What: Show CRM context when viewing emails from known contacts

Implementation:

<!-- CRM sidebar panel (only if CRM enabled) -->
<div class="email-crm-panel" id="crmPanel" style="display: none;">
    <h4>CRM Information</h4>
    
    <div class="crm-contact-card">
        <img src="/api/avatar/john@company.com" class="contact-avatar">
        <div class="contact-info">
            <strong>John Doe</strong>
            <span>CEO at Acme Corp</span>
            <a href="/suite/crm?contact=123">View in CRM →</a>
        </div>
    </div>
    
    <div class="crm-deals">
        <h5>Active Deals</h5>
        <div class="deal-item">
            <span>Enterprise License</span>
            <span class="deal-value">$50,000</span>
            <span class="deal-stage">Negotiation</span>
        </div>
    </div>
    
    <div class="crm-history">
        <h5>Recent Activity</h5>
        <div class="activity-item">
            <span>📞 Call - 2 days ago</span>
        </div>
        <div class="activity-item">
            <span>📧 Email sent - 5 days ago</span>
        </div>
    </div>
    
    <button onclick="logEmailToCrm()">Log to CRM</button>
</div>

<script>
async function loadCrmContext(emailFrom) {
    if (!window.crmEnabled) return;
    
    const response = await fetch(`/api/crm/contact/by-email?email=${emailFrom}`);
    const contact = await response.json();
    
    if (contact) {
        document.getElementById('crmPanel').style.display = 'block';
        populateCrmPanel(contact);
    }
}
</script>

3. Track Email in Deal Timeline

What: Automatically log emails to deal activity timeline

Implementation:

async function logEmailToCrm() {
    const email = getCurrentEmail();
    
    await fetch('/api/crm/activity/log', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            type: 'email',
            contact_email: email.from,
            subject: email.subject,
            body: email.body,
            timestamp: email.date
        })
    });
    
    showNotification('Email logged to CRM');
}

// Auto-log if setting enabled
if (window.crmEnabled && window.crmAutoLog) {
    logEmailToCrm();
}

📧 Email → Campaigns Integration (When Campaigns Enabled)

4. Add Email Sender to Campaign List

What: Quick-add email sender to marketing list

Implementation:

<!-- Only shows if Campaigns is enabled -->
<div class="email-campaign-actions">
    <button onclick="addToList()">
        <svg><!-- list icon --></svg>
        Add to List
    </button>
</div>

<div class="list-selector-modal" id="listSelector" style="display: none;">
    <h4>Add to Campaign List</h4>
    
    <div class="list-options" hx-get="/api/crm/lists" hx-trigger="load">
        <!-- Lists loaded here -->
    </div>
    
    <button onclick="createNewList()">+ New List</button>
</div>

<script>
async function addToList() {
    if (!window.campaignsEnabled) return;
    
    const email = getCurrentEmail();
    document.getElementById('listSelector').style.display = 'block';
    
    // Pre-fill with sender info
    document.getElementById('contactEmail').value = email.from;
    document.getElementById('contactName').value = extractName(email.from);
}
</script>

5. Track Campaign Email Opens

What: Show if email is from a campaign and track engagement

Implementation:

<!-- Campaign badge (only if from campaign) -->
<div class="campaign-badge">
    <svg><!-- megaphone icon --></svg>
    <span>From Campaign: "Welcome Series"</span>
    <a href="/suite/campaigns?id=456">View Campaign →</a>
</div>

<div class="campaign-stats">
    <span>Opened: Yes</span>
    <span>Clicked: 2 links</span>
    <span>Converted: No</span>
</div>

<script>
async function checkIfCampaignEmail(emailId) {
    if (!window.campaignsEnabled) return;
    
    const response = await fetch(`/api/crm/campaigns/check-email?id=${emailId}`);
    const { is_campaign, campaign_id } = await response.json();
    
    if (is_campaign) {
        showCampaignBadge(campaign_id);
    }
}
</script>

🤖 AI-Powered Cross-App Features

6. Smart Reply Suggestions (AI + CRM Context)

What: AI generates replies using CRM deal context

Implementation:

async function generateSmartReply() {
    const email = getCurrentEmail();
    let context = { email };
    
    // Add CRM context if available
    if (window.crmEnabled) {
        const crmData = await fetch(`/api/crm/contact/by-email?email=${email.from}`);
        context.crm = await crmData.json();
    }
    
    // Generate reply with full context
    const response = await fetch('/api/ai/generate-reply', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(context)
    });
    
    const { suggestions } = await response.json();
    
    showReplySuggestions(suggestions);
}

7. Lead Scoring from Email Behavior

What: AI scores leads based on email engagement

Implementation:

async function updateLeadScore(emailId) {
    if (!window.crmEnabled) return;
    
    const email = getCurrentEmail();
    
    // Calculate engagement score
    const score = {
        opened: email.opened ? 10 : 0,
        replied: email.replied ? 20 : 0,
        clicked_links: email.clicks * 5,
        response_time: calculateResponseScore(email.response_time)
    };
    
    const totalScore = Object.values(score).reduce((a, b) => a + b, 0);
    
    // Update in CRM
    await fetch('/api/crm/lead/score', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            email: email.from,
            score: totalScore,
            source: 'email_engagement'
        })
    });
}

8. Campaign Performance in Email

What: Show campaign metrics when viewing campaign emails

Implementation:

<!-- Campaign performance panel -->
<div class="campaign-performance" id="campaignPerf" style="display: none;">
    <h4>Campaign Performance</h4>
    
    <div class="perf-metrics">
        <div class="metric">
            <span class="metric-value">1,250</span>
            <span class="metric-label">Sent</span>
        </div>
        <div class="metric">
            <span class="metric-value">45%</span>
            <span class="metric-label">Opened</span>
        </div>
        <div class="metric">
            <span class="metric-value">12%</span>
            <span class="metric-label">Clicked</span>
        </div>
        <div class="metric">
            <span class="metric-value">3%</span>
            <span class="metric-label">Converted</span>
        </div>
    </div>
    
    <button onclick="viewFullCampaign()">View Full Campaign →</button>
</div>

9. Unified Contact View

What: See all interactions (emails + CRM + campaigns) in one place

Implementation:

<div class="unified-contact-view">
    <div class="contact-header">
        <img src="/api/avatar/john@company.com" class="avatar-large">
        <div class="contact-details">
            <h3>John Doe</h3>
            <span>john@company.com</span>
            <span>CEO at Acme Corp</span>
        </div>
    </div>
    
    <div class="contact-timeline">
        <!-- Email interactions -->
        <div class="timeline-item email">
            <span class="timeline-icon">📧</span>
            <div class="timeline-content">
                <strong>Email received</strong>
                <p>Re: Project proposal</p>
                <span class="timeline-date">2 hours ago</span>
            </div>
        </div>
        
        <!-- CRM activity (if enabled) -->
        <div class="timeline-item crm" data-requires="crm">
            <span class="timeline-icon">📞</span>
            <div class="timeline-content">
                <strong>Call completed</strong>
                <p>Discussed pricing</p>
                <span class="timeline-date">Yesterday</span>
            </div>
        </div>
        
        <!-- Campaign interaction (if enabled) -->
        <div class="timeline-item campaign" data-requires="campaigns">
            <span class="timeline-icon">📨</span>
            <div class="timeline-content">
                <strong>Campaign email opened</strong>
                <p>Welcome Series - Email 2</p>
                <span class="timeline-date">3 days ago</span>
            </div>
        </div>
    </div>
</div>

<script>
// Hide items that require disabled features
document.querySelectorAll('[data-requires]').forEach(el => {
    const feature = el.dataset.requires;
    if (!window[`${feature}Enabled`]) {
        el.style.display = 'none';
    }
});
</script>

10. AI Email Categorization

What: AI automatically categorizes emails (sales, support, marketing)

Implementation:

async function categorizeEmail(emailId) {
    const email = getCurrentEmail();
    
    const response = await fetch('/api/ai/categorize-email', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            from: email.from,
            subject: email.subject,
            body: email.body
        })
    });
    
    const { category, confidence } = await response.json();
    
    // Route based on category
    if (category === 'sales' && window.crmEnabled) {
        suggestCreateLead();
    } else if (category === 'marketing' && window.campaignsEnabled) {
        suggestAddToList();
    }
    
    // Add category badge
    addCategoryBadge(category);
}

🔧 Backend API Requirements

# Feature Detection
GET    /api/features/enabled             - Check which features are enabled

# Email → CRM
POST   /api/ai/extract-lead              - Extract lead info from email
GET    /api/crm/contact/by-email         - Get contact by email
POST   /api/crm/activity/log             - Log email to CRM

# Email → Campaigns
GET    /api/crm/lists                    - Get campaign lists
POST   /api/crm/lists/:id/contacts       - Add contact to list
GET    /api/crm/campaigns/check-email    - Check if email is from campaign

# AI Features
POST   /api/ai/generate-reply            - Generate smart reply
POST   /api/ai/categorize-email          - Categorize email
POST   /api/crm/lead/score               - Update lead score

# Unified View
GET    /api/contact/timeline             - Get all interactions

📊 Database Schema

-- Feature flags
CREATE TABLE feature_flags (
    id UUID PRIMARY KEY,
    org_id UUID NOT NULL,
    feature VARCHAR(50),  -- 'crm', 'campaigns'
    enabled BOOLEAN DEFAULT FALSE
);

-- Email-CRM links
CREATE TABLE email_crm_links (
    id UUID PRIMARY KEY,
    email_id UUID,
    contact_id UUID REFERENCES crm_contacts(id),
    deal_id UUID REFERENCES crm_opportunities(id),
    logged_at TIMESTAMP
);

-- Email-Campaign links
CREATE TABLE email_campaign_links (
    id UUID PRIMARY KEY,
    email_id UUID,
    campaign_id UUID REFERENCES campaigns(id),
    list_id UUID REFERENCES contact_lists(id),
    sent_at TIMESTAMP
);

-- AI categorization
ALTER TABLE emails ADD COLUMN ai_category VARCHAR(50);
ALTER TABLE emails ADD COLUMN ai_confidence FLOAT;

✅ Implementation Priority

Phase 1: Feature Detection (Week 1)

1. Check if CRM/Campaigns enabled
2. Show/hide integration features
3. Feature flag system

Phase 2: CRM Integration (Week 2)

4. Auto-create lead from email
5. Link email to contact/deal
6. Track email in deal timeline

Phase 3: Campaigns Integration (Week 3)

7. Add sender to campaign list
8. Track campaign email opens
9. Show campaign performance

Phase 4: AI Features (Week 4)

10. Smart reply with CRM context
11. Lead scoring from email
12. Unified contact view
13. AI email categorization

🧪 Testing Checklist

Email Standalone:

• Email works without CRM
• Email works without Campaigns
• All email features functional

With CRM Enabled:

• CRM panel appears in email
• Create lead from email
• Link email to contact
• Log email to deal timeline

With Campaigns Enabled:

• Add sender to list
• Track campaign opens
• Show campaign metrics

AI Features:

• Smart reply uses CRM context
• Lead score updates from engagement
• Unified timeline shows all interactions
• AI categorizes emails correctly