Email Spam Filter

The Email Spam Filter processes inbound email in EML (RFC 822) format through Sentinel's HTTP API and returns both the parsed message and a full classification report — a fit for SaaS apps, helpdesks, contact forms, or anything else that needs to screen inbound mail.

How it works

Rather than a Bayesian classifier or a static blacklist, scoring combines several layers:

Content analysis — structural red flags in the message.
Signature verification — ARC, DKIM, and SPF authentication.
NLP — the same language analysis behind the Classifier, applied to the email body.
Phishing detection — URLs checked against Phishing Detection's continuously-updated feed.
Attachment handling — attachments can be safely extracted and uploaded to S3/Azure Blob storage instead of returned inline.

A 20KB email typically processes in around 15ms.

Setup

Finish installing Sentinel.
Create an API Key on a Security Group with Restricted access — this isn't a public endpoint.

Submitting an email

POST /v1/eml
Content-Type: application/octet-stream
Authorization: Bearer {API_KEY}

[raw EML file as the request body]

Optional request headers:

Header	Purpose	Default
`X-Authenticate`	Run ARC/DKIM/SPF verification (requires DNS lookups)	`false`
`X-Attachments-Upload`	Upload attachments to storage instead of returning them inline	`false`
`X-Attachments-Size-Limit`	Max attachment size, bytes	`5000000`
`X-Disable-Rules`	Comma-separated list of rules to skip	—
`X-Similarity-Groups`	Training data groups to match the body against	—
`X-Mail-From`	Sender from the SMTP `MAIL FROM` command, if you have it	—
`X-Smtp-Ip`	The relaying SMTP server's IP	—
`X-Smtp-Helo`	The relay's HELO/EHLO hostname	—
`X-Smtp-Mta`	The server that performed authentication	—
`X-Trust-Authentication`	Trust an existing `Authentication-Results` header instead of re-verifying	`true`

Response

{
  "authentication": {
    "ARC": { "result": "pass", "comment": "..." },
    "DKIM": [{ "result": "neutral", "signingDomain": "..." }],
    "SPF": { "result": "pass", "comment": "..." }
  },
  "classification": {
    "classification": "GOOD",
    "score": 0.5,
    "email": { "score": 0, "rules": {}, "triggeredRules": [] },
    "text": { "score": 1, "rules": {}, "triggeredRules": [] }
  },
  "mail": {
    "from": [{ "address": "...", "name": "..." }],
    "to": [{ "address": "...", "name": "..." }],
    "subject": "...",
    "text": "...",
    "html": "...",
    "attachments": [],
    "headers": []
  },
  "rules": {
    "ARC": { "score": null },
    "DKIM": { "score": null },
    "SPF": { "score": null },
    "FROM_SPOOFING": { "score": 0 },
    "REPLY_TO_SPOOFING": { "score": 0 },
    "CLASSIFICATION": { "score": 0.5 },
    "NO_SUBJECT": { "score": 0 },
    "NO_TEXT": { "score": 0 },
    "UNDISCLOSED_RECIPIENTS": { "score": 1 },
    "DELIVERED_TO_MISMATCH": { "score": 0 }
  },
  "score": 1.5,
  "spam": false,
  "time": 5.189
}

A total score of 2 or higher is treated as spam.

Email-specific rules

Rule	Flags
`FROM_SPOOFING`	Sender display name doesn't match the actual address — a common phishing indicator.
`REPLY_TO_SPOOFING`	`Reply-To` differs from the sender address — also a common phishing indicator.
`ARC` / `DKIM` / `SPF`	Authentication failures (only checked with `X-Authenticate: true`).
`NO_SUBJECT` / `NO_TEXT`	Missing subject or body content.
`UNDISCLOSED_RECIPIENTS`	No valid `To` address.
`DELIVERED_TO_MISMATCH`	`Delivered-To` doesn't match the `To` header.

Attachments

Attachments are returned Base64-encoded inline by default. With X-Attachments-Upload: true, they're uploaded to your configured storage provider instead, and can be retrieved later via GET /v1/blobs/{key}.

Configuration

Variable	Default	Purpose
`EML_BODY_LIMIT`	`5MB`	Maximum size of an incoming EML file.

Phishing Detection — the URL feed this cross-references.
Classifier — shared NLP scoring engine and rule format.
Similarity & Training Data — X-Similarity-Groups.
Storage Providers — where uploaded attachments go.
ENV Variables