Skip to content

First Analysis Tutorial

Learn how to analyze emails and understand results through practical examples.

Understanding Email Analysis

SPOT analyzes emails through multiple stages:

  1. Submission - Email sent to API
  2. Validation - Schema validation
  3. Analysis - Multiple analyzers run in parallel or sequentially
  4. Aggregation - Results combined into threat assessment
  5. Response - Final verdict returned

Example 1: Legitimate Email

Submit Analysis

curl -X POST http://localhost:8001/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "headers": {
        "message_id": "<team-update-001@company.com>",
        "subject": "Weekly Team Update",
        "sender": "manager@company.com",
        "recipients": ["team@company.com"],
        "date": "2024-01-15T10:00:00Z"
      },
      "body_text": "Hi team,\n\nJust a reminder about our weekly standup tomorrow at 10am. Please prepare your updates.\n\nBest regards,\nYour Manager"
    },
    "workflow_id": "default-workflow"
  }'

Response

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "submitted",
  "message": "Analysis job submitted successfully"
}

Check Status

curl http://localhost:8001/api/v1/analyze/f47ac10b-58cc-4372-a567-0e02b2c3d479

Expected Result

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "result": {
    "threat_level": "safe",
    "confidence_score": 0.96,
    "threat_indicators": [],
    "summary": "No phishing indicators detected. Email appears legitimate.",
    "analyzer_results": {
      "nlp": {
        "sentiment": "neutral",
        "urgency": "low",
        "suspicious_phrases": []
      },
      "llm": {
        "verdict": "legitimate",
        "reasoning": "Professional tone, known sender, no suspicious patterns"
      }
    }
  },
  "processing_time_ms": 342
}

Example 2: Spear-Phishing Email

Submit Analysis

curl -X POST http://localhost:8001/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "headers": {
        "message_id": "<urgent-verify-123@phishing.com>",
        "subject": "URGENT: Your Account Will Be Suspended!!!",
        "sender": "security@paypaI.com",
        "recipients": ["victim@company.com"],
        "date": "2024-01-15T03:22:00Z"
      },
      "body_text": "Dear Customer,\n\nYour PayPal account has been flagged for suspicious activity. Click here IMMEDIATELY to verify your identity or your account will be permanently suspended within 24 hours:\n\nhttp://paypal-verify.suspicious-domain.com/login\n\nFailure to act will result in account termination.\n\nPayPal Security Team"
    },
    "workflow_id": "default-workflow"
  }'

Expected Result

{
  "job_id": "8b3e7f12-9d4a-4e6c-b8a1-1234567890ab",
  "status": "completed",
  "result": {
    "threat_level": "critical",
    "confidence_score": 0.98,
    "threat_indicators": [
      "domain_mismatch",
      "urgent_language",
      "suspicious_link",
      "sender_spoofing",
      "threat_of_consequences"
    ],
    "summary": "CRITICAL THREAT: Multiple phishing indicators detected.",
    "analyzer_results": {
      "nlp": {
        "sentiment": "threatening",
        "urgency": "critical",
        "suspicious_phrases": [
          "URGENT",
          "suspended",
          "IMMEDIATELY",
          "permanently suspended",
          "24 hours"
        ]
      },
      "llm": {
        "verdict": "phishing",
        "reasoning": "Classic phishing patterns: fake urgency, spoofed sender (paypaI with capital I), suspicious domain, threats of consequences"
      }
    }
  },
  "processing_time_ms": 528
}

Understanding Threat Levels

Level Score Range Description Recommended action
safe 0.0 - 0.2 No threats detected Allow
low 0.2 - 0.4 Minor suspicious elements Monitor
medium 0.4 - 0.6 Potentially harmful Review
high 0.6 - 0.8 Likely spear-phishing Block
critical 0.8 - 1.0 Definite spear-phishing Block + Alert

Common Threat Indicators

Sender Issues

  • sender_spoofing - Display name doesn't match email
  • domain_mismatch - Suspicious domain
  • no_spf - Missing SPF record

Content Issues

  • urgent_language - Excessive urgency
  • threatening_tone - Threats of consequences
  • suspicious_link - Malicious URLs
  • credential_request - Asking for passwords

Technical Issues

  • unusual_headers - Suspicious headers
  • attachment_threat - Dangerous attachments
  • encoding_anomaly - Character encoding tricks

Example 3: Bulk Analysis

Save emails to file: 

cat > emails.json <<EOF
[
  {
    "email": {
      "headers": {
        "subject": "Invoice #12345",
        "sender": "billing@company.com",
        "recipients": ["accounting@company.com"]
      },
      "body_text": "Please find attached invoice for payment."
    }
  },
  {
    "email": {
      "headers": {
        "subject": "Free iPhone - Click Now!",
        "sender": "offers@spam.com",
        "recipients": ["user@company.com"]
      },
      "body_text": "You've won a free iPhone! Click here: http://suspicious.link"
    }
  }
]
EOF

Analyze batch: 

for email in $(cat emails.json | jq -c '.[]'); do
  curl -X POST http://localhost:8001/api/v1/analyze \
    -H "Content-Type: application/json" \
    -d "$email"
done

Custom Workflows Examples

High Sensitivity

{
  "email": {...},
  "workflow_id": "high-sensitivity",
  "config": {
    "threshold": 0.3,
    "analyzers": ["nlp", "llm", "url", "attachment"]
  }
}

Fast Scan

{
  "email": {...},
  "workflow_id": "fast-scan",
  "config": {
    "threshold": 0.7,
    "analyzers": ["nlp"],
    "timeout": 5
  }
}

Integration Examples

Python

import httpx
import asyncio

async def analyze_email(email):
    async with httpx.AsyncClient() as client:
        # Submit analysis
        response = await client.post(
            "http://localhost:8001/api/v1/analyze",
            json={"email": email}
        )
        job_id = response.json()["job_id"]

        # Poll for result
        while True:
            result = await client.get(
                f"http://localhost:8001/api/v1/analyze/{job_id}"
            )
            data = result.json()
            if data["status"] == "completed":
                return data["result"]
            await asyncio.sleep(1)

# Usage
email = {
    "headers": {"subject": "Test", "sender": "test@example.com"},
    "body_text": "Test email"
}
result = asyncio.run(analyze_email(email))
print(f"Threat Level: {result['threat_level']}")

JavaScript

async function analyzeEmail(email) {
  // Submit
  const submitResponse = await fetch('http://localhost:8001/api/v1/analyze', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({email})
  });
  const {job_id} = await submitResponse.json();

  // Poll
  while (true) {
    const statusResponse = await fetch(
      `http://localhost:8001/api/v1/analyze/${job_id}`
    );
    const data = await statusResponse.json();
    if (data.status === 'completed') {
      return data.result;
    }
    await new Promise(r => setTimeout(r, 1000));
  }
}

Next Steps