Skip to main content
POST
/
api
/
v1
/
master-inbox
/
important
curl -X POST "https://server.smartlead.ai/api/v1/master-inbox/important?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 20,
    "filters": {
      "emailStatus": "Replied",
      "leadCategories": {
        "categoryIdsIn": [1, 2]
      }
    },
    "sortBy": "REPLY_TIME_DESC"
  }'

{
  "messages": [
    {
      "id": "msg_important_456",
      "campaign_lead_map_id": "2433664091",
      "lead": {
        "email": "ceo@bigcorp.com",
        "first_name": "Sarah",
        "last_name": "Williams",
        "title": "CEO",
        "company": "BigCorp Inc"
      },
      "campaign": {
        "id": 12345,
        "name": "Enterprise Outreach"
      },
      "last_message": {
        "subject": "Re: Strategic Partnership",
        "body": "This looks very promising. Can we set up a call with my team?",
        "received_at": "2025-01-20T10:30:00Z"
      },
      "email_status": "Replied",
      "category": {
        "id": 2,
        "name": "Meeting Request"
      },
      "is_important": true,
      "importance_score": 95,
      "tags": ["enterprise", "c-level", "hot-lead"]
    }
  ],
  "total_count": 1
}
Access your starred/important emails in one view. Essential for prioritizing high-value leads and urgent conversations that need immediate attention.

​
Overview

Retrieves all emails marked as important by users or automatically flagged by the system. This endpoint helps you focus on the most critical conversations and high-value leads. Key Features:
  • Quick access to flagged important conversations
  • Same comprehensive filtering as other inbox endpoints
  • Combine manual flags with automatic importance scoring
  • Priority queue for urgent follow-ups
Importance Criteria:
  • Manual flags: User-starred messages
  • High-value indicators: Enterprise leads, large deal sizes
  • Urgent keywords: “Urgent”, “ASAP”, “Budget approved”
  • VIP contacts: Tagged as important accounts
  • Executive responses: C-level replies
Common Use Cases:
  • VIP management: Track high-value account communications
  • Urgent response queue: Handle time-sensitive requests
  • Deal pipeline: Monitor active opportunities
  • Executive visibility: Surface C-level conversations
  • Team priorities: Share important leads across team

​
Query Parameters

​
api_key
string
required
Your SmartLead API key
​
fetch_message_history
boolean
default:"false"
Include full email thread history
  • false: Only latest message (recommended for list views)
  • true: Complete conversation thread

​
Request Body

​
offset
number
default:"0"
Number of records to skip for pagination
​
limit
number
default:"20"
Number of records per page (1-20)
​
filters
object
Advanced filtering options
​
sortBy
string
default:"REPLY_TIME_DESC"
Sort order: REPLY_TIME_DESC or SENT_TIME_DESC
curl -X POST "https://server.smartlead.ai/api/v1/master-inbox/important?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 20,
    "filters": {
      "emailStatus": "Replied",
      "leadCategories": {
        "categoryIdsIn": [1, 2]
      }
    },
    "sortBy": "REPLY_TIME_DESC"
  }'

​
Response Example

{
  "messages": [
    {
      "id": "msg_important_456",
      "campaign_lead_map_id": "2433664091",
      "lead": {
        "email": "ceo@bigcorp.com",
        "first_name": "Sarah",
        "last_name": "Williams",
        "title": "CEO",
        "company": "BigCorp Inc"
      },
      "campaign": {
        "id": 12345,
        "name": "Enterprise Outreach"
      },
      "last_message": {
        "subject": "Re: Strategic Partnership",
        "body": "This looks very promising. Can we set up a call with my team?",
        "received_at": "2025-01-20T10:30:00Z"
      },
      "email_status": "Replied",
      "category": {
        "id": 2,
        "name": "Meeting Request"
      },
      "is_important": true,
      "importance_score": 95,
      "tags": ["enterprise", "c-level", "hot-lead"]
    }
  ],
  "total_count": 1
}

​
Common Workflows

​
VIP Daily Digest

def get_vip_daily_digest():
    """Generate daily digest of important VIP interactions"""
    from datetime import datetime, timedelta
    
    today_start = datetime.now().replace(hour=0, minute=0, second=0)
    
    payload = {
        "filters": {
            "emailStatus": "Replied",
            "campaignTagId": 5,  # VIP tag
            "replyTimeBetween": [
                today_start.isoformat() + 'Z',
                datetime.now().isoformat() + 'Z'
            ]
        },
        "sortBy": "REPLY_TIME_DESC"
    }
    
    response = get_important_emails(payload)
    messages = response.get('messages', [])
    
    print(f"📊 VIP Daily Digest - {len(messages)} interactions\n")
    
    for msg in messages:
        lead = msg['lead']
        category = msg.get('category', {}).get('name', 'Uncategorized')
        print(f"⭐ {lead.get('title', '')} at {lead.get('company', '')}")
        print(f"   {lead['email']} - {category}")
        print(f"   {msg['last_message']['subject']}\n")
    
    return messages

​
Executive Visibility Report

def generate_executive_report():
    """Create executive summary of important conversations"""
    payload = {
        "filters": {
            "emailStatus": "Replied",
            "leadCategories": {
                "categoryIdsIn": [1, 2]  # Interested, Meeting Request
            }
        },
        "limit": 20
    }
    
    response = get_important_emails(payload)
    messages = response.get('messages', [])
    
    # Categorize by type
    meeting_requests = [m for m in messages 
                       if m.get('category', {}).get('id') == 2]
    interested_leads = [m for m in messages 
                       if m.get('category', {}).get('id') == 1]
    
    print("🎯 Executive Summary - Important Conversations")
    print(f"   Total: {len(messages)}")
    print(f"   Meeting Requests: {len(meeting_requests)}")
    print(f"   Interested Leads: {len(interested_leads)}")
    
    # List top priorities
    print("\n🔥 Top Priorities:")
    for i, msg in enumerate(messages[:5], 1):
        print(f"   {i}. {msg['lead']['company']} - {msg['last_message']['subject']}")

​
Importance Scoring

def score_and_flag_important(lead_map_id, criteria):
    """Auto-score and flag leads as important based on criteria"""
    score = 0
    reasons = []
    
    # Scoring rules
    if criteria.get('title') in ['CEO', 'CTO', 'VP', 'Director']:
        score += 30
        reasons.append("C-level/VP")
    
    if criteria.get('company_size') == 'enterprise':
        score += 25
        reasons.append("Enterprise")
    
    if criteria.get('deal_size', 0) > 50000:
        score += 20
        reasons.append("High deal value")
    
    if criteria.get('response_time_hours', 999) < 4:
        score += 15
        reasons.append("Quick response")
    
    if 'budget' in criteria.get('message_body', '').lower():
        score += 10
        reasons.append("Budget mentioned")
    
    # Flag as important if score > 50
    if score >= 50:
        flag_as_important(lead_map_id)
        print(f"⭐ Flagged as important (score: {score})")
        print(f"   Reasons: {', '.join(reasons)}")
        return True
    
    return False