Activity & Audit Logs API Reference

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

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/activity`	`GET`	`activity:read`	Retrieve recent activity feed and event stream.
`/v1/activity/logs`	`GET`	`activity:read`	Query paginated delivery logs with status and security filters.
`/v1/activity/logs/:id/xray`	`GET`	`activity:read`	Deep forensic header inspection and tracking pixel analysis.
`/v1/activity/logs/export`	`GET`	`activity:read`	Stream and download historical activity logs in JSON or CSV.
`/v1/activity/retention`	`GET`	`activity:read`	Inspect active retention windows and log expiration schedules.
`/v1/activity/anonymization`	`GET`	`activity:read`	View automated address masking and privacy policies.

Plan Quotas & Retention Limits#

Tier	Retention Period	Email X-Ray Forensics	Behavior Upon Expiration
Free	7 days	Disabled (Returns basic status)	Logs older than 7 days are permanently deleted via automated cron.
Pro	30 days	Enabled (Diagnostic metadata & headers)	Logs older than 30 days are permanently deleted via automated cron.
Business	90 days	Enabled (Diagnostic metadata & headers)	Full 90-day forensic window for compliance archival.

Get Activity Feed#

GET /v1/activity

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

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

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.
Tracker Stripping Telemetry: When tracker blocking is active, the engine increments tracker counts and records detected tracker domains without logging user interaction behavior.
Forensic X-Ray: Detailed email headers, originating sending MTA IP address, country code, and cryptographic signature validations (SPF, DKIM, DMARC) are available on demand for diagnostics through the X-Ray endpoint. Intermediate transit hops are stripped at the edge.
Tier Retention Windows:

Tier	Retention Window
Free	7 days
Pro	30 days
Business	90 days

Retrieve Activity Feed#

GET /v1/activity

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`limit`	`integer`	Optional	`10`	Maximum number of activity records to return (max `100`).

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/activity?limit=2" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "success": true,  "activities": [    {      "id": "email-4a8f9c1b-2d3e-4f5a-6b7c-8d9e0f1a2b3c",      "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": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",      "type": "sender_blocked",      "title": "Sender Blocked",      "description": "Added scamnetwork.xyz to blacklist",      "timestamp": "2026-09-04T12:20:00.000Z",      "metadata": {        "sender": "scamnetwork.xyz"      }    }  ],  "total": 2}

Response Fields#

Field	Type	Description
`success`	`boolean`	Indicates successful request.
`activities`	`array`	List of recent operational events.
`activities[].id`	`string`	Unique activity event identifier.
`activities[].type`	`string`	Event category (`"email_forwarded"`, `"sender_blocked"`, `"alias_created"`, `"bounce_detected"`, `"destination_verified"`).
`activities[].title`	`string`	Display label for feed rendering.
`activities[].description`	`string`	Narrative explanation of the event.
`activities[].timestamp`	`string`	ISO 8601 event timestamp.
`activities[].metadata`	`object`	Contextual entity references.
`total`	`integer`	Count of events returned in this page.

Query Delivery Logs#

GET /v1/activity/logs

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Results per page (max `100`).
`type`	`string`	Optional	—	Event type filter: `"forwarded"`, `"bounced"`, `"blocked"`, `"sent"`, or `"quick_send"`.
`aliasId`	`string`	Optional	—	Filter events to a specific alias UUID.
`search`	`string`	Optional	—	Substring search across sender, recipient, subject, or alias.
`startDate`	`string`	Optional	—	ISO 8601 start date timestamp (e.g. `2026-09-01T00:00:00Z`).
`endDate`	`string`	Optional	—	ISO 8601 end date timestamp.

cURL Example#

Terminal

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`)#

JSON

{  "success": true,  "logs": [    {      "id": "9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7",      "type": "forwarded",      "alias": "vendor-alerts@acme-corp.com",      "aliasId": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",      "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",      "isAnonymized": false,      "senderHash": null    }  ],  "counts": {    "total": 1420,    "forwarded": 1200,    "sent": 150,    "quickSend": 25,    "replied": 30,    "bounced": 5,    "blocked": 10,    "trackersBlocked": 42  },  "pagination": {    "page": 1,    "limit": 1,    "total": 1420,    "totalPages": 1420  },  "retention": {    "days": 30,    "isGracePeriod": false,    "graceEndsAt": null,    "planRetention": 30,    "logsCount": 1420  }}

Response Fields#

Field	Type	Description
`success`	`boolean`	Verification confirmation flag.
`logs`	`array`	List of delivery event log entries.
`logs[].id`	`string`	Unique delivery event UUID identifier.
`logs[].type`	`string`	Event category (`"forwarded"`, `"bounced"`, `"blocked"`, `"sent"`, `"quick_send"`).
`logs[].alias`	`string \| null`	Full email alias address receiving the message.
`logs[].aliasId`	`string \| null`	Receiving alias UUID identifier.
`logs[].sender`	`string`	Original sending party email address.
`logs[].senderName`	`string \| null`	Display name parsed from `From` header.
`logs[].recipient`	`string`	Destination inbox where message delivered.
`logs[].subject`	`string`	Message subject line.
`logs[].messageId`	`string`	RFC 5322 Message-ID header value.
`logs[].bounced`	`boolean`	`true` if transmission generated an SMTP bounce.
`logs[].timestamp`	`string`	ISO 8601 delivery timestamp.
`logs[].expiresAt`	`string`	ISO 8601 retention expiration timestamp.
`logs[].spamScore`	`number`	Heuristic spam rating score.
`logs[].trackersBlockedCount`	`integer`	Count of tracking pixels stripped from body.
`logs[].trackerDomains`	`string[]`	FQDNs of detected spy pixel sources.
`logs[].securityStatus`	`object`	Cryptographic authentication verdicts (`spf`, `dkim`, `dmarc`).
`logs[].ipAddress`	`string \| null`	Originating sending MTA IP address.
`logs[].countryCode`	`string \| null`	Two-letter ISO country code of sending server.
`counts`	`object`	Breakdown counters for forwarded, sent, quick send, bounced, and blocked messages.
`pagination`	`object`	Page index and total items metadata.
`retention`	`object`	Plan retention boundaries (`days`, `planRetention`, `isGracePeriod`, `logsCount`).

Inspect Forensic X-Ray#

GET /v1/activity/logs/:id/xray

Retrieves deep diagnostic telemetry for a specific delivery event, including cryptographic authentication checks (SPF, DKIM, DMARC), blocked spy pixels and tracking domains, originating MTA IP, and geographic country code. Intermediate transit hops are stripped at the edge to preserve infrastructure privacy.

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string`	Yes	Log event UUID identifier.

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/activity/logs/9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7/xray" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "success": true,  "telemetry": {    "id": "9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7",    "type": "forwarded",    "alias": "vendor-alerts@acme-corp.com",    "aliasId": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",    "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"  }}

Response Fields#

Field	Type	Description
`success`	`boolean`	Verification confirmation flag.
`telemetry`	`object`	Complete envelope forensic diagnostic object.
`telemetry.id`	`string`	Event identifier.
`telemetry.headers`	`object`	Key-value dictionary of sanitized transport headers.
`telemetry.securityStatus`	`object`	Cryptographic verdicts (`spf`, `dkim`, `dmarc`).
`telemetry.trackerDomains`	`string[]`	List of stripped beacon domain origins.
`telemetry.ipAddress`	`string \| null`	Originating sending server IP address.
`telemetry.countryCode`	`string \| null`	Two-letter ISO country code of sending server.

Error Responses#

Status Code	Code	Error Message	Reason
`404`	`NOT_FOUND`	`"Log entry not found"`	Delivery log record does not exist or has exceeded retention cutoff.

Export Audit Logs#

GET /v1/activity/logs/export

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

Scope: activity:readRate Limit: 10 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`format`	`string`	Optional	`"json"`	Desired output format: `"json"` or `"csv"`.

cURL Example#

Terminal

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

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

Inspect Log Retention#

GET /v1/activity/retention

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "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": {    "count": 18,    "oldestExpiry": "2026-09-07T12:00:00.000Z"  },  "planLimits": {    "free": 7,    "pro": 30,    "business": 90  }}

Response Fields#

Field	Type	Description
`retention`	`object`	Account retention policy attributes.
`retention.currentPlan`	`string`	Subscription tier dictating retention (`"free"`, `"pro"`, `"business"`).
`retention.effectiveDays`	`integer`	Active log retention window in days.
`retention.logsCount`	`integer`	Total log records currently stored.
`retention.oldestLog`	`string \| null`	Timestamp of oldest accessible log record.
`retention.newestLog`	`string \| null`	Timestamp of most recently recorded log.
`expiring.count`	`integer`	Count of log records expiring within 3 days.
`expiring.oldestExpiry`	`string \| null`	Expiration timestamp of earliest expiring log.
`planLimits`	`object`	Reference limits by tier (`free: 7`, `pro: 30`, `business: 90`).

Inspect Anonymization Settings#

GET /v1/activity/anonymization

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

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

Response Fields#

Field	Type	Description
`anonymization.enabled`	`boolean`	Whether automated anonymization is active.
`anonymization.afterDays`	`integer`	Age threshold after which records are anonymized.
`anonymization.totalAnonymized`	`integer`	Total historical records masked to date.

Frequently Asked Questions

The stream captures inbound email forwarding, rejected messages from blocked senders, delivery bounces, tracker strip events, and administrative security changes.

Retention windows depend on your account plan tier: Free is 7 days, Pro is 30 days, and Business is 90 days.

The X-Ray endpoint provides deep diagnostic metadata including SPF/DKIM/DMARC authentication verdicts, blocked tracker domains, originating MTA IP, country code, spam scores, and sanitized transport headers. Internal transit hops are stripped to preserve infrastructure and privacy integrity.

Yes. You can stream or download complete audit history in either structured JSON or RFC 4180 CSV format using GET /v1/activity/logs/export.

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

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/activity`	`GET`	`activity:read`	Retrieve recent activity feed and event stream.
`/v1/activity/logs`	`GET`	`activity:read`	Query paginated delivery logs with status and security filters.
`/v1/activity/logs/:id/xray`	`GET`	`activity:read`	Deep forensic header inspection and tracking pixel analysis.
`/v1/activity/logs/export`	`GET`	`activity:read`	Stream and download historical activity logs in JSON or CSV.
`/v1/activity/retention`	`GET`	`activity:read`	Inspect active retention windows and log expiration schedules.
`/v1/activity/anonymization`	`GET`	`activity:read`	View automated address masking and privacy policies.

Plan Quotas & Retention Limits#

Tier	Retention Period	Email X-Ray Forensics	Behavior Upon Expiration
Free	7 days	Disabled (Returns basic status)	Logs older than 7 days are permanently deleted via automated cron.
Pro	30 days	Enabled (Diagnostic metadata & headers)	Logs older than 30 days are permanently deleted via automated cron.
Business	90 days	Enabled (Diagnostic metadata & headers)	Full 90-day forensic window for compliance archival.

Get Activity Feed#

GET /v1/activity

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

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

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.
Tracker Stripping Telemetry: When tracker blocking is active, the engine increments tracker counts and records detected tracker domains without logging user interaction behavior.
Forensic X-Ray: Detailed email headers, originating sending MTA IP address, country code, and cryptographic signature validations (SPF, DKIM, DMARC) are available on demand for diagnostics through the X-Ray endpoint. Intermediate transit hops are stripped at the edge.
Tier Retention Windows:

Tier	Retention Window
Free	7 days
Pro	30 days
Business	90 days

Retrieve Activity Feed#

GET /v1/activity

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`limit`	`integer`	Optional	`10`	Maximum number of activity records to return (max `100`).

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/activity?limit=2" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "success": true,  "activities": [    {      "id": "email-4a8f9c1b-2d3e-4f5a-6b7c-8d9e0f1a2b3c",      "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": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",      "type": "sender_blocked",      "title": "Sender Blocked",      "description": "Added scamnetwork.xyz to blacklist",      "timestamp": "2026-09-04T12:20:00.000Z",      "metadata": {        "sender": "scamnetwork.xyz"      }    }  ],  "total": 2}

Response Fields#

Field	Type	Description
`success`	`boolean`	Indicates successful request.
`activities`	`array`	List of recent operational events.
`activities[].id`	`string`	Unique activity event identifier.
`activities[].type`	`string`	Event category (`"email_forwarded"`, `"sender_blocked"`, `"alias_created"`, `"bounce_detected"`, `"destination_verified"`).
`activities[].title`	`string`	Display label for feed rendering.
`activities[].description`	`string`	Narrative explanation of the event.
`activities[].timestamp`	`string`	ISO 8601 event timestamp.
`activities[].metadata`	`object`	Contextual entity references.
`total`	`integer`	Count of events returned in this page.

Query Delivery Logs#

GET /v1/activity/logs

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Results per page (max `100`).
`type`	`string`	Optional	—	Event type filter: `"forwarded"`, `"bounced"`, `"blocked"`, `"sent"`, or `"quick_send"`.
`aliasId`	`string`	Optional	—	Filter events to a specific alias UUID.
`search`	`string`	Optional	—	Substring search across sender, recipient, subject, or alias.
`startDate`	`string`	Optional	—	ISO 8601 start date timestamp (e.g. `2026-09-01T00:00:00Z`).
`endDate`	`string`	Optional	—	ISO 8601 end date timestamp.

cURL Example#

Terminal

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`)#

JSON

{  "success": true,  "logs": [    {      "id": "9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7",      "type": "forwarded",      "alias": "vendor-alerts@acme-corp.com",      "aliasId": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",      "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",      "isAnonymized": false,      "senderHash": null    }  ],  "counts": {    "total": 1420,    "forwarded": 1200,    "sent": 150,    "quickSend": 25,    "replied": 30,    "bounced": 5,    "blocked": 10,    "trackersBlocked": 42  },  "pagination": {    "page": 1,    "limit": 1,    "total": 1420,    "totalPages": 1420  },  "retention": {    "days": 30,    "isGracePeriod": false,    "graceEndsAt": null,    "planRetention": 30,    "logsCount": 1420  }}

Response Fields#

Field	Type	Description
`success`	`boolean`	Verification confirmation flag.
`logs`	`array`	List of delivery event log entries.
`logs[].id`	`string`	Unique delivery event UUID identifier.
`logs[].type`	`string`	Event category (`"forwarded"`, `"bounced"`, `"blocked"`, `"sent"`, `"quick_send"`).
`logs[].alias`	`string \| null`	Full email alias address receiving the message.
`logs[].aliasId`	`string \| null`	Receiving alias UUID identifier.
`logs[].sender`	`string`	Original sending party email address.
`logs[].senderName`	`string \| null`	Display name parsed from `From` header.
`logs[].recipient`	`string`	Destination inbox where message delivered.
`logs[].subject`	`string`	Message subject line.
`logs[].messageId`	`string`	RFC 5322 Message-ID header value.
`logs[].bounced`	`boolean`	`true` if transmission generated an SMTP bounce.
`logs[].timestamp`	`string`	ISO 8601 delivery timestamp.
`logs[].expiresAt`	`string`	ISO 8601 retention expiration timestamp.
`logs[].spamScore`	`number`	Heuristic spam rating score.
`logs[].trackersBlockedCount`	`integer`	Count of tracking pixels stripped from body.
`logs[].trackerDomains`	`string[]`	FQDNs of detected spy pixel sources.
`logs[].securityStatus`	`object`	Cryptographic authentication verdicts (`spf`, `dkim`, `dmarc`).
`logs[].ipAddress`	`string \| null`	Originating sending MTA IP address.
`logs[].countryCode`	`string \| null`	Two-letter ISO country code of sending server.
`counts`	`object`	Breakdown counters for forwarded, sent, quick send, bounced, and blocked messages.
`pagination`	`object`	Page index and total items metadata.
`retention`	`object`	Plan retention boundaries (`days`, `planRetention`, `isGracePeriod`, `logsCount`).

Inspect Forensic X-Ray#

GET /v1/activity/logs/:id/xray

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string`	Yes	Log event UUID identifier.

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/activity/logs/9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7/xray" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "success": true,  "telemetry": {    "id": "9a8b7c6d-5e4f-3a2b-1c0d-e2f3a4b5c6d7",    "type": "forwarded",    "alias": "vendor-alerts@acme-corp.com",    "aliasId": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",    "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"  }}

Response Fields#

Field	Type	Description
`success`	`boolean`	Verification confirmation flag.
`telemetry`	`object`	Complete envelope forensic diagnostic object.
`telemetry.id`	`string`	Event identifier.
`telemetry.headers`	`object`	Key-value dictionary of sanitized transport headers.
`telemetry.securityStatus`	`object`	Cryptographic verdicts (`spf`, `dkim`, `dmarc`).
`telemetry.trackerDomains`	`string[]`	List of stripped beacon domain origins.
`telemetry.ipAddress`	`string \| null`	Originating sending server IP address.
`telemetry.countryCode`	`string \| null`	Two-letter ISO country code of sending server.

Error Responses#

Status Code	Code	Error Message	Reason
`404`	`NOT_FOUND`	`"Log entry not found"`	Delivery log record does not exist or has exceeded retention cutoff.

Export Audit Logs#

GET /v1/activity/logs/export

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

Scope: activity:readRate Limit: 10 req/minIdempotent: Yes

Query Parameters#

Parameter	Type	Required	Default	Description
`format`	`string`	Optional	`"json"`	Desired output format: `"json"` or `"csv"`.

cURL Example#

Terminal

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

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

Inspect Log Retention#

GET /v1/activity/retention

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "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": {    "count": 18,    "oldestExpiry": "2026-09-07T12:00:00.000Z"  },  "planLimits": {    "free": 7,    "pro": 30,    "business": 90  }}

Response Fields#

Field	Type	Description
`retention`	`object`	Account retention policy attributes.
`retention.currentPlan`	`string`	Subscription tier dictating retention (`"free"`, `"pro"`, `"business"`).
`retention.effectiveDays`	`integer`	Active log retention window in days.
`retention.logsCount`	`integer`	Total log records currently stored.
`retention.oldestLog`	`string \| null`	Timestamp of oldest accessible log record.
`retention.newestLog`	`string \| null`	Timestamp of most recently recorded log.
`expiring.count`	`integer`	Count of log records expiring within 3 days.
`expiring.oldestExpiry`	`string \| null`	Expiration timestamp of earliest expiring log.
`planLimits`	`object`	Reference limits by tier (`free: 7`, `pro: 30`, `business: 90`).

Inspect Anonymization Settings#

GET /v1/activity/anonymization

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

Scope: activity:readRate Limit: 60 req/minIdempotent: Yes

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

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

Response Fields#

Field	Type	Description
`anonymization.enabled`	`boolean`	Whether automated anonymization is active.
`anonymization.afterDays`	`integer`	Age threshold after which records are anonymized.
`anonymization.totalAnonymized`	`integer`	Total historical records masked to date.

Quick Reference#

Plan Quotas & Retention Limits#

Get Activity Feed#

Retrieve Activity Feed#

Query Parameters#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Query Delivery Logs#

Query Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Inspect Forensic X-Ray#

Path Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Error Responses#

Export Audit Logs#

Query Parameters#

cURL Example#

Response Headers (200 OK)#

Inspect Log Retention#

cURL Example#

Response (200 OK)#

Response Fields#

Inspect Anonymization Settings#

cURL Example#

Response (200 OK)#

Response Fields#

Frequently Asked Questions

What events are recorded in the activity log stream?

How long are activity and delivery logs retained?

What forensic data does the X-Ray endpoint provide?

Can I export audit logs for external SIEM integration?

Was this article helpful?

Related in Developer API

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Destinations API

Still need help?

Quick Reference#

Plan Quotas & Retention Limits#

Get Activity Feed#

Retrieve Activity Feed#

Query Parameters#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Query Delivery Logs#

Query Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Inspect Forensic X-Ray#

Path Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Error Responses#

Export Audit Logs#

Query Parameters#

cURL Example#

Response Headers (200 OK)#

Inspect Log Retention#

cURL Example#

Response (200 OK)#

Response Fields#

Inspect Anonymization Settings#

cURL Example#

Response (200 OK)#

Response Fields#

Frequently Asked Questions

What events are recorded in the activity log stream?

How long are activity and delivery logs retained?

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response Headers (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response Headers (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#