# Email analysis (EML)

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

`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](#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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/reference/classifier-rules/#email-eml-rules).

## Enabling it

`POST /v2/eml` is on by default. These keys control it:

```toml
[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.*`](/docs/sentinel/v2/reference/rules/#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]`](/docs/sentinel/v2/reference/configuration/#eml) and [`[eml.malicious_hashes]`](/docs/sentinel/v2/reference/configuration/#emlmalicious_hashes).

### Attachment uploads

By default, attachments are returned inline as base64 `content`. To upload them to object storage instead, configure a [`[storage]` provider](/docs/sentinel/v2/configure/storage/) 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](/docs/sentinel/v2/configure/storage/) page.

### Malicious-hash list

`[eml.malicious_hashes]` is a [remote file](/docs/sentinel/v2/configure/remote-files/) 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](/docs/sentinel/v2/reference/classifier-rules/#email-eml-rules). 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`:

```http
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>
```

```bash
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.

```json
{
"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`):

```json
{
"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](/sentinel-api-docs-v2.html#tag/eml/POST/v2/eml). 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](/docs/sentinel/v2/reference/errors/).

<Callout type="note" title="Changed in v2">

Without `X-Authenticate`, Sentinel trusts the topmost `Authentication-Results` header (your receiving server's), not the bottommost. Attachment checksums are SHA-256, and uploads need a `[storage]` provider. See [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/#eml).

## 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.

## Related

- [Inbound email screening](/docs/sentinel/v2/use-cases/email-screening/)
- [Classifier](/docs/sentinel/v2/features/classifier/) and [Phishing detection](/docs/sentinel/v2/features/phishing/)
- [Classifier rules & scores: EML rules](/docs/sentinel/v2/reference/classifier-rules/#email-eml-rules)
- [Object storage](/docs/sentinel/v2/configure/storage/)
- [Remote files](/docs/sentinel/v2/configure/remote-files/)
- [`[eml]` configuration](/docs/sentinel/v2/reference/configuration/#eml)
- [API reference: `POST /v2/eml`](/sentinel-api-docs-v2.html#tag/eml/POST/v2/eml)
