Activity & Audit Logs API

Stream real-time forwarding events, query paginated delivery logs, perform deep forensic X-Ray envelope analysis, and export compliance audit trails.

Quick Reference

Log Architecture & Privacy Protection

AliasFleet records operational metadata required for delivery troubleshooting while adhering to zero-knowledge privacy guarantees:

1. Envelope vs. Payload Separation: The log engine captures envelope routing metadata (sender, recipient alias, destination, spam scores, authentication verdicts, tracker count) but never stores the raw message bodies of forwarded emails.
2. Tracker Stripping Telemetry: When tracker blocking is active, the engine increments tracker counts and records detected tracker domains without logging user interaction behavior.
3. Forensic X-Ray: Detailed email headers, originating MTA IP addresses, and cryptographic signature validations (SPF, DKIM, DMARC) are available on demand for diagnostics through the X-Ray endpoint.

GET /v1/activity — Retrieve Activity Feed

Scope: activity:read · Rate Limit: 60/min · Idempotent: Yes

Returns recent workspace activity events in reverse chronological order, including forwarding actions, bounce detections, and security events.

Query Parameters

Example Request

curl -X GET "https://api.aliasfleet.com/v1/activity?limit=2" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "activities": [
    {
      "id": "email-evt_7f8a9b0c1d2e",
      "type": "email_forwarded",
      "title": "Email Forwarded",
      "description": "Forwarded message from billing@saas-provider.com to inbox",
      "timestamp": "2026-09-04T12:45:00.000Z",
      "metadata": {
        "aliasName": "subscriptions@acme-corp.com",
        "email": "billing@saas-provider.com"
      }
    },
    {
      "id": "act_8a9b0c1d2e3f4a5b",
      "type": "sender_blocked",
      "title": "Sender Blocked",
      "description": "Added scamnetwork.xyz to denylist",
      "timestamp": "2026-09-04T12:20:00.000Z",
      "metadata": {
        "sender": "scamnetwork.xyz"
      }
    }
  ]
}

GET /v1/activity/logs — Query Delivery Logs

Scope: activity:read · Rate Limit: 60/min · Idempotent: Yes

Queries unified inbound and outbound email delivery events with support for full-text search, event type filtering, date windowing, and pagination.

Query Parameters

Example Request

curl -X GET "https://api.aliasfleet.com/v1/activity/logs?page=1&limit=1&type=forwarded" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "logs": [
    {
      "id": "evt_9a8b7c6d5e4f3a2b",
      "type": "forwarded",
      "sender_email": "notifications@vendor.com",
      "sender_name": "Vendor Operations",
      "recipient_email": "inbox@primary-domain.com",
      "subject": "System Status Alert: Maintenance Window",
      "message_id": "<9f8e7d6c-5b4a-3a2b@vendor.com>",
      "created_at": "2026-09-04T12:40:00.000Z",
      "expires_at": "2026-10-04T12:40:00.000Z",
      "bounced": false,
      "spam_score": 0.2,
      "trackers_blocked_count": 3,
      "tracker_domains": ["tracking.pixel.com", "analytics.mail.net"],
      "security_status": {
        "spf": "pass",
        "dkim": "pass",
        "dmarc": "pass"
      },
      "ip_address": "198.51.100.42",
      "country_code": "US",
      "is_catchall_virtual": false,
      "alias_id": "al_6c5J5LMXd5E3Yq1Wx1zN",
      "alias_local_part": "vendor-alerts",
      "alias_domain": "acme-corp.com",
      "category_prediction": "transactional"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 1420,
    "totalPages": 1420
  },
  "retention": {
    "retentionDays": 30,
    "planRetention": 30,
    "logsCount": 1420
  }
}

GET /v1/activity/logs/:id/xray — Inspect Forensic X-Ray

Scope: activity:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves deep diagnostic telemetry for a specific delivery event, including cryptographic authentication checks (SPF, DKIM, DMARC), blocked spy pixels and tracking domains, and transit hops.

Path Parameters

Example Request

curl -X GET "https://api.aliasfleet.com/v1/activity/logs/evt_9a8b7c6d5e4f3a2b/xray" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "success": true,
  "telemetry": {
    "id": "evt_9a8b7c6d5e4f3a2b",
    "type": "forwarded",
    "alias": "vendor-alerts@acme-corp.com",
    "aliasId": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "sender": "notifications@vendor.com",
    "senderName": "Vendor Operations",
    "recipient": "inbox@primary-domain.com",
    "subject": "System Status Alert: Maintenance Window",
    "messageId": "<9f8e7d6c-5b4a-3a2b@vendor.com>",
    "bounced": false,
    "timestamp": "2026-09-04T12:40:00.000Z",
    "expiresAt": "2026-10-04T12:40:00.000Z",
    "spamScore": 0.2,
    "trackersBlockedCount": 3,
    "trackerDomains": [
      "tracking.pixel.com",
      "analytics.mail.net"
    ],
    "headers": {
      "x-mailer": "VendorMailer v4.2",
      "content-type": "text/html; charset=UTF-8"
    },
    "securityStatus": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass"
    },
    "ipAddress": "198.51.100.42",
    "countryCode": "US",
    "isCatchallVirtual": false,
    "localPart": "vendor-alerts",
    "domain": "acme-corp.com",
    "categoryPrediction": "transactional"
  }
}

Errors

GET /v1/activity/logs/export — Export Audit Logs

Scope: activity:read · Rate Limit: 10/min · Idempotent: Yes

Exports complete email delivery and audit logs for your workspace in structured JSON or CSV format for compliance archival and SIEM ingestion.

Query Parameters

Example Request: Export CSV

curl -X GET "https://api.aliasfleet.com/v1/activity/logs/export?format=csv" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -o "aliasfleet-audit-logs.csv"

Response Headers (200 OK)

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="aliasfleet-logs-2026-09-04.csv"

GET /v1/activity/retention — Inspect Log Retention

Scope: activity:read · Rate Limit: 60/min · Idempotent: Yes

Returns the active log retention window, oldest and newest log timestamps, and counts of log records scheduled for deletion.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/activity/retention" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "success": true,
  "retention": {
    "currentPlan": "business",
    "effectiveDays": 90,
    "planDays": 90,
    "isGracePeriod": false,
    "graceEndsAt": null,
    "logsCount": 4250,
    "oldestLog": "2026-06-06T10:15:00.000Z",
    "newestLog": "2026-09-04T12:45:00.000Z"
  },
  "expiring": {
    "expiringSoonCount": 18,
    "windowDays": 3
  }
}

GET /v1/activity/anonymization — Inspect Anonymization Settings

Scope: activity:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves the automated privacy anonymization policy configured for your workspace. When enabled, historical sender and recipient addresses are masked after a specified aging period.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/activity/anonymization" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "success": true,
  "anonymization": {
    "enabled": true,
    "afterDays": 30,
    "totalAnonymized": 312
  }
}