> ## Documentation Index
> Fetch the complete documentation index at: https://api.smartlead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Important Emails

> Retrieve emails marked as important to prioritize high-value conversations

<Note>
  Access your starred/important emails in one view. Essential for prioritizing high-value leads and urgent conversations that need immediate attention.
</Note>

## 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

<ParamField query="api_key" type="string" required>
  Your SmartLead API key
</ParamField>

<ParamField query="fetch_message_history" type="boolean" default="false">
  Include full email thread history

  * `false`: Only latest message (recommended for list views)
  * `true`: Complete conversation thread
</ParamField>

## Request Body

<ParamField body="offset" type="number" default="0">
  Number of records to skip for pagination
</ParamField>

<ParamField body="limit" type="number" default="20">
  Number of records per page (1-20)
</ParamField>

<ParamField body="filters" type="object">
  Advanced filtering options

  <Expandable title="filters properties">
    <ParamField body="filters.search" type="string">
      Search term (max 30 characters)
    </ParamField>

    <ParamField body="filters.leadCategories" type="object">
      Filter by lead category

      <Expandable title="leadCategories properties">
        <ParamField body="leadCategories.unassigned" type="boolean">
          Include uncategorized leads
        </ParamField>

        <ParamField body="leadCategories.isAssigned" type="boolean">
          Include categorized leads
        </ParamField>

        <ParamField body="leadCategories.categoryIdsNotIn" type="array">
          Exclude categories (max 10)
        </ParamField>

        <ParamField body="leadCategories.categoryIdsIn" type="array">
          Include only specific categories (max 10)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters.emailStatus" type="string or array">
      Email engagement status: `Opened`, `Clicked`, `Replied`, `Unsubscribed`, `Bounced`, `Accepted`, `Not Replied`
    </ParamField>

    <ParamField body="filters.campaignId" type="number or array">
      Campaign ID(s) - max 5 campaigns
    </ParamField>

    <ParamField body="filters.emailAccountId" type="number or array">
      Email account ID(s) - max 10 accounts
    </ParamField>

    <ParamField body="filters.campaignTeamMemberId" type="number or array">
      Team member ID(s) - max 10 members
    </ParamField>

    <ParamField body="filters.campaignTagId" type="number or array">
      Campaign tag ID(s) - max 10 tags
    </ParamField>

    <ParamField body="filters.campaignClientId" type="number or array">
      Client ID(s) - max 10 clients
    </ParamField>

    <ParamField body="filters.replyTimeBetween" type="array">
      Date range: `["start_datetime", "end_datetime"]` in ISO 8601 format
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sortBy" type="string" default="REPLY_TIME_DESC">
  Sort order: `REPLY_TIME_DESC` or `SENT_TIME_DESC`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  # Get important interested leads that replied
  payload = {
      "offset": 0,
      "limit": 20,
      "filters": {
          "emailStatus": "Replied",
          "leadCategories": {
              "categoryIdsIn": [1, 2]  # Interested, Meeting Request
          },
          "campaignTagId": 5  # VIP tag
      },
      "sortBy": "REPLY_TIME_DESC"
  }

  response = requests.post(
      "https://server.smartlead.ai/api/v1/master-inbox/important",
      params={"api_key": API_KEY, "fetch_message_history": False},
      json=payload
  )

  result = response.json()
  print(f"🌟 {result.get('total_count', 0)} important replies")

  for msg in result.get('messages', []):
      lead = msg['lead']
      category = msg.get('category', {}).get('name', 'Uncategorized')
      print(f"  {lead['email']} - {category}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = 'YOUR_API_KEY';

  // Get today's important replies
  async function getTodayImportantReplies() {
    const today = new Date();
    today.setHours(0, 0, 0, 0);
    
    const payload = {
      filters: {
        emailStatus: 'Replied',
        replyTimeBetween: [
          today.toISOString(),
          new Date().toISOString()
        ]
      },
      sortBy: 'REPLY_TIME_DESC',
      limit: 20
    };

    const response = await fetch(
      `https://server.smartlead.ai/api/v1/master-inbox/important?api_key=${API_KEY}`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload)
      }
    );

    const result = await response.json();
    console.log(`⭐ ${result.total_count} important replies today`);
    return result;
  }
  ```
</RequestExample>

## Response Example

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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
  }
  ```
</ResponseExample>

## Common Workflows

### VIP Daily Digest

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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
```

## Related Endpoints

* [Get Inbox Messages](/api-reference/inbox/get-messages) - All replies
* [Get Unread Replies](/api-reference/inbox/get-unread) - Unread messages
* [Get Assigned to Me](/api-reference/inbox/get-assigned) - Your assigned leads