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 workspace capabilities:

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

{
  "user": {
    "id": "usr_9f83a2c1b4d5e6f7",
    "email": "developer@company.com",
    "plan": "pro"
  },
  "auth": {
    "key_id": "key_1a2b3c4d5e6f7g8h",
    "name": "Production Worker",
    "scopes": ["*"]
  },
  "quotas": {
    "aliases_used": 14,
    "aliases_limit": 500,
    "domains_used": 2,
    "domains_limit": 10
  }
}

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

AliasFleet uses type-prefixed identifiers across all resources. Prefixes allow you to identify any entity at a glance:

Permission Scopes

Keys can be restricted to specific functional scopes or granted full access (*):

Rate Limits & Headers

Rate limits are evaluated per API key:

Every response includes rate limit telemetry headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1725450000

When a rate limit is exceeded, the server returns 429 Too Many Requests with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Rate limit exceeded. Please back off and retry.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Idempotency

All mutation endpoints (POST, PATCH, DELETE) accept an optional Idempotency-Key header:

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

• Retention Window: Keys are retained for 24 hours.
• Retry Behavior: If network disruption interrupts a request, repeating the request with the identical key returns the cached response without re-executing the operation or double-allocating quota.
• Payload Mismatch: Submitting the same key with a different request payload returns 422 Unprocessable Entity.

Pagination

Endpoints returning collections support cursor and offset pagination:

Pagination metadata is included in the response body:

{
  "aliases": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_more": true
  }
}

Error Handling

All error responses adhere to RFC 9457 Problem Details format:

{
  "error": "Cannot delete domain with active aliases. Please reassign or delete them first.",
  "code": "ALIASES_EXIST",
  "status": 400
}

Common HTTP Status Codes

API Resource Directory

• Identity API (/v1/me) — Token introspection, active scopes, and workspace capabilities.
• Aliases API (/v1/aliases) — Core alias lifecycle (create, query, update, trash, and restore).
• Alias Destinations & Batch API — Multi-destination forwarding fanout, atomic batch operations, and privacy settings.
• Domains API (/v1/domains) — Shared platform domains, custom domain DNS verification, and safety locks.
• Destinations API (/v1/destinations) — Inboxes, OTP verification, sender identities, and fallback routing.
• Quick-Send API (/v1/quick-send) — Outbound anonymous email dispatch with attachment handling.
• Sender Rules & Firewall API (/v1/sender-rules) — Inbound allowlist and denylist firewall rules, pattern matching, and edge threat protection.
• Activity API (/v1/activity) — Audit forwarding events, delivery logs, and security blocks.
• Fleet Analytics API (/v1/analytics) — Time-series forwarding trends, spam threat telemetry, tracker blockage, and vendor graphs.
• Rules Engine 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, cryptographic HMAC-SHA256 signature verification, and delivery audit logs.