API

The web API accepts a JSON POST request. Query string parameters are not supported; all options belong in the request body.

Minimal request

{
  "message": "Return-Path: <spam@example.net>\nFrom: ...\n\nbody"
}

Example with curl:

jq -n --rawfile message spam.eml '{message: $message}' \
  | curl -s -H 'Content-Type: application/json' \
      --data-binary @- http://localhost:5000

Response shape

{
  "complaints": {
    "abuse@example.com": [
      {
        "type": "link",
        "host": "landing.example",
        "ips": ["203.0.113.42"],
        "whois-abuse-email": "abuse@example.com",
        "link": "https://landing.example/path"
      }
    ]
  },
  "warnings": []
}

complaints is keyed by the abuse email address to contact. Each item contains the evidence that led sc to that recipient, such as a Received header, IP address, hosted link, expanded link, host, and lookup result.

warnings contains non-fatal failures, such as cache errors or abuse lookups that timed out.

Trusted boundary override

You can override only trusted_boundary for one request:

{
  "message": "Return-Path: <spam@example.net>\nFrom: ...\n\nbody",
  "trusted_boundary": {
    "name": "mx.example.com"
  }
}

XARF reports

Add an xarf object to include XARF reports in the response. reporter and link_type are required.

{
  "message": "Return-Path: <spam@example.net>\nFrom: ...\n\nbody",
  "xarf": {
    "reporter": {
      "org": "Example Org",
      "contact": "abuse-reports@example.com",
      "domain": "example.com"
    },
    "link_type": "fraud",
    "smtp_source_port": 25
  }
}

Allowed hosted-link XARF types are phishing, malware, fraud, exposed_data, brand_infringement, remote_compromise, and suspicious_registration.

Server-side sending

If abuse_report is configured in sc.yaml, a request can ask the server to send abuse report email:

{
  "message": "Return-Path: <spam@example.net>\nFrom: ...\n\nbody",
  "abuse_report": {
    "send": true
  }
}

Sending is never automatic. The request must include abuse_report.send as JSON boolean true.

Error responses

Malformed requests return JSON error bodies with stable error codes.