Query fleet-wide email forwarding volumes, time-series delivery trends, spam threat scores, tracker blockage telemetry, and vendor exposure graphs.
Quick Reference#
| Endpoint | Method | Required Scope | Description |
|---|---|---|---|
/v1/analytics | GET | analytics:read | Retrieve high-level fleet forwarding and alias volume metrics. |
/v1/analytics/dashboard | GET | analytics:read | Query time-series delivery, block, and reply activity. |
/v1/analytics/alias/:aliasId | GET | analytics:read | Inspect deliverability metrics for a specific alias (Business plan). |
/v1/analytics/spam-analysis/:aliasId | GET | analytics:read | Retrieve AI-generated spam analysis report and threat metrics. |
/v1/analytics/roi | GET | analytics:read | Retrieve tenant privacy ROI metrics (hours/bytes saved, threats blocked). |
/v1/analytics/vendor-graph | GET | analytics:read | Map external vendor relationships and cross-alias exposure. |
/v1/analytics/mta-origins | GET | analytics:read | Inspect geographic distribution of sending mail transfer agents. |
Tier Access & Analytics Capabilities#
| Feature | Free Tier | Pro Tier | Business Tier |
|---|---|---|---|
| Fleet Overview | Basic counters & top 5 aliases | Full overview, categories, domains, top 10 aliases | Full overview, all categories, domains, and full top aliases |
| Time-Series Dashboard | Basic delivery counters (is_degraded: true) | Detailed email trends, top senders, peak hours, bounce analytics | Detailed email trends, top senders, peak hours, bounce analytics |
| Per-Alias Analytics | Locked (is_upgrade_required: true) | Locked (is_upgrade_required: true) | Full per-alias metrics |
| AI Spam Analysis | HTTP 403 UPGRADE_REQUIRED | Full AI Report & Metrics | Full AI Report & Metrics |
| Rate Limit | 10 req / 10s | 10 req / 10s | 10 req / 10s |
Fleet Volume Overview#
GET /v1/analytics
Returns aggregated forwarding counts, active alias ratios, domain breakdowns, category statistics, and highest-volume aliases across your fleet.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YesQuery Parameters#
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
timeRange | string | Optional | "30d" | Evaluation window: "7d", "14d", "30d", "90d", "1y", or "all". |
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#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics?timeRange=30d" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "overview": { "totalAliases": 42, "activeAliases": 38, "inactiveAliases": 4, "totalEmailsForwarded": 1284, "avgEmailsPerAlias": 30.57, "aliasGrowthRate": 0.9, "aliasesCreatedThisPeriod": 6 }, "categories": [ { "category": "Customer Care", "count": 12, "emailsForwarded": 640, "activeCount": 12 }, { "category": "Billing", "count": 8, "emailsForwarded": 420, "activeCount": 8 } ], "domains": [ { "domain": "acme-corp.com", "count": 28, "emailsForwarded": 980, "activeCount": 26 }, { "domain": "af-mail.com", "count": 14, "emailsForwarded": 304, "activeCount": 12 } ], "topAliases": [ { "id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b", "local_part": "support", "full_alias": "support@acme-corp.com", "emails_forwarded": 312, "category": "Customer Care", "is_active": true, "last_email_at": "2026-09-04T12:00:00.000Z" } ], "timeRange": "30d", "fromDate": "2026-08-05T12:00:00.000Z", "toDate": "2026-09-04T12:00:00.000Z"}Response Fields#
| Field | Type | Description |
|---|---|---|
overview | object | Fleet-wide aggregate metrics. |
overview.totalAliases | integer | Count of all aliases created under the account. |
overview.activeAliases | integer | Count of aliases actively routing messages. |
overview.inactiveAliases | integer | Count of paused or trashed aliases. |
overview.totalEmailsForwarded | integer | Total inbound emails routed during this period. |
overview.avgEmailsPerAlias | number | Mean delivery volume per alias. |
overview.aliasesCreatedThisPeriod | integer | Count of newly provisioned aliases during window. |
categories | array | Volume breakdown grouped by category folder. |
domains | array | Volume breakdown grouped by hosting domain. |
topAliases | array | The highest-traffic aliases ranked by forwarded volume. |
Time-Series Dashboard Telemetry#
GET /v1/analytics/dashboard
Queries day-by-day delivery volumes (forwarded messages, rejected firewall blocks, anonymous replies), top sending domains, and hourly message distribution.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YesQuery Parameters#
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
timeRange | string | Optional | "7d" | Time series window: "24h", "7d", "30d", or "90d". |
aliasId | string | Optional | — | Scope time-series strictly to a single alias UUID. |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/dashboard?timeRange=7d" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "success": true, "tier": "advanced", "is_degraded": false, "timeRange": "7d", "startDate": "2026-08-28T12:00:00.000Z", "endDate": "2026-09-04T12:00:00.000Z", "stats": { "totalEmails": 842, "activeAliases": 38, "totalAliases": 42, "emailChange": "+12.4%", "aliasChange": 42 }, "aliasAnalytics": [ { "alias_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b", "alias": "support@acme-corp.com", "emails_received": 312, "category": "Customer Care", "is_active": true } ], "topSenders": [ { "sender": "notifications@github.com", "name": "GitHub", "count": 68, "percentage": 8.1 } ], "emailTrends": [ { "date": "2026-09-03", "forwarded": 142, "replied": 14, "sent": 0, "total": 156 } ], "bounceAnalytics": { "totalBounces": 2, "bounceRate": 0.2, "recentBounces": [] }}Response Fields#
| Field | Type | Description |
|---|---|---|
success | boolean | Verification confirmation flag. |
tier | string | Active analytics fidelity ("basic", "advanced", "detailed"). |
is_degraded | boolean | true when user is on Free tier without advanced telemetry. |
stats | object | Fleet-wide aggregate counters and trend deltas. |
topSenders | array | Most frequent external senders (Pro and Business tiers). |
emailTrends | array | Daily delivery volumes partitioned by forwarded, replied, and sent. |
bounceAnalytics | object | Historical bounce rates and error classifications. |
Per-Alias Deliverability Metrics#
GET /v1/analytics/alias/:aliasId
Inspects historical deliverability health, forwarding volumes, and reply counts for a specific alias. Requires Business tier (per_alias_analytics). Calling this endpoint on Free or Pro accounts returns { is_degraded: true, is_upgrade_required: true, required_plan: "business" }.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YesPath Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
aliasId | string | Yes | Unique alias UUID identifier. |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/alias/3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b?timeRange=30d" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "alias": { "id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b", "alias": "support@acme-corp.com", "category": "Customer Care", "is_active": true, "created_at": "2026-06-15T08:00:00.000Z" }, "stats": { "totalEmails": 312, "forwarded": 298, "replied": 14, "sent": 0, "bounced": 0, "emailChange": "+5.2%" }, "topSenders": [ { "sender": "notifications@github.com", "name": "GitHub", "count": 42 } ], "timeRange": "30d"}Response Fields#
| Field | Type | Description |
|---|---|---|
alias | object | Target alias descriptor. |
alias.id | string | Alias UUID. |
alias.alias | string | Complete email alias address. |
alias.is_active | boolean | Current routing status. |
stats | object | Performance and telemetry metrics. |
stats.totalEmails | integer | Count of routed emails. |
stats.forwarded | integer | Forwarded message count. |
stats.replied | integer | Outbound responses relayed. |
Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | VALIDATION_ERROR | "Invalid alias ID format" | Provided alias ID is not a valid UUID. |
404 | NOT_FOUND | "Alias not found" | Alias ID does not exist or access denied. |
Spam & Threat Telemetry#
GET /v1/analytics/spam-analysis/:aliasId
Returns an AI-generated natural language risk assessment, spam score metrics, and spy tracker blockage insights for an alias. Requires Pro or Business tier (analytics feature).
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YesPath Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
aliasId | string | Yes | Unique alias UUID identifier. |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/spam-analysis/3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "analysis": "This alias shows low overall spam volume with 2 suspicious marketing newsletters detected. The sending domain reputation remains healthy. Recommendation: keep monitoring normally.", "spamRate": 3, "spamEmailCount": 2, "totalEmailCount": 68, "topSpamDomains": [ "promo-blast.net" ], "generatedAt": "2026-09-04T12:00:00.000Z", "fromCache": true}Response Fields#
| Field | Type | Description |
|---|---|---|
analysis | string | Plain English AI risk summary and operational advice. |
spamRate | integer | Percentage of messages classified as spam (0 to 100). |
spamEmailCount | integer | Total spam messages intercepted. |
totalEmailCount | integer | Total messages evaluated during the 30-day inspection window. |
topSpamDomains | string[] | Most frequent sending domains generating spam scores. |
fromCache | boolean | Indicates whether report was served from daily cache. |
Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | VALIDATION_ERROR | "Invalid alias ID format" | Alias ID is malformed. |
403 | UPGRADE_REQUIRED | "Upgrade required" | AI spam analysis requires a Pro or Business subscription. |
404 | ALIAS_NOT_FOUND | "Alias not found" | Alias does not exist under your account. |
Tenant Privacy ROI Metrics#
GET /v1/analytics/roi
Retrieves privacy return-on-investment telemetry, calculating total spam blocked, tracking beacons neutralized, bytes of network transfer saved, and administrative hours preserved.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YescURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/roi" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "success": true, "data": { "total_spam_blocked": 1420, "total_trackers_neutralized": 384, "estimated_bytes_saved": 4892010, "spam_hours_saved": 12, "last_updated": "2026-09-04T12:00:00.000Z" }}Response Fields#
| Field | Type | Description |
|---|---|---|
success | boolean | Verification confirmation flag. |
data.total_spam_blocked | integer | Cumulative spam messages dropped before reaching your inbox. |
data.total_trackers_neutralized | integer | Spy tracking pixels stripped from inbound HTML bodies. |
data.estimated_bytes_saved | integer | Inbound network payload size prevented from reaching primary inbox. |
data.spam_hours_saved | integer | Estimated reading and triage time saved based on spam volume. |
data.last_updated | string | ISO 8601 timestamp of last metric computation. |
Vendor Exposure Graph#
GET /v1/analytics/vendor-graph
Maps relationships between external sender organizations and receiving aliases, detecting cross-service contact sharing and data broker dissemination formatted as a node-edge graph.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YescURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/vendor-graph" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "success": true, "data": { "nodes": [ { "id": "vendor-stripe", "type": "input", "data": { "label": "Stripe", "role": "intended_vendor" }, "position": { "x": 100, "y": 50 } }, { "id": "domain-adnetwork-xyz", "type": "output", "data": { "label": "adnetwork.xyz", "role": "leaked_domain" }, "position": { "x": 450, "y": 50 } } ], "edges": [ { "id": "edge-vendor-stripe-domain-adnetwork-xyz", "source": "vendor-stripe", "target": "domain-adnetwork-xyz", "animated": true, "label": "Leaked To", "data": { "detected_at": "2026-09-04T10:15:00.000Z" } } ], "total_leaks": 1 }}Response Fields#
| Field | Type | Description |
|---|---|---|
success | boolean | Request status confirmation. |
data.nodes | array | Graph vertices representing intended vendors and leaked recipient domains. |
data.edges | array | Graph relationships with animation status and detection timestamps. |
data.total_leaks | integer | Count of cross-vendor data exposure events detected. |
Inbound MTA Geographic Breakdown#
GET /v1/analytics/mta-origins
Returns incoming message volume distributions mapped by originating mail transfer agent geographical locations, latitude, longitude, and country codes.
Scope:
analytics:readRate Limit: 10 req / 10sIdempotent: YescURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/analytics/mta-origins" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "success": true, "data": [ { "country_code": "US", "latitude": 37.751, "longitude": -97.822, "total_emails": 842, "spam_blocked": 42, "legit_forwarded": 800 }, { "country_code": "DE", "latitude": 51.2993, "longitude": 9.491, "total_emails": 240, "spam_blocked": 12, "legit_forwarded": 228 } ]}Response Fields#
| Field | Type | Description |
|---|---|---|
success | boolean | Verification confirmation flag. |
data | array | Geographical MTA origin coordinate clusters. |
data[].country_code | string | Two-letter ISO country code. |
data[].latitude | number | Geographic latitude coordinate. |
data[].longitude | number | Geographic longitude coordinate. |
data[].total_emails | integer | Cumulative emails originating from this server cluster. |
data[].spam_blocked | integer | Messages dropped or bounced by the firewall from this location. |
data[].legit_forwarded | integer | Messages successfully forwarded to inboxes. |