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

{
  "messages": [
    {
      "id": "msg_456",
      "campaign_lead_map_id": "9876543210",
      "lead": {
        "email": "sarah@startup.io",
        "first_name": "Sarah",
        "last_name": "Johnson"
      },
      "campaign": {
        "id": 12345,
        "name": "SaaS Outreach"
      },
      "subsequence": {
        "id": 789,
        "name": "Pricing Discussion"
      },
      "last_message": {
        "subject": "Re: Pricing Question",
        "body": "Thanks for the detailed pricing...",
        "received_at": "2025-01-20T10:15:00Z"
      },
      "email_status": "Replied",
      "category": {
        "id": 1,
        "name": "Interested"
      }
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 20
}
Access emails using your custom saved views/filters. Create complex filter combinations and save them for quick access to specific inbox segments.

​
Overview

Retrieves emails based on custom saved views. This endpoint allows you to create and access sophisticated filter combinations for segmenting your inbox. Key Features:
  • Save complex filter combinations as reusable views
  • Quick access to frequently used inbox segments
  • Additional subsequence filtering capability
  • All standard inbox filtering options available
Common Custom Views:
  • “Hot Leads”: Replied + High Priority + Assigned to Me
  • “Follow-up Needed”: Not Replied + Sent > 3 days ago
  • “Campaign X VIPs”: Specific campaign + Important flag
  • “Subsequence Tracking”: Leads in specific subsequence

​
Query Parameters

​
api_key
string
required
Your SmartLead API key
​
fetch_message_history
boolean
default:"false"
Include full email thread history

​
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
Custom view filter configuration
​
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/views?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "limit": 20,
    "filters": {
      "emailStatus": "Replied",
      "campaignId": 12345,
      "leadCategories": {
        "categoryIdsIn": [1]
      },
      "subSequenceId": 789
    },
    "sortBy": "REPLY_TIME_DESC"
  }'

​
Response Codes

​
200
Success
Custom view emails retrieved successfully
​
401
Unauthorized
Invalid API key
​
422
Validation Error
Invalid filter parameters
​
500
Internal Server Error
Server error
{
  "messages": [
    {
      "id": "msg_456",
      "campaign_lead_map_id": "9876543210",
      "lead": {
        "email": "sarah@startup.io",
        "first_name": "Sarah",
        "last_name": "Johnson"
      },
      "campaign": {
        "id": 12345,
        "name": "SaaS Outreach"
      },
      "subsequence": {
        "id": 789,
        "name": "Pricing Discussion"
      },
      "last_message": {
        "subject": "Re: Pricing Question",
        "body": "Thanks for the detailed pricing...",
        "received_at": "2025-01-20T10:15:00Z"
      },
      "email_status": "Replied",
      "category": {
        "id": 1,
        "name": "Interested"
      }
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 20
}

​
Predefined View Examples

​
Hot Leads View

{
  "filters": {
    "emailStatus": "Replied",
    "leadCategories": {
      "categoryIdsIn": [1]  # Interested
    },
    "campaignTeamMemberId": current_user_id
  },
  "sortBy": "REPLY_TIME_DESC"
}

​
Needs Follow-up View

{
  "filters": {
    "emailStatus": "Not Replied",
    "replyTimeBetween": [
      three_days_ago,
      now
    ]
  },
  "sortBy": "SENT_TIME_DESC"
}

​
Subsequence Performance View

{
  "filters": {
    "subSequenceId": 789,
    "emailStatus": "Replied"
  },
  "sortBy": "REPLY_TIME_DESC"
}

​
VIP Campaign View

{
  "filters": {
    "campaignId": 12345,
    "campaignTagId": 5,  # VIP tag
    "leadCategories": {
      "isAssigned": True
    }
  }
}

​
Subsequence Filtering

The subSequenceId filter is unique to this endpoint and allows tracking leads that have been pushed to child campaigns: 
# Track leads in demo request subsequence
demo_requests = {
  "filters": {
    "campaignId": main_campaign_id,
    "subSequenceId": demo_subsequence_id,
    "emailStatus": "Replied"
  }
}

# Compare parent vs subsequence performance
parent_responses = get_views({"filters": {"campaignId": main_campaign_id}})
subseq_responses = get_views({"filters": {"subSequenceId": demo_subsequence_id}})

​
Building Effective Views

​
1. Start Specific, Then Broaden

# Start narrow
specific_view = {
  "filters": {
    "campaignId": 123,
    "emailStatus": "Replied",
    "leadCategories": {"categoryIdsIn": [1]}
  }
}

# If no results, remove constraints
broader_view = {
  "filters": {
    "campaignId": 123,
    "emailStatus": "Replied"
  }
}

​
2. Combine Time and Status

recent_inactive = {
  "filters": {
    "emailStatus": "Opened",  # Opened but not replied
    "replyTimeBetween": [last_week, today]
  }
}

​
3. Multi-Dimension Filtering

high_value_prospects = {
  "filters": {
    "leadCategories": {"categoryIdsIn": [1]},  # Interested
    "campaignTagId": vip_tag_id,
    "campaignTeamMemberId": senior_rep_id,
    "subSequenceId": pricing_discussion_id
  }
}

​
Performance Optimization

  1. Single values preferred: Use single IDs instead of arrays when possible
  2. Limit subsequence queries: Subsequence filtering is more intensive
  3. Paginate properly: Use offset/limit for large result sets
  4. Cache views: Save frequently used filter combinations client-side