Monitor automated anomaly alerts, inspect abnormal delivery volume spikes, and review security telemetry across user email aliases.
Quick Reference#
| Endpoint | Method | Required Scope / Auth | Description |
|---|---|---|---|
/v1/security/suspicious-activity | GET | security:read | Retrieve active, unresolved suspicious traffic alerts for the account. |
/v1/security/suspicious-activity | POST | Interactive Session (Bearer) | Acknowledge and dismiss an active security alert. |
Anomaly Detection & Threat Heuristics#
AliasFleet continuously inspects incoming delivery envelopes to protect account reputation and detect credential abuse or spam targeting. The security engine evaluates traffic patterns against dynamic behavioral heuristics:
flowchart TD A["Inbound Delivery Stream"] --> B{"Burst Heuristics"} B -- "Normal Flow" --> C["Deliver to Forwarding Destination"] B -- "Spike > Baseline Threshold" --> D["Create Security Alert"] D --> E["Capture Forensic Envelope Samples"] E --> F["Notify Account & Flag in Security API"] F --> G{"Remediation Flow"} G -- "Interactive Session" --> H["POST /v1/security/suspicious-activity (Dismiss)"] G -- "Automation" --> I["Automated Quarantine via Rules Engine"]Anomaly Triggers#
- Volumetric Delivery Bursts: An alias receiving sudden, high-frequency inbound transmissions that significantly deviate from historical hourly baselines.
- Brute-Force Sender Probing: Repetitive message attempts from rotating subdomains, ephemeral origin servers, or recognized spam distribution networks.
- Repeated Denylist Collisions: Multiple consecutive delivery attempts from sender addresses or domains explicitly configured in your inbound firewall denylist.
List Active Security Alerts#
GET /v1/security/suspicious-activity
Retrieves all active, unresolved security alerts generated for the authenticated user's aliases. Alerts remain active until explicitly dismissed.
security:readRate Limit: 60 req/minIdempotent: YesQuery Parameters#
This endpoint accepts no query parameters. It returns all unresolved alerts for the authenticated tenant ordered by lastAttemptAt descending.
Request Headers#
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Optional* | Bearer afp_... |
x-api-key | string | Optional* | afp_... (*Provide either Authorization or x-api-key). |
Accept | string | Yes | application/json |
cURL Example#
curl -X GET "https://api.aliasfleet.com/v1/security/suspicious-activity" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
{ "alerts": [ { "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "aliasId": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b", "aliasEmail": "billing.alerts@mycompany.com", "attemptCount": 142, "sampleSenders": [ "spammer@suspicious-relay.xyz", "crawler-bot@host-node-4.net" ], "sampleSubjects": [ "Urgent invoice payment required", "Undelivered package notification" ], "firstAttemptAt": "2026-09-04T06:12:00.000Z", "lastAttemptAt": "2026-09-04T07:45:22.000Z", "alertSentAt": "2026-09-04T07:46:00.000Z" } ], "count": 1}Response Fields#
| Field | Type | Description |
|---|---|---|
alerts | array | List of active security alert objects. |
alerts[].id | string | Unique UUID for the security alert. |
alerts[].aliasId | string | The target alias UUID identifier. |
alerts[].aliasEmail | string | Full email address of the affected alias. |
alerts[].attemptCount | integer | Total number of delivery attempts detected during the incident window. |
alerts[].sampleSenders | string[] | Up to 5 sample sender email addresses identified during the anomaly. |
alerts[].sampleSubjects | string[] | Up to 5 sample subject headers captured from incoming message envelopes. |
alerts[].firstAttemptAt | string | ISO 8601 timestamp of the initial anomalous delivery attempt. |
alerts[].lastAttemptAt | string | ISO 8601 timestamp of the most recent delivery attempt. |
alerts[].alertSentAt | string | ISO 8601 timestamp when the security notification was dispatched. |
count | integer | Total count of unresolved security alerts. |
Error Responses#
| Status Code | Code | Error Message | Solution |
|---|---|---|---|
401 | UNAUTHORIZED | "Unauthorized: Missing API Key or Session Token" | Provide a valid API key or session token. |
403 | INSUFFICIENT_SCOPES | "Forbidden: Insufficient scopes" | Ensure your API key includes security:read or security:write. |
429 | RATE_LIMIT_EXCEEDED | "Too Many Requests" | Respect the 60 requests per minute rate limit. |
500 | DATABASE_ERROR | "Database query failed" | Retry request with exponential backoff. |
Dismiss Security Alert#
POST /v1/security/suspicious-activity
Acknowledges and dismisses an active security alert, removing it from the active alert queue and recording human-in-the-loop resolution metadata.
Interactive Session Required: To prevent automated scripts or compromised API keys from suppressing security notifications without human review, this endpoint strictly requires an interactive user session Bearer token. Standard developer API keys (afp_...) will receive an HTTP 403 SESSION_REQUIRED response.
Request Headers#
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer <SESSION_JWT_TOKEN> (Interactive dashboard session). |
Content-Type | string | Yes | application/json |
Request Body Schema#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
alertId | string | Yes | Valid alert UUID | The unique identifier of the alert to dismiss. |
action | string | Yes | Must be "dismiss" | The resolution action to execute. |
cURL Example#
curl -X POST "https://api.aliasfleet.com/v1/security/suspicious-activity" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "alertId": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "action": "dismiss" }'Response (200 OK)#
{ "success": true, "message": "Alert dismissed"}Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | BAD_REQUEST | "alertId required" | Missing alertId parameter in the request payload. |
400 | BAD_REQUEST | "Invalid action" | The action field must be "dismiss". |
403 | SESSION_REQUIRED | "Forbidden: This endpoint is restricted to interactive dashboard sessions and cannot be accessed using an API key." | Attempted dismissal with an API key (afp_...) instead of an interactive session token. |
429 | RATE_LIMIT_EXCEEDED | "Too Many Requests" | Client exceeded the 60 requests per minute limit. |
Threat Remediation Best Practices#
When an alert indicates anomalous delivery activity on an alias, consider the following defense-in-depth remediation steps:
1. Inbound Firewall Rules#
If the alert identifies persistent bad actor domains in sampleSenders, add an envelope denylist rule via the Sender Rules API:
curl -X POST "https://api.aliasfleet.com/v1/sender-rules/blacklist" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Content-Type: application/json" \ -d '{ "emailPattern": "suspicious-relay.xyz", "patternType": "domain", "reason": "Blocked following volumetric burst alert" }'2. Automated Quarantine via Rules Engine#
Configure conditional rules in the Rules Engine API to inspect high-risk indicators (such as spam_score > 5.0 or missing SPF/DKIM verification) and route them to quarantine or silent drop:
{ "name": "Quarantine High Spam Inbound", "priority": 10, "match_type": "ANY", "conditions": [ { "field": "spam_score", "operator": "greater_than", "value": "5.0" } ], "actions": [ { "action_type": "quarantine" } ], "stop_processing": true}3. Alias Deactivation or Rotation#
If an alias has been exposed in a public leak or credential stuffing campaign, disable inbound forwarding immediately by moving it to the trash via the Aliases API:
curl -X POST "https://api.aliasfleet.com/v1/aliases/9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c/trash" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"