Get Custom View Emails

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"

# Example: "Hot Leads in Subsequence" view
hot_leads_view = {
    "filters": {
        "emailStatus": "Replied",
        "campaignId": 12345,
        "leadCategories": {
            "categoryIdsIn": [1]  # Interested
        },
        "subSequenceId": 789  # Pricing discussion subsequence
    },
    "sortBy": "REPLY_TIME_DESC",
    "limit": 20
}

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

leads = response.json()
print(f"Hot leads in subsequence: {leads.get('total_count', 0)}")

const API_KEY = 'YOUR_API_KEY';

// Example: "Needs Follow-up" view
const needsFollowupView = {
  filters: {
    emailStatus: 'Not Replied',
    replyTimeBetween: [
      new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
      new Date().toISOString()
    ]
  },
  sortBy: 'SENT_TIME_DESC',
  limit: 20
};

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

const result = await response.json();
console.log(`Leads needing follow-up: ${result.total_count}`);

{
  "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
}

{
  "error": "Invalid subSequenceId"
}

POST

api

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"

# Example: "Hot Leads in Subsequence" view
hot_leads_view = {
    "filters": {
        "emailStatus": "Replied",
        "campaignId": 12345,
        "leadCategories": {
            "categoryIdsIn": [1]  # Interested
        },
        "subSequenceId": 789  # Pricing discussion subsequence
    },
    "sortBy": "REPLY_TIME_DESC",
    "limit": 20
}

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

leads = response.json()
print(f"Hot leads in subsequence: {leads.get('total_count', 0)}")

const API_KEY = 'YOUR_API_KEY';

// Example: "Needs Follow-up" view
const needsFollowupView = {
  filters: {
    emailStatus: 'Not Replied',
    replyTimeBetween: [
      new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
      new Date().toISOString()
    ]
  },
  sortBy: 'SENT_TIME_DESC',
  limit: 20
};

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

const result = await response.json();
console.log(`Leads needing follow-up: ${result.total_count}`);

{
  "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
}

{
  "error": "Invalid subSequenceId"
}

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

string

required

Your SmartLead API key

boolean

default:"false"

Include full email thread history

Request Body

number

default:"0"

Number of records to skip for pagination

number

default:"20"

Number of records per page (1-20)

object

Custom view filter configuration

Show filters properties

string

Search term (max 30 characters)

object

Lead category filters

Show leadCategories properties

boolean

Include uncategorized leads

boolean

Include categorized leads

array

Exclude specific category IDs (max 10)

array

Include only specific category IDs (max 10)

string

Email engagement status: Opened, Clicked, Replied, Unsubscribed, Bounced, Accepted, Not Replied

number

Filter by campaign ID (single value only for views)

number

Filter by email account ID (single value)

number

Filter by team member assignment (single value)

number

Filter by campaign tag (single value)

number

Filter by client ID (single value)

number

Unique to views: Filter by subsequence ID to track leads in specific child campaigns

array

Date range for reply times: ["start_date", "end_date"] in ISO 8601 format

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"

# Example: "Hot Leads in Subsequence" view
hot_leads_view = {
    "filters": {
        "emailStatus": "Replied",
        "campaignId": 12345,
        "leadCategories": {
            "categoryIdsIn": [1]  # Interested
        },
        "subSequenceId": 789  # Pricing discussion subsequence
    },
    "sortBy": "REPLY_TIME_DESC",
    "limit": 20
}

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

leads = response.json()
print(f"Hot leads in subsequence: {leads.get('total_count', 0)}")

const API_KEY = 'YOUR_API_KEY';

// Example: "Needs Follow-up" view
const needsFollowupView = {
  filters: {
    emailStatus: 'Not Replied',
    replyTimeBetween: [
      new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
      new Date().toISOString()
    ]
  },
  sortBy: 'SENT_TIME_DESC',
  limit: 20
};

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

const result = await response.json();
console.log(`Leads needing follow-up: ${result.total_count}`);

Response Codes

Success

Custom view emails retrieved successfully

Unauthorized

Invalid API key

Validation Error

Invalid filter parameters

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
}

{
  "error": "Invalid subSequenceId"
}

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

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

Get Inbox Messages - All replies
Push to Subsequence - Add leads to subsequence
Get By Campaign - Campaign-specific leads

Get Archived Emails Get Inbox Item by ID

⌘I

Campaign Management

Campaign Leads

Campaign Webhooks

Campaign Statistics

Lead Management

Lead Notes

Lead Tasks

Lead Tags

Lead Lists

Email Account Management

Email Account Tags

Master Inbox

Smart Delivery

Smart Senders

Webhooks

Global Analytics

Utilities

Client Management

Smart Prospect

Overview

Query Parameters

Request Body

Response Codes

Predefined View Examples

Hot Leads View

Needs Follow-up View

Subsequence Performance View

VIP Campaign View

Subsequence Filtering

Building Effective Views

1. Start Specific, Then Broaden

2. Combine Time and Status

3. Multi-Dimension Filtering

Performance Optimization

​Overview

​Query Parameters

​Request Body

​Response Codes

​Predefined View Examples

​Hot Leads View

​Needs Follow-up View

​Subsequence Performance View

​VIP Campaign View

​Subsequence Filtering

​Building Effective Views

​1. Start Specific, Then Broaden

​2. Combine Time and Status

​3. Multi-Dimension Filtering

​Performance Optimization

​Related Endpoints

Overview

Query Parameters

Request Body

Response Codes

Predefined View Examples

Hot Leads View

Needs Follow-up View

Subsequence Performance View

VIP Campaign View

Subsequence Filtering

Building Effective Views

1. Start Specific, Then Broaden

2. Combine Time and Status

3. Multi-Dimension Filtering

Performance Optimization

Related Endpoints