SpamTitan Quarantine

SpamTitan Quarantine Management

Overview

SpamTitan's quarantine holds inbound emails that its filtering engine determines are likely spam, phishing, or malware. Administrators and end users can review held messages and either release legitimate emails (false positives) or permanently delete spam. For MSPs managing multiple clients, efficient quarantine management is critical to preventing false positives from disrupting business communications while ensuring malicious mail is never delivered.

Anti-triggers

• Managing a sender list as a decision in its own right — allowlisting the sender of one released message is a follow-up call, covered here. Auditing, scoping, or removing list entries is SpamTitan Lists.
• Mail that already reached the mailbox — SpamTitan filters in front of the tenant and cannot reach into an inbox. Clawing back delivered mail is Abnormal Security Threats or IRONSCALES Incidents.
• A quarantine belonging to a different gateway — every mail security product in this fleet has one and none of them share message IDs. Use Mimecast Message Tracking for its hold queue, Proofpoint Quarantine, or Checkpoint Avanan Quarantine.

Key Concepts

Quarantine Types

SpamTitan maintains separate quarantine queues for different threat categories:

• Spam — High-confidence unsolicited commercial email
• Probable Spam — Lower-confidence spam; may include false positives
• Phishing — Detected phishing or credential harvesting attempts
• Virus/Malware — Emails containing detected malware (generally never released)
• Blocked — Emails matching admin blocklist rules

Release vs. Delete

• Release — Delivers the held message to the recipient's inbox. Use for confirmed false positives.
• Delete — Permanently removes the message. Use for confirmed spam or malicious mail.
• Virus-quarantined messages should never be released — malware detections are high-confidence.

Message Aging

Quarantined messages are retained for a configurable period (typically 30 days). Messages older than the retention period are automatically purged. Review the queue regularly to catch time-sensitive false positives before they expire.

Multi-Domain Management — the queue is not tenant-scoped

In MSP deployments SpamTitan typically filters mail for multiple client domains, and the natural instinct is to scope the quarantine listing to one customer. You cannot. spamtitan_get_queue accepts no domain parameter. Its shipped input schema is exactly page, per_page, sender, recipient, subject, reason (spamtitan-mcp/src/domains/quarantine.ts:21-53).

What follows from that:

• An operator who asks for "customer X's quarantine" gets the appliance-wide queue, across every tenant, unless you narrow it yourself.
• Per-customer filtering is a client-side operation on the recipient field after the results come back. There is no server-side tenant boundary on this call other than the API key itself.
• Never describe an unfiltered listing as belonging to one customer, and never act on "the first result" from one. The release and delete that follow are scoped only by message_id, so a cross-tenant listing leads directly to a cross-tenant action.
• The asymmetry is what makes this easy to miss: the sibling spamtitan_get_stats does take domain, so per-domain statistics are genuinely scoped while the queue beside them is not.

The server does help a little: calling spamtitan_get_queue with none of sender, recipient, subject, or reason triggers an elicitation asking the caller for a recipient filter. That is a prompt, not a control — an unattended agent cannot answer it, and a caller can decline it.

API Patterns

List Quarantine Queue

spamtitan_get_queue

Parameters (this is the complete list — there is no domain, quarantine_type, date_from, or date_to):

• page — Page number (1-based, default 1)
• per_page — Results per page (default 50, max 200)
• sender — Filter by sender email address
• recipient — Filter by recipient email address. The only lever that approximates per-customer scope, and it matches a full address, not a domain
• subject — Filter by subject (partial match)
• reason — Filter by quarantine reason (e.g. spam, virus, policy)

Example response (the domain field appears in the response payload; it is not a request parameter):

{
  "messages": [
    {
      "id": "q-00192873",
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Your Weekly Industry Update",
      "received_at": "2026-03-02T07:30:00Z",
      "quarantine_type": "probable_spam",
      "score": 6.8,
      "domain": "clientcorp.com"
    }
  ],
  "page": 1,
  "per_page": 50
}

On a multi-tenant appliance the messages array will contain entries whose to and domain belong to other customers. That is the expected result of an unfiltered call, not a bug — filter on to before you use it.

Get Message Details

spamtitan_get_message

Parameters:

• message_id — The quarantine message ID (required, and the only parameter)

Example response:

{
  "id": "q-00192873",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your Weekly Industry Update",
  "received_at": "2026-03-02T07:30:00Z",
  "quarantine_type": "probable_spam",
  "score": 6.8,
  "score_breakdown": {"rdns": 0.5, "spf": 0.0, "dkim": 0.0, "content": 5.2, "uri": 1.1},
  "headers": {
    "reply_to": "[email protected]",
    "received_spf": "pass",
    "dkim": "pass",
    "list_unsubscribe": "<mailto:[email protected]>"
  },
  "links": ["https://vendor-newsletter.com/weekly-update/2026-03-02"],
  "attachments": [],
  "domain": "clientcorp.com"
}

Release a Quarantined Message

spamtitan_release_message

Parameters:

• message_id — The quarantine message ID to release (required, and the only parameter). There is no add_to_allowlist option — releasing and allowlisting are two separate calls.

To release and allowlist the sender, make the second call explicitly: spamtitan_manage_allowlist with action: "add", sender, and a note. Doing it in two steps is not a workaround; it is the only shape the server offers, and it means the allowlist grant is a deliberate decision of its own rather than a checkbox on a release. Treat it that way — an allowlist entry is a durable bypass of spam scoring for that sender, and spoofed mail claiming to be that sender inherits it.

Example — {"message_id": "q-00192873"} returns {"success": true, "message": "Message q-00192873 released successfully"}.

Delete a Quarantined Message

spamtitan_delete_message

Parameters:

• message_id — The quarantine message ID to delete (required, and the only parameter). There is no bulk-delete tool; one call deletes one message.

Example response:

{
  "success": true,
  "message": "Message q-00192874 deleted successfully"
}

Get Email Statistics

spamtitan_get_stats

Parameters:

• period — One of today, yesterday, last_7_days, last_30_days, last_90_days (default today). These are the only accepted values; there is no custom date range.
• domain — Filter to a single customer domain (omit for appliance-wide stats). This is the one place per-domain scoping works — the queue listing has no equivalent.

Example — one customer's last seven days:

{
  "period": "last_7_days",
  "domain": "clientcorp.com"
}

Example response:

{
  "stats": {
    "inbound": {"total": 4821, "delivered": 4102, "quarantined": 687, "blocked": 32},
    "quarantine_breakdown": {"spam": 512, "probable_spam": 143, "phishing": 28, "virus": 4},
    "spam_rate": 0.1424,
    "top_quarantine_senders": [{"sender": "[email protected]", "count": 84}]
  },
  "period": "last_7_days",
  "domain": "clientcorp.com"
}

The server echoes domain as "all" when you omit it — a useful check that the scope you got is the scope you meant.

Common Workflows

Daily Quarantine Review

1. Call spamtitan_get_stats with period=today (and domain for one customer) to get a quick overview of email volume and spam rates
2. Call spamtitan_get_queue to list held messages. There is no date filter, so page through and cut by received_at yourself; there is no domain filter either, so if this is a per-customer review, filter the results on the recipient's domain before you look at anything else
3. Sort by score — low-scoring probable_spam messages are most likely to be false positives
4. Review subject lines and senders for obvious spam vs. legitimate business mail
5. Release confirmed false positives with spamtitan_release_message (one message_id per call)
6. Delete confirmed spam and phishing with spamtitan_delete_message
7. For frequently falsely-quarantined senders, make a separate spamtitan_manage_allowlist call with action: "add" — release does not allowlist

Investigating a Specific Held Message

1. Get full message details with spamtitan_get_message
2. Review the score breakdown — high content and URI scores indicate spam/phishing; high rdns scores may indicate misconfigured legitimate senders
3. Check SPF and DKIM pass/fail status — passing auth for a low-score message suggests a legitimate sender
4. Look for List-Unsubscribe headers — legitimate marketing mail from reputable senders includes this
5. Evaluate the links — legitimate newsletters link to recognizable domains
6. Release if confident it is legitimate; delete if spam or phishing

Handling a Client Complaint About Missing Email

1. Identify the expected sender and recipient
2. Call spamtitan_get_queue with sender and recipient filters to find the held message — this is the one workflow where the available filters do scope tightly, because you have a full recipient address
3. Review the message details and score to confirm it was incorrectly quarantined
4. Release the message with spamtitan_release_message
5. To prevent recurrence, make a second call to spamtitan_manage_allowlist with action: "add", the sender, and a note recording why. Verify the sender is genuinely legitimate first — this grants a durable scoring bypass that spoofed mail claiming to be that sender will inherit
6. Communicate the resolution to the client with a note that the sender has been allowlisted

Monitoring for Phishing Campaigns

1. Call spamtitan_get_queue with reason set to the appliance's phishing reason string. There is no quarantine_type parameter and no date filter, so page the queue and cut to the last 24 hours yourself
2. Review sender domains and subject patterns for coordinated campaign indicators
3. If multiple recipients received the same phishing mail, check whether any slipped through (quarantine miss)
4. Delete all confirmed phishing messages
5. If the sending domain is new, add it to the blocklist to prevent future delivery

Error Handling

Message Not Found

Cause: Invalid message ID, or message has already expired from the retention period Solution: List the quarantine queue to verify the correct ID; check retention settings if messages are expiring sooner than expected

Release Failed — Virus Quarantine

Cause: SpamTitan blocks release of virus-quarantined messages by default Solution: Virus-quarantined messages should not be released; if a false positive is suspected, contact TitanHQ support for manual review

Permission Denied on Domain

Cause: The API key may not have access to all domains in multi-tenant deployments Solution: Verify the API key scope. Note that the API key is the only tenant boundary on the quarantine tools — there is no per-call domain scope to fall back on.

Statistics Return Zero

Cause: The domain value passed to spamtitan_get_stats may not match the configured domain name exactly Solution: Call spamtitan_get_stats without domain to get appliance-wide numbers, and spamtitan_status to see the domains the connection reports

Best Practices

• Review the quarantine queue at least once per business day; twice daily for high-volume clients
• Treat every spamtitan_get_queue result as cross-tenant until you have filtered it yourself. There is no domain filter on the call; filter on recipient, or cut the results on the recipient's domain, before showing an operator anything labelled as one customer's quarantine
• Release and allowlist are separate calls — spamtitan_release_message then spamtitan_manage_allowlist with action: "add" and a note
• Never release virus-quarantined messages — deletion is the only appropriate action
• Use spamtitan_get_stats with domain to identify customers with unusually high spam rates; this is the one call that does scope per domain
• Keep an eye on the top_quarantine_senders list — persistent senders should be blocklisted
• Delete acts on one message_id at a time; document each batch you work through in your PSA ticketing system for client audit trails

Related Skills

• api-patterns - Authentication, pagination, and error handling
• lists - Allowlist and blocklist management