Automate Email analysis with the Blue Lantern Security API
In a business setting you likely will not want to leverage the UI every time you need to scan an email to assess whether it is phishing or not. Instead, you should leverage Blue Lantern's API capabilities to build an automated workflow to send eml files and then make the risk determination about each email automatically.
Prerequisites
- A Blue Lantern Security API Key requested from here API Access.
- Familiarity with a scipting language and curl commands.
API Call Required to Submit Emails for analysis
The curl for the API call to submit emails for analysis looks as below. You will need to pass an eml file that you've retrieved from wherever you automatically collect suspicious emails (potentially from a company phishing/spam submission inbox). You will need to provide your API key and file path in the placeholders below in the scripting language you choose.
curl --location 'https://api.bluelanternsecurity.io/runs' \
--header 'Authorization: [API KEY HERE]' \
--form 'tool="EMAILANALYZER"' \
--form 'checkCost="false"' \
--form 'file=@"[PATH HERE]"'
On successful submission, you will receive a job ID for checking the status of the analysis and for fetching the results once the analysis completes.
{
"message": "Requested Analysis Job Created",
"result": {
"jobId": "[JOB ID]"
}
}
NOTE: these emails are only processed for possible phishing related signatures. The email itself is kept for no more than a day in our systems. The final reports are kept for no more than one week. These emails must be below 4.5 MB in size to work with our API.
Collecting data
The job statis can be checked from the /runs data endpoint by passing the job ID as a path parameter with a GET request:
curl --location 'https://api.bluelanternsecurity.io/runs/[JOB ID]' \
--header 'Authorization: [API KEY HERE]'
The job will not show "COMPLETE" until the results are ready. Example data response is shown below:
{
"message": "Job run data retrieved",
"result": [
{
"id": "[JOB ID]",
"user_id": "[YOUR USER ID]",
"run_start": "2026-03-31 15:03:33.956299+00:00",
"run_type": "EMAILANALYZER",
"run_status": "COMPLETE",
"run_description": null,
"run_end": "2026-03-31 15:03:38.238808+00:00"
}
]
}
Once complete, you can fetch the results of the analysis using the POST request as shown in the curl below:
curl --location 'https://api.bluelanternsecurity.io/results' \
--header 'Content-Type: application/json' \
--header 'Authorization: [API KEY]' \
--data '{
"jobId": "[JOB ID]"
}'
The results data for the email analyzer looks as follows. You can use the direct check pass/fail results or you can use the details provided to inform your downstream decision on the risk of the email itself.:
{
"message": "results retrieved",
"result": {
"job_id": "[JOB ID]",
"filename": "[FILE NAME]",
"analyzed_at": "2026-03-31T15:03:37.592621+00:00",
"status": "Completed",
"Status": 200,
"Checks_failed": 4,
"Checks_total": 22,
"checks_results": [
{
"name": "From matches Reply-To",
"result": "Pass",
"type": "headers",
"description": "Checks if the 'From' address matches the 'Reply-To' address. Mismatches often indicate spoofing."
},
{
"name": "Private Domain Sender",
"result": "Pass",
"type": "headers",
"description": "Verifies the sender uses a private, organizational domain instead of a free provider."
},
{
"name": "Display Name Email Matches Sender Email",
"result": "Pass",
"type": "headers",
"description": "Checks if the display name contains a misleading email address that doesn't match the sender."
},
{
"name": "Matching Sender and Recipient Domain",
"result": "Fail",
"type": "headers",
"description": "Checks if the sender domain matches the recipient domain (Internal Email)."
},
{
"name": "No Sender Typosquatting",
"result": "Pass",
"type": "headers",
"description": "Verifies the sender domain is not mimicking the recipient domain (e.g. examp1e.com vs example.com)."
},
{
"name": "Fewer Than 6 Routing Hops",
"result": "Pass",
"type": "headers",
"description": "Checks for excessive server hops which might indicate relay abuse."
},
{
"name": "SPF Record Valid",
"result": "Fail",
"type": "headers",
"description": "SPF verifies that the sending server is authorized to send email on behalf of this domain."
},
{
"name": "DKIM Signature Valid",
"result": "Fail",
"type": "headers",
"description": "DKIM ensures the email content hasn't been tampered with during transit using cryptographic signatures."
},
{
"name": "DMARC Policy Valid",
"result": "Fail",
"type": "headers",
"description": "DMARC enforces policies for handling emails that fail authentication, protecting the domain reputation."
},
{
"name": "No Hops > 10 Minutes Or Backwards In Time",
"result": "Pass",
"type": "headers",
"description": "Checks if any hop in email routing took longer than 10 minutes or went backwards in time by greater than 1 second."
},
{
"name": "No Phishing Keywords",
"result": "Pass",
"type": "body",
"description": "Scans for common words and patterns typically found in spam and phishing attempts."
},
{
"name": "No Urgency Patterns",
"result": "Pass",
"type": "body",
"description": "Detects psychological triggers like 'Immediate Action' designed to make you act without thinking."
},
{
"name": "No Character Substitutions",
"result": "Pass",
"type": "body",
"description": "Checks for hidden characters or homoglyphs used to bypass spam filters."
},
{
"name": "No Active Scripts",
"result": "Pass",
"type": "body",
"description": "Detects dangerous executable scripts embedded in the email body."
},
{
"name": "Standard Spelling & Grammar",
"result": "Pass",
"type": "body",
"description": "Checks for poor spelling and grammar errors often found in mass-generated phishing emails."
},
{
"name": "No Hidden Content",
"result": "Pass",
"type": "body",
"description": "Detects invisible text or elements used to bypass security filters."
},
{
"name": "No Lookalike Domains",
"result": "Pass",
"type": "links",
"description": "Detects typosquatting domains that visually mimic legitimate brands to deceive users."
},
{
"name": "No Suspicious Shorteners",
"result": "Pass",
"type": "links",
"description": "Identifies generic URL shorteners often used to hide malicious destinations."
},
{
"name": "No Anchor Text Mismatches",
"result": "Pass",
"type": "links",
"description": "Verifies that the link text matches the actual URL, preventing deceptive redirection."
},
{
"name": "No Suspicious Hosting",
"result": "Pass",
"type": "links",
"description": "Checks if links point to abuse-prone free hosting services often used for phishing pages."
},
{
"name": "Domain Older Than 30 Days",
"result": "Pass",
"type": "domain",
"description": "Checks if the domain was registered recently (less than 30 days ago and is likely temporary)."
},
{
"name": "No Attachment Types That Could Be Executable",
"result": "Pass",
"type": "attachments",
"description": "Scans for executables, scripts, macros, and other dangerous file types."
}
],
"details": {
"headers": {
"from": "",
"from_address": "",
"reply_to": "",
"reply_to_mismatch": null,
"return_path": "",
"return_path_mismatch": null,
"sender_domain": "",
"is_public_domain": false,
"mismatch_detected": false,
"sender_receiver_mismatch": true,
"sender_typosquat": false,
"excessive_hops": false,
"timing_anomalies": false,
"auth_results": {
"spf": "",
"dkim": "",
"dmarc": ""
},
"email_path": [],
"subject_flags": {
"findings": []
},
"display_name_flags": {
"findings": [],
"display_name_spoof": false
},
"domain_results": {
"domain": "blsec.net",
"root_domain": "blsec.net",
"subdomain": null,
"age_days": 98,
"creation_date": "2025-12-23T12:33:19+00:00",
"registrar": "Cloudflare, Inc.",
"available": false,
"whois_error": null,
"suspicious_patterns": [],
"expiration_date": "2026-12-23T12:33:19+00:00"
},
"findings": [
"Domain less than 1 year old (98 days)"
]
},
"body": {
"keywords_found": [],
"keyword_count": 0,
"grammar_issues": 0,
"urgency_patterns": [],
"character_substitutions": [],
"has_scripts": false,
"findings": []
},
"links": {
"urls_found": [],
"url_count": 0,
"shorteners": [],
"anchor_mismatches": [],
"lookalikes": [],
"suspicious_hosting": [],
"punycode_domains": [],
"ip_urls": [],
"dangerous_files": [],
"open_redirects": [],
"suspicious_params": [],
"domain_analysis": [],
"findings": []
},
"domain": {
"domain_info": {
"domain": "blsec.net",
"root_domain": "blsec.net",
"subdomain": null,
"age_days": 98,
"creation_date": "2025-12-23T12:33:19+00:00",
"registrar": "Cloudflare, Inc.",
"available": false,
"whois_error": null,
"suspicious_patterns": [],
"expiration_date": "2026-12-23T12:33:19+00:00"
},
"findings": [
"Domain less than 1 year old (98 days)"
]
},
"attachments": {
"attachment_count": 1,
"attachments": [
{
"filename": "[ATTACHMENT FILENAME]",
"size_bytes": 3049,
"content_type": "text/x-python-script",
"findings": [],
"detected_type": null,
"has_macros": false,
"has_javascript": false,
"extracted_urls": []
}
],
"findings": []
}
}
}
}