Proofpoint API Patterns

Overview

The Proofpoint APIs provide programmatic access to email security data including threat events, quarantine management, people risk analytics, and URL defense. This skill covers authentication, base URLs, rate limiting, pagination, error handling, and best practices for API integration.

Proofpoint operates multiple API endpoints, each serving a different product area. All APIs share the same authentication mechanism but have different base URLs and rate limits.

Authentication

HTTP Basic Auth

All Proofpoint APIs use HTTP Basic Authentication with a service principal and secret:

GET /v2/siem/all?sinceSeconds=3600
Host: tap-api.proofpoint.com
Authorization: Basic <base64(service_principal:service_secret)>
Content-Type: application/json

Constructing the Authorization Header:

const credentials = Buffer.from(`${servicePrincipal}:${serviceSecret}`).toString('base64');
const headers = {
  'Authorization': `Basic ${credentials}`,
  'Content-Type': 'application/json'
};

# Using curl
curl -u "SERVICE_PRINCIPAL:SERVICE_SECRET" \
  "https://tap-api.proofpoint.com/v2/siem/all?sinceSeconds=3600"

Environment Variables

export PROOFPOINT_SERVICE_PRINCIPAL="your-service-principal"
export PROOFPOINT_SERVICE_SECRET="your-service-secret"
export PROOFPOINT_MCP_URL="https://proofpoint-mcp.wyre.workers.dev/mcp"

Obtaining Credentials

1. Log into the Proofpoint TAP Dashboard at https://threatinsight.proofpoint.com
2. Navigate to Settings > Connected Applications
3. Click Create New Credential
4. Copy the Service Principal and Service Secret
5. Store securely - the secret is shown only once

Important: Service credentials are scoped to your organization. Each MSP client organization requires its own set of credentials.

Base URLs

API Endpoints

Note: All APIs currently share the same base URL (tap-api.proofpoint.com) but are versioned and namespaced separately in the path.

API Versioning

Rate Limiting

Rate Limit Tiers

Rate Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1708012800

Rate Limit Response (HTTP 429)

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after the rate limit window resets.",
  "retryAfter": 60
}

Retry Strategy

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      const jitter = Math.random() * 5000;
      await sleep(retryAfter * 1000 + jitter);
      continue;
    }

    if (response.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await sleep(delay);
      continue;
    }

    return response;
  }

  throw new Error(`Request failed after ${maxRetries} retries`);
}

Pagination

TAP SIEM API Pagination

The TAP SIEM API does not use traditional offset-based pagination. Instead, it uses time-based windowing:

GET /v2/siem/all?sinceSeconds=3600
GET /v2/siem/all?sinceTime=2024-02-15T00:00:00Z
GET /v2/siem/all?interval=PT30M/2024-02-15T12:00:00Z

Quarantine API Pagination

GET /v2/quarantine/search?limit=25&offset=0
GET /v2/quarantine/search?limit=25&offset=25

People API Pagination

GET /v2/people/vap?window=30&size=100&page=1

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Bad Request",
  "message": "The sinceSeconds parameter must be between 1 and 86400.",
  "status": 400
}

Common Error Scenarios

Request Patterns

TAP SIEM All Events

GET /v2/siem/all?format=json&sinceSeconds=3600
Authorization: Basic <credentials>

TAP Messages Blocked

GET /v2/siem/messages/blocked?format=json&sinceSeconds=3600
Authorization: Basic <credentials>

TAP Messages Delivered

GET /v2/siem/messages/delivered?format=json&sinceSeconds=3600
Authorization: Basic <credentials>

TAP Clicks Permitted

GET /v2/siem/clicks/permitted?format=json&sinceSeconds=3600
Authorization: Basic <credentials>

People VAP Report

GET /v2/people/vap?window=30&size=20
Authorization: Basic <credentials>

Campaign Details

GET /v1/campaign/{campaignId}
Authorization: Basic <credentials>

Forensics Report

GET /v2/forensics?threatId={threatId}
Authorization: Basic <credentials>

Response Patterns

TAP SIEM Response Structure

{
  "queryEndTime": "2024-02-15T12:00:00Z",
  "messagesBlocked": [...],
  "messagesDeli