Checkpoint Harmony Email Quarantine and Message Actions

Overview

Where an event is a verdict, an entity is the thing that was scanned — usually the email, with its subject, sender, recipients and attachments. Quarantine and restore operate on entities. Day-to-day MSP work here is finding a message a user says is missing, judging whether the detection was right, and either leaving it held or delivering it.

Anti-triggers

• Why the message was flagged — the engine verdict, type, severity and

confidence are on the detection record. Use avanan-threats.

• Stopping a sender being flagged again — a release delivers one message

and changes nothing standing. Sender allow entries are avanan-exceptions.

• Search-and-destroy in a delivered mailbox on another stack — Proofpoint

TRAP is proofpoint-forensics; Microsoft 365 mailbox operations are cipp-mailboxes.

• Another vendor's quarantine — "release from quarantine" is shared

vocabulary. Proofpoint is proofpoint-quarantine, SpamTitan is spamtitan-quarantine, Mimecast calls it the held queue (mimecast-queue-management), Abnormal is abnormal-security-cases.

Finding a message

hec_search_emails requires `saas` and `startDate`. saas here is a single string, not an array — unlike the events surface, which takes a list. Everything else is optional.

Attribute matching goes in filters, an array of triples:

{
  "saas": "office365_emails",
  "startDate": "2026-07-01T00:00:00Z",
  "filters": [
    { "saasAttrName": "fromEmail", "saasAttrOp": "is",
      "saasAttrValue": "[email protected]" },
    { "saasAttrName": "isQuarantined", "saasAttrOp": "is",
      "saasAttrValue": true }
  ]
}

Operators: is, isNot, contains, notContains, startsWith, isEmpty, isNotEmpty, greaterThan, lessThan. isEmpty and isNotEmpty take no saasAttrValue.

Useful attribute names: fromEmail, subject, recipients, isQuarantined, attachmentMd5.

There is no free-text query argument and no field argument — all matching is through this structure. The operator list has no or and filters do not nest, so an either/or sender search is two calls whose results you merge.

What an entity carries

The search result summarises each hit as entityId, saas, entityCreated, subject, from, to, isQuarantined, isRestored, verdict and availableActions. hec_get_email returns the full record:

• `entityPayload` — internetMessageId, subject, received,

fromEmail, fromName, to, cc, recipients, attachmentCount, and attachments with each file's name, mimetype, size and MD5.

• `entitySecurityResult.combinedVerdict` — the engines' combined judgement.
• `entityAvailableActions` — what this entity will accept right now.
• `isQuarantined` / `isRestored` — the two flags that answer "where is

this message". Both true means it was held and then delivered.

Attachment MD5 is the hash the payload exposes; there is no SHA-256 field here despite SHA-256 being the more common currency downstream.

Acting on mail

Four tools, two operations, two id namespaces:

Use whichever id you already hold. They reach the same underlying action.

Actions are asynchronous

None of the four completes inline. Each returns one `taskId` per entity, and the call returning successfully means the work was accepted, not done. Poll each with hec_get_task_status. An agent that reports "released" off the back of the action call alone is reporting an intention.

Restore is the sharp one

Restoring delivers a message the security stack judged malicious into a real person's inbox, and there is no un-deliver. When the detection was malware or BEC, an erroneous restore is precisely the outcome the product exists to prevent.

Note the asymmetry in how the tools are annotated: the two quarantine tools carry destructiveHint: true and prompt for confirmation, while the restore tools carry no annotations at all. A client that gates on destructiveHint will therefore wave restores through and stop on quarantines — the opposite of the risk ordering. Require a human on restores explicitly; do not rely on the tool metadata to ask.

Before any restore, confirm the sender with the customer out of band, read the entity's combinedVerdict rather than the summary alone, and check whether other recipients received the same message.

Reading a quarantine decision

Harmony Email does not expose a "quarantine reason" field. The reason is the detection that caused it, so the mapping runs through the event type:

A malicious_url_click event means a user already reached the destination. Releasing or holding the message is then secondary to credential response.

Gotchas

• Batches are not transactional. The tool schema sets only minItems: 1

with no upper bound, but the API caps a single action call (GOVERNANCE.md records 100 entities). Splitting a large action into batches performs several independent irreversible operations; a failure partway leaves a mixed state with nothing to roll back. Poll every taskId, not just the last.

• `startDate` is mandatory, so "search everything" is impossible. A user

reporting a message from "a while ago" needs a window guessed and widened, and retention bounds how far back that can go.

• Quarantine expiry is a hard deletion. Entries age out after the

tenant's retention period (30 days by default) and cannot be recovered. There is no tool that reads or extends retention; the only documented workaround — release and re-quarantine — means briefly delivering the message.

• An empty search is not proof of absence. Wrong saas value, wrong

region, or a window that misses the message all return zero records without an error.

Capability gaps

• No delete. The surface has quarantine and restore only. There is no way

to permanently delete a held message; that is a console action.

• No release-with-allow-list. Releasing and creating a sender exception

are two separate operations against two different tools.

• No message body or attachment download. Names, sizes, MIME types and

MD5 hashes are exposed; the content is not.

• No notification. Nothing here tells a recipient their mail was held or

released.

Related Skills

• Checkpoint Threats — why it was held
• Checkpoint Exceptions — stopping it recurring
• Checkpoint API Patterns — ids, paging, auth