Skip to main content
ALTCHA®

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:

  1. Parses the headers, addresses, subject, text and HTML bodies, links, and attachments. Each attachment gets a SHA-256 checksum, its risks, and a malicious flag from the malicious-hash list.
  2. 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-Results header, which your receiving mail server added.
    • With X-Trust-Authentication: 0, it skips authentication: every member of authentication is null, and so are the ARC, DKIM, SPF, and DMARC_ALIGNMENT rule scores.
  3. Classifies the From address, the subject and body text, and the sending server's IP with the classifier, using the API key's security-group settings. The IP is X-Smtp-Ip, else the topmost Received header with a public client IP, else X-Originating-IP. The classifier's score becomes the CLASSIFICATION rule.
  4. Scores the message: score is the sum of the EML rule scores, and spam is true when score is 2 or 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

HeaderDescription
X-Authenticate1, ?1, or true: verify ARC, DKIM, SPF, and DMARC through DNS instead of reading Authentication-Results. Absent or any other value: off.
X-Trust-AuthenticationUsed 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-Upload1, ?1, or true: upload attachments to [storage] instead of inlining them.
X-Attachments-Size-LimitBytes. Larger attachments get content: null and aren't uploaded. Absent or 0: 5000000.
X-Disable-RulesEML 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-GroupsSimilarity groups, overriding the API key's.
X-Smtp-IpThe 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-MtaThe 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:

FieldContent
ARC{ result, comment }
DKIMOne { 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

RuleMeaning
ARCThe ARC chain fails or is neutral.
ATTACHMENT_RISKThe riskiest attachment's highest risk (see below).
BULK_MAILERX-Mailer or User-Agent names a bulk-mailing tool.
CLASSIFICATIONThe classifier's score for the sender, text, and sending IP.
DATE_ANOMALYDate is missing, in the future, or well before the topmost Received time.
DELIVERED_TO_MISMATCHThe first Delivered-To differs from the first To address.
DKIMA DKIM signature fails or is neutral.
DMARC_ALIGNMENTDMARC fails; weighted by the domain's policy.
FROM_SPOOFINGThe From display name holds another address ("admin@paypal.com" <evil@attacker.example>).
HIDDEN_TEXTMost of the HTML's text is hidden.
HTML_ONLYAn HTML body without a text/plain alternative.
LINK_PHISHINGA link target is on the phishing list.
LINK_TEXT_MISMATCHA link's text shows another site than its target.
LIST_UNSUBSCRIBEA List-Unsubscribe header on DMARC-passing mail; lowers the score.
MALICIOUS_ATTACHMENTAn attachment is on the malicious-hash list.
MESSAGE_ID_ANOMALYMessage-ID is missing, malformed, or from an unrelated domain.
NO_SUBJECTThe message has no subject.
NO_TEXTThe message has no text body.
REPLY_TO_SPOOFINGReply-To points elsewhere than From.
SPFSPF fails or is neutral.
SUSPICIOUS_LINKA javascript: or data: link, an IP-address host, or a link shortener.
UNDISCLOSED_RECIPIENTSNo 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.

RiskMeaning
ARCHIVED_EXECUTABLEA ZIP entry named like an executable, disk image, macro-enabled document, or deceptively
DECEPTIVE_NAMEA decoy extension before a risky one (invoice.pdf.exe), or a bidi control character reordering the name
DISK_IMAGEA disk image (.iso, .img, .vhd, …), which bypasses Windows download warnings
ENCRYPTED_ARCHIVEA password-protected ZIP, which mail scanners can't read
EXECUTABLEAn executable or script by extension or declared type
EXECUTABLE_CONTENTWindows, Linux, or macOS executable code, whatever the name
HTMLAn HTML or SVG file (credential phishing, HTML smuggling)
MACROSA macro-enabled Office document, by extension or VBA/XLM content
TYPE_MISMATCHThe 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.eml

Use --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 spam as a starting point. The 2 threshold is fixed. For a quarantine-or-reject flow, compare score to your own thresholds, or act on specific triggeredRules, such as quarantining on MALICIOUS_ATTACHMENT regardless 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. Use X-Authenticate when nothing upstream authenticates, and pass X-Smtp-Ip and X-Mail-From so SPF checks the real connection.
  • False positives. Newsletters and transactional mail often trip HTML_ONLY, BULK_MAILER, or DELIVERED_TO_MISMATCH (forwarding). Disable rules per request with X-Disable-Rules, or classifier rules for the whole group with classifier.disableRules.
  • Large messages. Raise [eml] max_body_size if legitimate mail with attachments gets 413, and lower X-Attachments-Size-Limit to 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_timeout per attempt, and a message relayed through a forwarder may fail SPF.
  • Sentinel doesn't serve uploaded attachments; your application reads them from storage.

Start typing to search...

↑ ↓ Navigate ↵ Select