Inbound email screening
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:
[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 spamTo 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 and [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) preset with the IPs of the hosts that call Sentinel, and add a classifier rule after it:
{
"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.
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:
curl https://sentinel.example.com/v2/eml \
-u 'key_…:sec_…' \
-H 'Content-Type: message/rfc822' \
-H 'X-Attachments-Size-Limit: 1' \
--data-binary @message.emlUse --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.
The same call in code:
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;
}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:
{
"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:
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; scores in Classifier rules & scores.
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:
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."}'{ "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.
Monitoring & tuning
- Find false positives. Newsletters and transactional mail often trip
HTML_ONLYandBULK_MAILER, and forwarded mailDELIVERED_TO_MISMATCHandSPF. Turn rules off per request withX-Disable-Rules, for example for mail from a known list server. Classifier rule names in that header replace the group'sclassifier.disableRules, so repeatFREE_PROVIDERthere. - 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
CLASSIFICATIONpart. ThetriggeredRulesbreakdown ofPOST /v2/request-logs/_statsfor the mail key shows which rules fire most, for example how oftenSPForHTML_ONLYtriggers. See Request logs & analytics. - Check the lists. Root users see the
malicious-file-hashesandphishinglists under Remote Files; until they download,MALICIOUS_ATTACHMENTandLINK_PHISHINGnever trigger. Thedownload_failuresalert reports a list that keeps failing. See Remote files & data sources. - Large messages. A
413 PAYLOAD_TOO_LARGEmeans 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] urlat a list fed by your mail gateway or threat feed, to catch attachments you've already identified.