Email analysis (EML)
POST /v2/eml takes a raw email message (RFC 5322, as an .eml file), parses it, checks its ARC, DKIM, SPF, and DMARC results, and scores it with 22 EML rules plus the classifier. Use it to screen inbound mail before it reaches a mailbox, a ticket system, or a support queue.
How it works
For each message, Sentinel:
- Parses the headers, addresses, subject, text and HTML bodies, links, and attachments. Each attachment gets a SHA-256
checksum, itsrisks, and amaliciousflag from the malicious-hash list. - Authenticates the message in one of three ways, chosen by request headers:
- With
X-Authenticate, Sentinel verifies ARC, DKIM, SPF, and DMARC itself through DNS. - Otherwise, by default, it reads the topmost
Authentication-Resultsheader, which your receiving mail server added. - With
X-Trust-Authentication: 0, it skips authentication: every member ofauthenticationisnull, and so are theARC,DKIM,SPF, andDMARC_ALIGNMENTrule scores.
- With
- Classifies the
Fromaddress, the subject and body text, and the sending server's IP with the classifier, using the API key's security-group settings. The IP isX-Smtp-Ip, else the topmostReceivedheader with a public client IP, elseX-Originating-IP. The classifier's score becomes theCLASSIFICATIONrule. - Scores the message:
scoreis the sum of the EML rule scores, andspamistruewhenscoreis2or higher.
The classifier runs without device, rate-limit, HIS, and injection checks here, and skips HOSTING when the sender's domain authorizes the sending server, because large senders send from hosting IPs. The full aggregation is in Classifier rules & scores.
Enabling it
POST /v2/eml is on by default. These keys control it:
[eml]
enabled = true # false: POST /v2/eml returns 404
max_body_size = 5000000 # largest message in bytes (1024–100000000); larger is 413
dns_timeout = "1s" # per DNS attempt (2 attempts) with X-Authenticate
[eml.malicious_hashes]
enabled = true # false: never downloaded; MALICIOUS_ATTACHMENT scores 0
schedule = "@daily"Call it with a restricted or full key. public keys get 403 NON_PUBLIC_API_KEY_REQUIRED. The key's security group supplies the classifier settings: classifier.* fields such as classifier.disableRules, classifier.highRiskCountries, and the similarity groups. A group needs no extra set rule for email analysis.
Every key is in [eml] and [eml.malicious_hashes].
Attachment uploads
By default, attachments are returned inline as base64 content. To upload them to object storage instead, configure a [storage] provider and send X-Attachments-Upload: 1. Each attachment then has content: null and a contentUri that your application fetches with its own storage credentials. Without [storage], the header gets 400 VALIDATION_ERROR, and a failed upload makes the request 502 STORAGE_ERROR. Key layout, [eml] storage_prefix, and bucket permissions are on the Object storage page.
Malicious-hash list
[eml.malicious_hashes] is a remote file named malicious-file-hashes: a CSV with a sha256 column, or one hash per line, downloaded from https://directory.altcha.org/malicious-file-hashes.csv.gz by default and indexed in SQLite under <data_dir>/eml/. An attachment whose SHA-256 is on the list gets malicious: true and scores MALICIOUS_ATTACHMENT. Point url at your own list to add hashes from your mail gateway or threat feed.
Rules & signals
Request headers
| Header | Description |
|---|---|
X-Authenticate | 1, ?1, or true: verify ARC, DKIM, SPF, and DMARC through DNS instead of reading Authentication-Results. Absent or any other value: off. |
X-Trust-Authentication | Used only without X-Authenticate. Absent, 1, ?1, or true (the default): trust the topmost Authentication-Results header. Any other value: leave authentication unchecked. |
X-Attachments-Upload | 1, ?1, or true: upload attachments to [storage] instead of inlining them. |
X-Attachments-Size-Limit | Bytes. Larger attachments get content: null and aren't uploaded. Absent or 0: 5000000. |
X-Disable-Rules | EML and classifier rule names to switch off for this request, separated by commas, semicolons, or whitespace (at most 200). A disabled rule scores null. Classifier names replace the group's classifier.disableRules. An unknown name is 400 VALIDATION_ERROR. |
X-Similarity-Groups | Similarity groups, overriding the API key's. |
X-Smtp-Ip | The SMTP client IP, for SPF and the IP rules. Default: the topmost Received header with a public client IP. |
X-Mail-From, X-Smtp-Helo, X-Smtp-Mta | The envelope sender, HELO host, and receiving MTA host for SPF (at most 320 characters each). Defaults: Return-Path, the Received header, and the server's host name. |
true and rule names are case-insensitive. With X-Authenticate, pass the SMTP headers from your MTA when you have them: SPF is checked against the IP and envelope sender, and the Received header is only a fallback.
Authentication
authentication has one member per mechanism. Each is null when not checked:
| Field | Content |
|---|---|
ARC | { result, comment } |
DKIM | One { result, signingDomain, comment } per signature; [] when the verified message has none |
SPF | { result, comment } |
DMARC | { result, domain, policy, comment } |
The ARC, DKIM, SPF, and DMARC_ALIGNMENT rules score these results.
EML rules
| Rule | Meaning |
|---|---|
ARC | The ARC chain fails or is neutral. |
ATTACHMENT_RISK | The riskiest attachment's highest risk (see below). |
BULK_MAILER | X-Mailer or User-Agent names a bulk-mailing tool. |
CLASSIFICATION | The classifier's score for the sender, text, and sending IP. |
DATE_ANOMALY | Date is missing, in the future, or well before the topmost Received time. |
DELIVERED_TO_MISMATCH | The first Delivered-To differs from the first To address. |
DKIM | A DKIM signature fails or is neutral. |
DMARC_ALIGNMENT | DMARC fails; weighted by the domain's policy. |
FROM_SPOOFING | The From display name holds another address ("admin@paypal.com" <evil@attacker.example>). |
HIDDEN_TEXT | Most of the HTML's text is hidden. |
HTML_ONLY | An HTML body without a text/plain alternative. |
LINK_PHISHING | A link target is on the phishing list. |
LINK_TEXT_MISMATCH | A link's text shows another site than its target. |
LIST_UNSUBSCRIBE | A List-Unsubscribe header on DMARC-passing mail; lowers the score. |
MALICIOUS_ATTACHMENT | An attachment is on the malicious-hash list. |
MESSAGE_ID_ANOMALY | Message-ID is missing, malformed, or from an unrelated domain. |
NO_SUBJECT | The message has no subject. |
NO_TEXT | The message has no text body. |
REPLY_TO_SPOOFING | Reply-To points elsewhere than From. |
SPF | SPF fails or is neutral. |
SUSPICIOUS_LINK | A javascript: or data: link, an IP-address host, or a link shortener. |
UNDISCLOSED_RECIPIENTS | No To recipients. |
Scores and exact triggers are in Classifier rules & scores. The response lists every rule in rules and the ones that scored above 0 in triggeredRules, highest first; the classifier's own rules are in classification.triggeredRules.
Attachment risks
Each attachment's risks lists what Sentinel found by name, declared type, and content. ATTACHMENT_RISK scores the highest one.
| Risk | Meaning |
|---|---|
ARCHIVED_EXECUTABLE | A ZIP entry named like an executable, disk image, macro-enabled document, or deceptively |
DECEPTIVE_NAME | A decoy extension before a risky one (invoice.pdf.exe), or a bidi control character reordering the name |
DISK_IMAGE | A disk image (.iso, .img, .vhd, …), which bypasses Windows download warnings |
ENCRYPTED_ARCHIVE | A password-protected ZIP, which mail scanners can't read |
EXECUTABLE | An executable or script by extension or declared type |
EXECUTABLE_CONTENT | Windows, Linux, or macOS executable code, whatever the name |
HTML | An HTML or SVG file (credential phishing, HTML smuggling) |
MACROS | A macro-enabled Office document, by extension or VBA/XLM content |
TYPE_MISMATCH | The content is a different file type than the extension or declared type says |
Using the API
Send the raw message as the request body. Use message/rfc822 or any content type except multipart/form-data, application/x-www-form-urlencoded, and application/json, which get 400 VALIDATION_ERROR. A sample message, sample.eml:
Received: from mail.example.net (mail.example.net [203.0.113.10])
by mx.example.com; Thu, 19 Nov 2026 09:58:00 +0000
Authentication-Results: mx.example.com; spf=fail smtp.mailfrom=billing@example.net; dkim=none; dmarc=fail (p=reject) header.from=example.net
From: "support@paypal.com" <billing@example.net>
To: alice@example.com
Reply-To: refunds@example.org
Subject: Your account is on hold
Date: Thu, 19 Nov 2026 09:57:00 +0000
Message-ID: <1234@example.net>
Content-Type: text/html; charset=utf-8
<p>Please <a href="http://198.51.100.7/login">verify at paypal.com</a> within 24 hours.</p>curl https://sentinel.example.com/v2/eml \
-u 'key_…:sec_…' \
-H 'Content-Type: message/rfc822' \
--data-binary @sample.emlUse --data-binary: plain -d strips line breaks and breaks the message.
{
"data": {
"authentication": {
"ARC": null,
"DKIM": [{ "comment": null, "result": "none", "signingDomain": null }],
"DMARC": { "comment": "(p=reject) header.from=example.net", "domain": "example.net", "policy": "reject", "result": "fail" },
"SPF": { "comment": "smtp.mailfrom=billing@example.net", "result": "fail" }
},
"classification": {
"classification": "BAD",
"score": 3.76,
"triggeredRules": ["MX", "MALICIOUS", "URL"],
…
},
"mail": {
"attachments": [],
"from": [{ "address": "billing@example.net", "name": "support@paypal.com" }],
"links": [{ "tag": "a", "url": "http://198.51.100.7/login", "text": "verify at paypal.com" }],
"replyTo": [{ "address": "refunds@example.org", "name": null }],
"subject": "Your account is on hold",
"text": "Please verify at paypal.com within 24 hours.\n",
…
},
"rules": {
"ARC": { "score": null },
"ATTACHMENT_RISK": { "score": 0.0 },
"CLASSIFICATION": { "score": 3.76 },
"DMARC_ALIGNMENT": { "score": 4.0 },
…
},
"score": 18.26,
"spam": true,
"time": 122.634,
"triggeredRules": [
"DMARC_ALIGNMENT",
"SPF",
"CLASSIFICATION",
"FROM_SPOOFING",
"REPLY_TO_SPOOFING",
"SUSPICIOUS_LINK",
"HTML_ONLY"
]
}
}ARC is null because the trusted Authentication-Results header has no arc= result. An attachment looks like this (inline, without X-Attachments-Upload):
{
"checksum": "667ea66fe08be0a9babef14d88a6bc3546f22fcf496ec0304e95dcd54a38c059",
"content": "TVqQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAA",
"contentType": "application/pdf",
"contentUri": null,
"filename": "invoice.pdf.exe",
"malicious": false,
"risks": ["DECEPTIVE_NAME", "EXECUTABLE", "EXECUTABLE_CONTENT"],
"size": 33,
…
}The full schema is in the API reference. Likely errors are 400 VALIDATION_ERROR (empty body, bad header), 413 PAYLOAD_TOO_LARGE (over [eml] max_body_size), and 502 STORAGE_ERROR (failed upload); see Errors.
Tuning
- Use
spamas a starting point. The2threshold is fixed. For a quarantine-or-reject flow, comparescoreto your own thresholds, or act on specifictriggeredRules, such as quarantining onMALICIOUS_ATTACHMENTregardless of the total. - Trust or verify. If your MTA already adds
Authentication-Results, the default is fastest and needs no DNS. Make sure the topmost such header comes from your own server; strip incoming ones at the edge, or senders can forge a pass. UseX-Authenticatewhen nothing upstream authenticates, and passX-Smtp-IpandX-Mail-Fromso SPF checks the real connection. - False positives. Newsletters and transactional mail often trip
HTML_ONLY,BULK_MAILER, orDELIVERED_TO_MISMATCH(forwarding). Disable rules per request withX-Disable-Rules, or classifier rules for the whole group withclassifier.disableRules. - Large messages. Raise
[eml] max_body_sizeif legitimate mail with attachments gets413, and lowerX-Attachments-Size-Limitto keep responses small.
Limitations
- The body is a single message. Mailbox files and multipart form uploads aren't accepted.
- The classifier sees at most the first 16000 characters of the subject and body text. Injection checks don't run on email, because bodies legitimately contain HTML and SQL-like text.
- Attachment analysis inspects names, declared types, file signatures, and ZIP entries. It doesn't scan file contents for malware beyond the malicious-hash list.
- With
X-Authenticate, results depend on DNS: lookups time out after[eml] dns_timeoutper attempt, and a message relayed through a forwarder may fail SPF. - Sentinel doesn't serve uploaded attachments; your application reads them from storage.