API Documentation

Analyze emails and SMS programmatically using the DelPhish REST API. Requires a Pro plan with an API key.

Authentication

All API requests require a Bearer token. Use your API key (created in Account → API Keys) as the token.

Authorization: Bearer dp_your_api_key_here

API keys start with dp_. Keep them secret. You can revoke a key at any time from your account page.

Rate Limits

API requests are rate-limited per IP address. Default limits: 20 analyses/minute, 60 history requests/minute. If you hit a limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Endpoints

POST /api/v1/analysis/analyze

Analyze an email or SMS message for phishing indicators. Returns a full analysis with scores, risk factors, URL intelligence, and classification.

Request Body

Field	Type	Description
`sender`	string	Sender email address or phone number
`subject`	string	Email subject line (empty for SMS)
`body`	string	required Email body (HTML or plain text) or SMS message
`urls`	string	Newline-separated list of URLs found in the message
`headers`	string	Raw email headers (for SPF/DKIM/DMARC checks)
`attachments`	string	Comma-separated attachment filenames
`message_type`	string	`"email"` (default), `"sms"`, `"url"` (link-only analysis), or `"text"` (text snippet)

Example (curl)

curl -X POST https://your-domain.com/api/v1/analysis/analyze \
  -H "Authorization: Bearer dp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "security@suspicious-domain.tk",
    "subject": "Your account has been suspended",
    "body": "Click here to verify: https://suspicious-link.tk/verify",
    "message_type": "email"
  }'

Example (Python)

import requests

response = requests.post(
    "https://your-domain.com/api/v1/analysis/analyze",
    headers={"Authorization": "Bearer dp_your_api_key"},
    json={
        "sender": "security@suspicious-domain.tk",
        "subject": "Your account has been suspended",
        "body": "Click here to verify: https://suspicious-link.tk/verify",
        "message_type": "email",
    },
)
result = response.json()
print(f"Score: {result['combined_score']}% - {result['risk_level']}")
print(f"Classification: {result['email_classification']}")

Response

{
  "id": "abc12345-...",
  "combined_score": 78.5,
  "risk_level": "Alto",
  "email_classification": "phishing",
  "heuristic_score": 82.0,
  "ml_score": 75.3,
  "bert_score": 68.0,
  "llm_score": 85.0,
  "summary": "High-risk phishing email...",
  "risk_factors": [...],
  "url_intelligence": [...]
}

GET /api/v1/history

List your analysis history. Paginated, newest first.

Param	Type	Description
`page`	int	Page number (default: 1)
`page_size`	int	Results per page (default: 20, max: 100)

GET /api/v1/history/{analysis_id}

Get full details of a specific analysis by ID.

GET /api/v1/export/{analysis_id}/pdf

Download a PDF report for an analysis. Returns application/pdf.

Param	Type	Description
`language`	string	`"en"` or `"es"` (default: `"es"`)

POST /api/v1/batch/analyze

Analyze multiple messages in a single request. Max 10 messages per batch.

Request Body

{
  "messages": [
    {"sender": "...", "subject": "...", "body": "..."},
    {"sender": "...", "subject": "...", "body": "..."}
  ]
}

Response Codes

Code	Description
`200`	Success
`400`	Bad request (invalid input)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (feature not available on your plan)
`404`	Not found
`422`	Validation error
`429`	Rate limit exceeded
`500`	Internal server error