Scan an email for phishing and malware
scan_emailScan ONE email message for phishing and malware before delivering, opening or acting on it. Send the raw message (eml, preferred) or the fields you already parsed (message: headers, text, html, attachment names, types and digests). Returns a verdict (malicious | suspicious | clean | inconclusive), a recommendedAction (quarantine | review | warn | deliver), a 0-100 riskScore, a headline you can relay as is, the strongest reasons, and what it could not check (coverage.skipped). It reads the sender and Reply-To, the connecting server, every link host and every attachment hash against threat intelligence, plus the tells of a phishing message: link text that names another site, a domain or a display name that imitates a well-known brand, a program named like a document, a display name that shows another address, credentials in a URL, an IDN homograph. From a raw message it also reads attachments for structure, never running them: the file type from its bytes, macros and remote templates in Office files, risky entries in archives, PDF actions, HTML that rebuilds a file in the browser; a message attached to it is read as a message of its own. It also flags text aimed at an AI reading the mail (prompt injection, including text hidden from a person). It never runs an attachment, fetches a link or calls a third party while you wait. malicious needs a listing in our data: the shape of a message alone asks for a review at most. clean is a positive claim and needs your own receiving system's DMARC pass: pass authservId (the id it writes in its Authentication-Results header) or trustAuthenticationResults, otherwise a message with nothing against it is inconclusive, which is not safe. deliver means no objection from this scan; never use it to release a message another engine quarantined. Costs one scan of the scan meter per message, whatever its size (not a request of the monthly quota).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| eml | No | The whole message as RFC 5322 text (a .eml file), headers first. Up to 10 MiB. Preferred when you have it: attachments are then read for structure. Use message for one that is too large, or that you only have parsed. Send exactly one of eml and message. | |
| message | No | A message you already parsed (Microsoft Graph, Gmail API…). Attachments carry digests, not bytes, so their structure is not read. Send exactly one of eml and message. | |
| authservId | No | The authserv-id your receiving system writes in its Authentication-Results header (for example mx.google.com). Only a header carrying it is read as SPF/DKIM/DMARC evidence, because anyone can write one into a message. | |
| trustedHops | No | How many Received headers, counted from the top, your own servers wrote. The connecting server is the one the last of them recorded. Default 1. | |
| connectingIp | No | The IP address that connected to your infrastructure, when you already have it. Overrides the Received chain. | |
| trustAuthenticationResults | No | True when every Authentication-Results header in the message was added by your own infrastructure (Exchange Online writes it with no authserv-id). Needed, with or instead of authservId, for a message to be clean. |