SpamTitan MCP Tools & API Patterns

Overview

The SpamTitan MCP server provides AI tool integration with the SpamTitan email security platform by TitanHQ. It exposes tools covering quarantine queue management, email flow statistics, and sender allowlist/blocklist management. The API uses an API key passed as an HTTP header.

Connection & Authentication

API Key Header Auth

SpamTitan authenticates using an API key passed via HTTP header:

Generate credentials at: SpamTitan Admin Interface > Settings > API

Environment Variables:

export SPAMTITAN_API_KEY="your-api-key"

IMPORTANT: Never hardcode credentials. Always use environment variables.

Available MCP Tools

Quarantine Management

Email Statistics

List Management

Pagination

The SpamTitan API uses page/limit style pagination:

• Pass page (1-based) and limit parameters
• Continue fetching pages until the result count is less than the limit

Example workflow:

1. Call spamtitan_get_queue with page=1&limit=100
2. If 100 results returned, call again with page=2
3. Repeat until fewer than limit results are returned

Rate Limiting

SpamTitan enforces API rate limits per API key:

• HTTP 429 responses indicate rate limit exceeded
• Wait before retrying — use exponential backoff
• Use date range filters to reduce result set sizes
• Avoid polling at high frequency; fetch on demand

Error Handling

Common Error Codes

Error Response Format

{
  "error": {
    "code": 401,
    "message": "Invalid or missing API key"
  }
}

Best Practices

• Use date range filters when listing the quarantine queue to avoid pulling the full history
• Use domain filters to scope queries to specific customer domains in multi-tenant deployments
• Use bulk actions (release or delete) rather than individual calls when processing multiple messages
• Always confirm before bulk-deleting quarantined messages — deletion is irreversible
• Handle rate limits gracefully with exponential backoff
• Log all list management changes (allowlist/blocklist) for audit trail purposes

Related Skills

• quarantine - Quarantine queue management
• lists - Sender allowlist and blocklist management