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"
}'
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}")
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;
}
{
"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
}
Master Inbox
Get Important Emails
Retrieve emails marked as important to prioritize high-value conversations
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"
}'
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}")
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;
}
{
"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
- 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
- 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
string
required
Your SmartLead API key
boolean
default:"false"
Include full email thread history
false: Only latest message (recommended for list views)true: Complete conversation thread
Request Body
number
default:"0"
Number of records to skip for pagination
number
default:"20"
Number of records per page (1-20)
object
Advanced filtering options
Show filters properties
Show filters properties
string
Search term (max 30 characters)
object
string or array
Email engagement status:
Opened, Clicked, Replied, Unsubscribed, Bounced, Accepted, Not Repliednumber or array
Campaign ID(s) - max 5 campaigns
number or array
Email account ID(s) - max 10 accounts
number or array
Team member ID(s) - max 10 members
number or array
Campaign tag ID(s) - max 10 tags
number or array
Client ID(s) - max 10 clients
array
Date range:
["start_datetime", "end_datetime"] in ISO 8601 formatstring
default:"REPLY_TIME_DESC"
Sort order:
REPLY_TIME_DESC or SENT_TIME_DESCcurl -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"
}'
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}")
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;
}
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
Related Endpoints
- Get Inbox Messages - All replies
- Get Unread Replies - Unread messages
- Get Assigned to Me - Your assigned leads
⌘I