API Reference

All API requests require a Bearer token in the Authorization header. Obtain a token by authenticating via POST /api/v1/auth/login.

Login

curl -X POST https://api.phishivox.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@company.com", "password": "your-password"}'

# Response:
{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer"
}

Using the token

Include the token in all subsequent requests:

curl https://api.phishivox.com/api/v1/scan/history \
  -H "Authorization: Bearer eyJhbGciOi..."

Scan email from JSON payload

curl -X POST https://api.phishivox.com/api/v1/scan \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": "sender@example.com",
    "from_display_name": "Example Sender",
    "subject": "Verify your account",
    "body_text": "Click here to verify...",
    "headers": {
      "Authentication-Results": "spf=pass; dkim=pass; dmarc=pass"
    },
    "use_ai": true
  }'

Upload .eml file

curl -X POST https://api.phishivox.com/api/v1/scan/upload \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@suspicious-email.eml" \
  -F "use_ai=true"

Scan from connected mailbox

Get scan result

Rescan

Batch mailbox scan

Bulk scan (Enterprise)

Scan history

Scan stats

Quota

Response format

All scan endpoints return the same result structure:

{
  "id": "uuid",
  "verdict": "safe | spam | suspicious | phishing",
  "score": 0.0 - 1.0,
  "confidence": 0.0 - 1.0,
  "sender_trust": 0.0 - 1.0,
  "reasons": ["Finding 1", "Finding 2"],
  "layer_scores": {
    "rules": 0.0,
    "url": 0.0,
    "headers": 0.0,
    "attachments": 0.0,
    "ml": 0.0,
    "ai": 0.0
  },
  "ai_brands": [],
  "ai_findings": [],
  "ai_recommendations": []
}

Connect, browse, and manage email provider integrations.

Gmail

Microsoft 365

Status

Enterprise gateway management. Requires org admin role.

Connections

Events

Quarantine

Click audit

Dashboard

URL Proxy (Public)

Templates

Campaigns

Click Tracking (Public)

API keys allow programmatic access without JWT tokens. Pass the key in the X-API-Key header instead of Authorization: Bearer.

Inbound (from email providers)

Graph notifications are validated by verifying the clientState token included in the subscription. Invalid notifications are rejected with HTTP 403.

Outbound (SIEM/SOAR integration)

Enterprise customers can configure outbound webhooks to push security events to Splunk, Microsoft Sentinel, or any SOAR platform.

Event types

• email.scanned — Fired for every email processed by the gateway
• email.quarantined — Fired when an email is moved to quarantine
• email.released — Fired when an admin releases a quarantined email
• url.clicked — Fired for every URL click through the proxy
• url.blocked — Fired when a malicious URL is blocked
• url.warned — Fired when a warning page is shown

Payload format

{
  "event": "email.quarantined",
  "timestamp": "2026-04-10T14:30:00Z",
  "org_id": "uuid",
  "data": {
    "email_event_id": "uuid",
    "recipient": "user@company.com",
    "sender": "phisher@fake-domain.xyz",
    "subject": "Verify your account immediately",
    "verdict": "phishing",
    "score": 0.87,
    "action": "quarantined"
  }
}

Rate limits are per-IP. Exceeding the rate limit returns HTTP 429 with aRetry-After header. Scan quotas reset on the 1st of every month.