Developer API Overview

Programmatically provision email aliases, manage custom domain routing tables, and dispatch outbound messages through the AliasFleet REST API.

Quickstart#

Make your first authenticated request to verify your API key and inspect your account identity:

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

{  "user_id": "d3b07384-d113-4674-bc50-a88981298418",  "email": "developer@company.com",  "full_name": "Alex Mercer",  "role": "user",  "tier": "business",  "created_at": "2026-09-04T12:00:00.000Z",  "auth_type": "api_key",  "scopes": [    "aliases:read",    "aliases:write",    "domains:read",    "destinations:read",    "analytics:read",    "categories:read"  ]}

Core Conventions#

Authentication#

Generate API keys in your dashboard under Settings → Developer API. All developer keys carry an afp_ prefix followed by 48 hexadecimal characters (52 characters total):

Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e

Alternatively, pass the key via the x-api-key header:

x-api-key: afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e

Entity Identifiers#

All database entities across the AliasFleet infrastructure (aliases, destinations, custom domains, rules, webhooks, categories, audit logs) use standard RFC 4122 UUIDs (e.g. 9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c).

The only prefixed strings in the API ecosystem are:

Permission Scopes#

API keys enforce fine-grained resource:action permission scopes. You can tailor each key with the exact permissions required by your application:

Platform Tiers & Feature Entitlements#

AliasFleet provisions features and quotas across three clear tiers: Free, Pro, and Business.

Rate Limits & Response Headers#

Rate limits are evaluated per client or API key using sliding-window limiters:

Telemetry Headers#

Every API response emits telemetry headers:

X-Response-Time: 12.4msServer-Timing: total;dur=12.4

When an idempotent quick-send request is replayed within its 24-hour cache window, the response includes:

X-Idempotent-Replay: true

Rate Limit Exceeded (429)#

When a rate limit threshold is crossed, the API returns 429 Too Many Requests with a standard Retry-After header:

HTTP/1.1 429 Too Many RequestsRetry-After: 12Content-Type: application/json{  "error": "Too Many Requests",  "code": "RATE_LIMIT_EXCEEDED"}

Outbound Email Idempotency#

To prevent duplicate email dispatches during network hiccups, POST /v1/quick-send supports an Idempotency-Key header:

Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

• Retention Window: Cached for 24 hours.
• Replay Behavior: If a connection drops and your client retries with the same Idempotency-Key, the server returns the cached 200 OK response with header X-Idempotent-Replay: true without sending a duplicate email.

Pagination#

Endpoints returning lists support limit and offset pagination:

Collection responses return item arrays alongside total counts:

{  "aliases": [...],  "total": 42}

Error Handling#

All error responses adhere to standard JSON error envelopes:

{  "error": "Alias limit reached. Upgrade your subscription plan to create more aliases.",  "code": "LIMIT_REACHED"}

Common HTTP Status Codes#

API Resource Directory#

• Identity API (/v1/me) - Token introspection, active scopes, and account identity.
• Aliases API (/v1/aliases) - Core alias lifecycle (create, query, update, trash, purge, and retention).
• Alias Destinations & Batch API - Multi-destination forwarding fanout, atomic batch operations, and privacy settings.
• Domains API (/v1/domains) - System shared domains, custom domain DNS verification, subdomains, and DKIM keys.
• Destinations API (/v1/destinations) - Forwarding inboxes, OTP verification, alias usage, and smart reassignment.
• Quick-Send API (/v1/quick-send) - Outbound anonymous email dispatch with presigned attachment handling.
• Sender Rules & Firewall API (/v1/sender-rules) - Inbound allowlist and denylist firewall rules, pattern matching, and threat protection.
• Activity API (/v1/activity) - Forwarding event logs, Email X-Ray delivery forensics, and GDPR deletion.
• Fleet Analytics API (/v1/analytics) - Time-series forwarding trends, spam threat telemetry, and tracker blocking stats.
• Rules API (/v1/rules) - Priority-ordered conditional routing rules, header evaluations, and automated actions.
• Security & Threat Intelligence API (/v1/security) - Anomalous traffic volume spikes, threat alerts, and human-in-the-loop incident dismissal.
• Webhooks API (/v1/webhooks) - Real-time event notifications, HMAC-SHA256 signature verification, secret rotation, and delivery logs.
• Categories & Tags API (/v1/categories) - Organize aliases into folders, apply color tokens, and manage category hierarchies.
• User Profile & Account API (/v1/user) - Account profile, active subscription plan, monthly bandwidth usage, and global forwarding preferences.