Email Search Guide

Endpoint: /search-by-login/emails

Required Permissions: search-by-login

Overview

The Email Search endpoint allows you to search for compromised credentials using email addresses. This endpoint is particularly useful for identifying potential security breaches where email credentials have been exposed.

Use Cases

Monitor employee email compromise
Investigate potential account breaches
Verify security incidents
Track credential exposure
Proactive security monitoring

Request Format

{
    "logins": [
        "[email protected]",
        "[email protected]"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "types": [
        "employees",
        "users"
    ],
    "domains": [
        "example.com"
    ],
    "keywords": [
        "vpn",
        "admin"
    ],
    "keywords_match": "any",
    "filter_credentials": true,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
}

Required Parameters

Parameter	Type	Description	Constraints
logins	array[string]	List of email addresses to search	1-50 emails, valid email format

Optional Parameters

Parameter	Type	Default	Description
sort_by	string	"date_compromised"	Sort results by "date_compromised" or "date_uploaded"
sort_direction	string	"desc"	Sort direction: "asc" or "desc"
types	array[string]	all types	Filter by "employees", "users", or "third_parties"
domains	array[string]	[]	Filter results by specific domains
keywords	array[string]	[]	Filter URLs containing specific keywords
keywords_match	string	"any"	Match "any" or "all" keywords
filter_credentials	boolean	true	Return only matched credentials
start_date	datetime	null	Filter results after this date
end_date	datetime	null	Filter results before this date

Response Structure

{
    "data": [
        {
            "stealer": "string",
            "date_compromised": "2024-02-27T10:53:48.989Z",
            "date_uploaded": "2024-02-27T10:53:48.989Z",
            "stealer_family": "string",
            "ip": "string",
            "computer_name": "string",
            "operating_system": "string",
            "credentials": [
                {
                    "url": "string",
                    "domain": "string",
                    "username": "string",
                    "password": "string",
                    "type": "employee"
                }
            ]
        }
    ],
    "nextCursor": "base64_encoded_cursor"
}

Response Fields

Field	Type	Required	Description
stealer	string	Yes	Unique identifier of the stealer
date_compromised	datetime	Yes	Date when credentials were compromised
date_uploaded	datetime	Yes	Date when data was uploaded to our system
stealer_family	string	No	Family/type of the stealer malware
ip	string	No	IP address of the compromised machine
computer_name	string	No	Name of the compromised computer
operating_system	string	No	OS of the compromised machine
credentials	array	Yes	Array of compromised credentials
nextCursor	string	No	Pagination cursor for next page

Best Practices

1. Email Validation

Ensure email addresses are properly formatted
Remove duplicates before sending
Normalize email addresses (lowercase)
Handle international email formats

2. Search Optimization

{
    "logins": [
        "[email protected]"
    ],
    "filter_credentials": true,
    "types": [
        "employees"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

Use specific types to narrow results
Enable filter_credentials for relevant matches
Sort by date for recent compromises
Use keywords to focus on specific services

3. Batch Processing

Group emails in batches (up to 50)
Implement pagination for large results
Handle rate limits appropriately
Cache results when possible

Common Search Patterns

1. Recent Employee Compromises

{
    "logins": [
        "[email protected]"
    ],
    "types": [
        "employees"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "start_date": "2024-01-01T00:00:00Z"
}

2. Domain-Specific Search

{
    "logins": [
        "[email protected]"
    ],
    "domains": [
        "example.com"
    ],
    "keywords": [
        "admin",
        "portal"
    ],
    "keywords_match": "any"
}

Error Handling

Common Errors

Status	Cause	Solution
400	Invalid email format	Validate emails before sending
400	Too many emails	Reduce batch size to ≤50
408	Request timeout	Reduce batch size or retry
429	Rate limit exceeded	Implement backoff strategy

Error Response Example

{
    "error": "ValidationError",
    "message": "Invalid email format: [email protected]"
}

Security Considerations

Secure storage of search results
Limit access to sensitive data
Audit search patterns
Encrypt API communications
Handle credentials securely

Integration Examples

Basic Search Implementation

async def search_emails(emails):
    try:
        response = await api.post('/search-by-login/emails', {
            'logins': emails,
            'filter_credentials': True,
            'sort_by': 'date_compromised',
            'sort_direction': 'desc'
        })
        return process_results(response.data)
    except ApiError as e:
        handle_error(e)

Pagination Handler

async def get_all_results(emails):
    results = []
    cursor = None
    while True:
        response = await search_emails(emails, cursor)
        results.extend(response.data)
        if not response.nextCursor:
            break
        cursor = response.nextCursor
    return results

Performance Tips

Use pagination for large result sets
Cache frequent searches
Implement request batching
Monitor response times
Handle timeouts gracefully

Monitoring and Alerts

Track search volumes
Monitor error rates
Alert on critical findings
Track response times
Monitor rate limits