Essentials Threat API

ccAddresses

Array of strings

A list of email addresses contained within the CC: header, excluding friendly names.

stackName

String

The name of the Essentials stack which processed the message.

customerEid

String

The customers entity ID.

customerName

String

The customer's name, as configured in Essentials.

parentEid

String

The parent's EID.

parentName

String

The parent's name, as configured in Essentials.

completelyRewritten

String

• true

• false

• na

The rewrite status of the message. If value is 'true', all instances of URL threats within the message were successfully rewritten. If the value is 'false', at least one instance of the a threat URL was not rewritten. If the value is 'na', the message did not contain any URL-based threats.

fromAddress

String

The email address contained in the From: header, excluding friendly name.

GUID

String

The ID of the message within PPS. It can be used to identify the message in PPS and is guaranteed to be unique.

headerFrom

String

The full content of the From: header, including any friendly name.

headerReplyTo

String

 If present, the full content of the Reply-To: header, including any friendly names.

impostorScore

int

0-100

The impostor score of the message. Higher scores indicate higher certainty.

malwareScore

int

0-100

The malware score of the message. Higher scores indicate higher certainty.

messageDetailsUrl

String

A permalink to the messages' details page.

messageID

String

Message-ID extracted from the headers of the email message. It can be used to look up the associated message in PPS and is not unique.

messageParts

Array of JSON Structures

An array of structures which contain details about parts of the message, including both message bodies and attachments.

messageParts/contentType

String

The true, detected Content-Type of the messagePart. This may differ from the oContentType value.

messageParts/disposition

String

• inline

• attached

If the value is "inline," the messagePart is a message body. If the value is "attached," the messagePart is an attachment.

messageParts/filename

String

The filename of the messagePart.

messageParts/md5

String

The MD5 hash of the messagePart contents.

messageParts/oContentType

String

The declared Content-Type of the messagePart.

messageParts/sandboxStatus

String

• unsupported

• threat

• clean

• prefilter

• uploaded

• inprogress

• uploaddisabled

The verdict returned by the sandbox during the scanning process. If the value is "unsupported", the messagePart is not supported by Attachment Defense and was not scanned. If the value is "clean", the sandbox returned a clean verdict. If the value is "threat", the sandbox returned a malicious verdict. If the value is "prefilter", the messagePart contained no active content, and was therefore not sent to the sandboxing service. If the value is "uploaded," the message was uploaded by PPS to the sandboxing service, but did not yet have a verdict at the time the message was processed. If the value is "inprogress," the attachment had been uploaded and was awaiting scanning at the time the message was processed. If the verdict is "uploaddisabled," the attachment was eligible for scanning, but was not uploaded because of PPS policy.

messageParts/sha256

String

The SHA256 hash of the messagePart contents.

messageSize

Integer

The size in bytes of the message, including headers and attachments.

messageTime

DateTime

ISO8601 Timestamp

When the message was delivered to the user or quarantined by PPS

phishScore

int

0-100

The phish score of the message. Higher scores indicate higher certainty.

quarantineRule

String

The name of the rule which quarantined the message. This appears only for messagesBlocked events.

recipient

String

Email Address

An array containing the email addresses of the SMTP (envelope) recipients

replyToAddress

String

The email address contained in the Reply-To: header, excluding friendly name.

sender

String

Email Address

The email address of the SMTP (envelope) sender. The user-part is hashed. The domain-part is cleartext.

senderIP

String

IP Address

The IP address of the sender.

spamScore

int

0-100

The spam score of the message. Higher scores indicate higher certainty.

subject

String

The subject line of the message, if available.

threatsInfoMap

Array of JSON Structures

An array of structures which contain details about detected threats within the message. There may be more than one threat per message.

threatsInfoMap/detectionType

String

Nullable

New field detectionType and ThreatInfo added to response

threatsInfoMap/classification

String

• Malware

• Phish

• Spam

• Impostor (for BEC/Message Text threats)

• TOAD (Telephone-Oriented Attack Delivery)

The category of threat found in the message

threatsInfoMap/threat

String

• SHA256

• URL

• email address

The artifact which was condemned by Proofpoint. The malicious URL, hash of the attachment threat, or email address of the impostor sender.

threatsInfoMap/threatId

String

The unique identifier associated with this threat. It can be used to query the forensics and campaign endpoints.

threatsInfoMap/threatStatus

String

• active

• falsepositive

• cleared

The current state of the threat.

threatsInfoMap/threatTime

DateTime

ISO8601 Timestamp

Proofpoint assigned the threatStatus at this time.

threatsInfoMap/threatType

String

• Attachment

• URL

• Message

Whether the threat was an attachment, URL, or message type.

threatsInfoMap/actors

Array of JSON Structures

An array of structures which contain details about the actors associated with a threat

toAddresses

Array of strings

A list of email addresses contained within the To: header, excluding friendly names.

xmailer

String

The content of the X-Mailer: header, if present.

classification

String

• Malware

• Phish

• Spam

The threat category of the malicious URL

clickIP

String

IP Address

The external IP address of the user who clicked on the link. If the user is behind a firewall performing network address translation, the IP address of the firewall will be shown.

clickTime

DateTime

ISO8601 Timestamp

The time the user clicked on the URL

GUID

String

The ID of the message within PPS. It can be used to identify the message in PPS and is guaranteed to be unique.

id

String

The unique id of the click.

recipient

String

Email Address

The email address of the recipient

sender

String

Email Address

The email address of the sender. The user-part is hashed. The domain-part is cleartext.

senderIP

String

IP Address

The IP address of the sender

threatID

String

The unique identifier associated with this threat. It can be used to query the forensics and campaign endpoints. 

threatTime

DateTime

ISO8601 Timestamp

Proofpoint identified the URL as a threat at this time.

threatStatus

String

• active

• falsepositive

• cleared

The current state of the threat.

url

String

URL

The malicious URL which was clicked

userAgent

String

The User-Agent header from the clicker's HTTP request