Skip to main content
ALTCHA®

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

ThreatWhat catches it
Phishing linksLINK_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 compromiseDMARC_ALIGNMENT, SPF, DKIM, ARC, FROM_SPOOFING (an address in the display name) and REPLY_TO_SPOOFING.
Malware attachmentsMALICIOUS_ATTACHMENT (the malicious-hash list) and ATTACHMENT_RISK: executables, macros, disk images, encrypted archives, double extensions, type mismatches.
SpamThe classifier's text, sender and IP rules (the CLASSIFICATION rule), plus BULK_MAILER, HIDDEN_TEXT and structural anomalies.
Repeats of spam you already reportedSimilarity with your own training groups, and CAMPAIGN for the same message from many sending servers.

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 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 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.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 setupSend
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 messageX-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 applyX-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';
}
VerdictTypical action
quarantineKeep the message away from users; let an administrator release it.
spamDeliver to the spam folder, or create the ticket as spam.
warnDeliver with a banner such as "The sender's address doesn't match their name."
deliverDeliver 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_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.
  • 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.
  • 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.

Start typing to search...

↑ ↓ Navigate ↵ Select