# Inbound email screening

> **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).

Support inboxes, ticket systems and shared mailboxes receive phishing, spoofed senders, malware attachments and spam alongside real customer mail. This page sends each inbound message to `POST /v2/eml` before it reaches a person, and turns the result into a deliver, flag, spam or quarantine decision.

Prerequisites: a running Sentinel with an active license, an admin user who can edit security groups and API keys, and access to the raw message (RFC 5322) at some point of your mail flow.

## What you're defending against

| Threat | What catches it |
| --- | --- |
| Phishing links | `LINK_PHISHING` (the phishing list), `LINK_TEXT_MISMATCH` (link text shows another site), `SUSPICIOUS_LINK` (IP hosts, `javascript:` and `data:` links, shorteners). |
| Spoofed senders and business email compromise | `DMARC_ALIGNMENT`, `SPF`, `DKIM`, `ARC`, `FROM_SPOOFING` (an address in the display name) and `REPLY_TO_SPOOFING`. |
| Malware attachments | `MALICIOUS_ATTACHMENT` (the malicious-hash list) and `ATTACHMENT_RISK`: executables, macros, disk images, encrypted archives, double extensions, type mismatches. |
| Spam | The classifier's text, sender and IP rules (the `CLASSIFICATION` rule), plus `BULK_MAILER`, `HIDDEN_TEXT` and structural anomalies. |
| Repeats of spam you already reported | Similarity with your own training groups, and `CAMPAIGN` for the same message from many sending servers. |

## Recommended configuration

### Server configuration

Email analysis is on by default. The keys you're most likely to set:

```toml
[eml]
max_body_size = 25000000   # bytes; the default 5000000 refuses larger messages with 413

[eml.malicious_hashes]
enabled = true             # default; MALICIOUS_ATTACHMENT needs this list

[similarity]
provider = "local"         # optional: semantic matching of reported spam
```

To have Sentinel upload attachments to object storage instead of returning them in the response, configure `[storage]` and send `X-Attachments-Upload: 1`. For screening, you usually don't need the attachments back. See [Email analysis](/docs/sentinel/v2/features/email-analysis/#enabling-it) and [`[eml]`](/docs/sentinel/v2/reference/configuration/#eml).

### Backend group and key

`POST /v2/eml` takes a `restricted` or `full` key. Create a `restricted` group for your mail pipeline, apply the [Backend API (allowed IPs)](/docs/sentinel/v2/policies/presets/#backend-api-allowed-ips) preset with the IPs of the hosts that call Sentinel, and add a classifier rule after it:

```json
{
"name": "inbound-mail",
"action": "set",
"set": [
{ "field": "classifier.disableRules", "value": "FREE_PROVIDER" },
{ "field": "classifier.similarityGroups", "value": "mail_spam" }
]
}
```

- **`FREE_PROVIDER`.** Customers write to a support inbox from free mail providers, so a free sender domain isn't a signal there.
- **`classifier.similarityGroups`.** The training group that your users' spam reports fill in [Step 3](#step-3--feed-spam-reports-back).

The group's `classifier.*` settings apply to the `CLASSIFICATION` part of the analysis. Create a `restricted` API key in this group with **Request logging** set to **All**.

## Integration steps

### Step 1 — Send each message to Sentinel

Call `POST /v2/eml` wherever your system holds the raw message after your own mail server accepted it: a content filter of your MTA, the inbound webhook of a mail provider that forwards raw MIME, or a worker that reads new messages from the mailbox. Send the message as the request body:

```bash
curl https://sentinel.example.com/v2/eml \
-u 'key_…:sec_…' \
-H 'Content-Type: message/rfc822' \
-H 'X-Attachments-Size-Limit: 1' \
--data-binary @message.eml
```

Use `--data-binary`; plain `-d` strips line breaks and breaks the message. `X-Attachments-Size-Limit: 1` keeps attachment contents out of the response; Sentinel still analyzes every attachment and returns its `checksum`, `risks` and `malicious` flag.

**How the message is authenticated** depends on where you call from:

| Your setup | Send |
| --- | --- |
| Your receiving mail server adds `Authentication-Results` (the default Sentinel trusts) | Nothing extra. Strip `Authentication-Results` headers that arrive from outside at your edge, or senders can forge a pass. |
| Nothing upstream authenticates the message | `X-Authenticate: 1`, plus `X-Smtp-Ip` and `X-Mail-From` from the SMTP session, so SPF checks the real connection. |
| The message was relayed or forwarded, so authentication results don't apply | `X-Trust-Authentication: 0`: the authentication rules score `null`. |

See [Request headers](/docs/sentinel/v2/features/email-analysis/#request-headers).

The same call in code:

<Tabs padding={false}>

### Node.js

```ts
const SENTINEL_AUTH =
'Basic ' + Buffer.from(`key_…:${process.env.SENTINEL_API_KEY_SECRET}`).toString('base64');

// raw: the complete message as received, headers and body.
export async function analyzeMessage(raw: Buffer, smtp?: { ip: string; mailFrom: string }) {
const headers: Record<string, string> = {
  Authorization: SENTINEL_AUTH,
  'Content-Type': 'message/rfc822',
  'X-Attachments-Size-Limit': '1',
};
if (smtp) {
  headers['X-Authenticate'] = '1';
  headers['X-Smtp-Ip'] = smtp.ip;
  headers['X-Mail-From'] = smtp.mailFrom;
}
const res = await fetch('https://sentinel.example.com/v2/eml', {
  method: 'POST',
  headers,
  body: raw,
  signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(`Sentinel /v2/eml: ${res.status}`);
return (await res.json()).data;
}
```

### Python

```python
import os

import requests

AUTH = ("key_…", os.environ["SENTINEL_API_KEY_SECRET"])

def analyze_message(raw: bytes, smtp_ip: str | None = None, mail_from: str | None = None) -> dict:
  """raw: the complete message as received, headers and body."""
  headers = {"Content-Type": "message/rfc822", "X-Attachments-Size-Limit": "1"}
  if smtp_ip and mail_from:
      headers.update({"X-Authenticate": "1", "X-Smtp-Ip": smtp_ip, "X-Mail-From": mail_from})
  res = requests.post(
      "https://sentinel.example.com/v2/eml",
      data=raw,
      headers=headers,
      auth=AUTH,
      timeout=10,
  )
  res.raise_for_status()
  return res.json()["data"]
```

### Step 2 — Decide what happens to the message

The response has `score` (the sum of the EML rule scores), `spam` (`true` from a score of `2`), the triggered EML rules in `triggeredRules`, and the parsed message in `mail`, including each attachment's `risks` and `malicious` flag:

```json
{
"data": {
"score": 18.26,
"spam": true,
"triggeredRules": ["DMARC_ALIGNMENT", "SPF", "CLASSIFICATION", "FROM_SPOOFING", "REPLY_TO_SPOOFING", "SUSPICIOUS_LINK", "HTML_ONLY"],
"authentication": { "DMARC": { "result": "fail", "policy": "reject", … }, … },
"classification": { "classification": "BAD", "score": 3.76, … },
"mail": { "attachments": [], "subject": "Your account is on hold", … },
…
}
}
```

Act on the strongest signals first, and on `spam` after that:

```ts
type Verdict = 'quarantine' | 'spam' | 'warn' | 'deliver';

export function decide(result: { spam: boolean; triggeredRules: string[] }): Verdict {
const rules = result.triggeredRules;
if (rules.includes('MALICIOUS_ATTACHMENT') || rules.includes('LINK_PHISHING')) return 'quarantine';
if (result.spam) return 'spam';
if (rules.includes('FROM_SPOOFING') || rules.includes('REPLY_TO_SPOOFING')) return 'warn';
return 'deliver';
}
```

| Verdict | Typical action |
| --- | --- |
| `quarantine` | Keep the message away from users; let an administrator release it. |
| `spam` | Deliver to the spam folder, or create the ticket as spam. |
| `warn` | Deliver with a banner such as "The sender's address doesn't match their name." |
| `deliver` | Deliver normally. |

`ATTACHMENT_RISK` is scored into `spam`, but you can also quarantine on specific attachment `risks`, such as `EXECUTABLE` or `MACROS`, if no legitimate sender of yours uses them. Rule meanings are in [EML rules](/docs/sentinel/v2/features/email-analysis/#eml-rules); scores in [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/#email-eml-rules).

Decide what happens when Sentinel can't be reached: deliver and screen later, or hold until it's back.

### Step 3 — Feed spam reports back

When a user or agent marks a message as spam, send its subject and text to `POST /v2/training-data/_feedback`. Samples are up to 4000 characters, so send the start of the text:

```bash
curl https://sentinel.example.com/v2/training-data/_feedback \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{"group": "mail_spam", "label": "positive", "text": "Your account is on hold\n\nPlease verify at paypal.com within 24 hours."}'
```

```json
{ "data": { "duplicate": false, "id": "trd_…" } }
```

Take the text from the response's `mail.subject` and `mail.text` rather than from the raw message, which holds headers and encoded parts. Rewordings of reported messages then trigger `SIMILARITY` or `NEAR_DUPLICATE` in the `CLASSIFICATION` part. Send "not spam" corrections as `negative`. See [Feedback from your application](/docs/sentinel/v2/features/similarity/#feedback-from-your-application).

## Monitoring & tuning

- **Find false positives.** Newsletters and transactional mail often trip `HTML_ONLY` and `BULK_MAILER`, and forwarded mail `DELIVERED_TO_MISMATCH` and `SPF`. Turn rules off per request with `X-Disable-Rules`, for example for mail from a known list server. Classifier rule names in that header replace the group's `classifier.disableRules`, so repeat `FREE_PROVIDER` there.
- **Watch the triggered rules.** With request logging set to **All**, each call is logged with its EML rules, followed by the classifier rules of its `CLASSIFICATION` part. The `triggeredRules` breakdown of `POST /v2/request-logs/_stats` for the mail key shows which rules fire most, for example how often `SPF` or `HTML_ONLY` triggers. See [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/#read-statistics).
- **Check the lists.** Root users see the `malicious-file-hashes` and `phishing` lists under **Remote Files**; until they download, `MALICIOUS_ATTACHMENT` and `LINK_PHISHING` never trigger. The `download_failures` alert reports a list that keeps failing. See [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/).
- **Large messages.** A `413 PAYLOAD_TOO_LARGE` means a message is over `[eml] max_body_size`. Raise it, or deliver such messages unscreened by policy.
- **Use your own hash list.** Point `[eml.malicious_hashes] url` at a list fed by your mail gateway or threat feed, to catch attachments you've already identified.

## Related

- [Email analysis (EML)](/docs/sentinel/v2/features/email-analysis/)
- [Phishing detection](/docs/sentinel/v2/features/phishing/)
- [Similarity & training data](/docs/sentinel/v2/features/similarity/)
- [Classifier rules & scores: EML rules](/docs/sentinel/v2/reference/classifier-rules/#email-eml-rules)
- [Object storage](/docs/sentinel/v2/configure/storage/)
- [API reference: `POST /v2/eml`](/sentinel-api-docs-v2.html#tag/eml/POST/v2/eml)
