Provision email aliases, inspect forwarding telemetry, update delivery rules, configure retention, and manage address lifecycles.
Quick Reference#
| Endpoint | Method | Required Scope | Description |
|---|---|---|---|
/v1/aliases | GET | aliases:read | List active, paused, or trashed aliases with limit/offset pagination. |
/v1/aliases | POST | aliases:write | Create a new alias with custom or randomized local parts. |
/v1/aliases/check | GET | aliases:read | Check whether a specific alias address is available for registration. |
/v1/aliases/stats | GET | aliases:read | Retrieve volume metrics and monthly forward/block trends. |
/v1/aliases/:id | GET | aliases:read | Retrieve detailed configuration and metrics for a single alias. |
/v1/aliases/:id | PATCH | aliases:write | Update alias state, description, category, or destination routing. |
/v1/aliases/:id | DELETE | aliases:write | Move an alias to trash (soft-delete). |
/v1/aliases/:id/purge | DELETE | aliases:write | Permanently delete an alias from the database. |
/v1/aliases/:id/restore | POST | aliases:write | Restore a trashed alias back to active routing. |
/v1/aliases/:id/retention | GET | aliases:read | Retrieve per-alias log retention settings and plan maximums. |
/v1/aliases/:id/retention | PATCH | aliases:write | Update per-alias log retention days within your plan limits. |
List Aliases#
GET /v1/aliases
Retrieves a paginated list of email aliases for your account. Results can be filtered by operational status, domain, site domain, or search query.
Scope:
aliases:readRate Limit: 60 req/minIdempotent: YesQuery Parameters#
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status | string | Optional | "active" | Filter by status: "active", "paused", "trash", or "all". |
limit | integer | Optional | 10 | Maximum items to return (min 1, max 100). |
offset | integer | Optional | 0 | Number of items to skip for pagination. |
domain | string | Optional | — | Filter aliases under a specific domain name (e.g. example.com). |
site_domain | string | Optional | — | Filter aliases created for a specific website domain. |
search | string | Optional | — | Case-insensitive search across local_part, description, or domain. |
sort | string | Optional | "created_at:desc" | Sort ordering (e.g. created_at:desc, created_at:asc). |
include_count | boolean | Optional | false | When true, includes total exact count in response. |
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/aliases?status=active&limit=2" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "aliases": [ { "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "address": "billing-support@company.com", "local_part": "billing-support", "domain": "company.com", "domain_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "description": "Billing Inquiries", "is_active": true, "status": "active", "emails_forwarded": 142, "emails_blocked": 3, "emails_replied": 12, "emails_sent": 4, "forward_to_email": "finance@company.com", "category": "Finance", "expires_at": null, "created_at": "2026-09-04T12:00:00.000Z" } ], "total": 42}Create Alias#
POST /v1/aliases
Provisions a new email alias. If local_part is omitted, the API automatically generates a random 8-character alphanumeric string.
Scope:
aliases:writeRate Limit: 10 req/minIdempotent: NoRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
domain_id | string | Yes | RFC 4122 UUID of the hosting domain (domains.id). |
local_part | string | Optional | Desired local part prefix. Max 64 chars. Generates random 8-char string if omitted. |
forward_to_email | string | Optional | Primary destination address. Must be verified on your account. |
destinations | array | Optional | Array of destination emails or IDs for multi-destination forwarding fanout. |
category_id | string | Optional | UUID of the category folder to assign this alias to. |
category | string | Optional | Category name string alternative to category_id. |
description | string | Optional | Descriptive note or label for organizing the alias. |
site_domain | string | Optional | Associated target website (e.g. github.com). |
alias_ttl_days | integer | Optional | Time-to-live in days (1–365). Custom domains only. |
expires_at | string | Optional | ISO 8601 UTC expiration timestamp. Custom domains only. |
Important
Custom Domain Requirement for Expiring Aliases: The alias_ttl_days and expires_at parameters are strictly restricted to verified custom domains (domain.type === 'custom'). Attempting to set an expiration on shared platform domains returns HTTP 400 CUSTOM_DOMAIN_REQUIRED to preserve shared domain reputation.
cURL Example#
Terminal
curl -X POST "https://api.aliasfleet.com/v1/aliases" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Content-Type: application/json" \ -d '{ "local_part": "newsletter", "domain_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "description": "Weekly Tech Digest", "forward_to_email": "inbox@company.com" }'Response (201 Created)#
JSON
{ "success": true, "alias": { "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "local_part": "newsletter", "domain": "company.com", "full_address": "newsletter@company.com", "description": "Weekly Tech Digest", "active": true, "site_domain": null, "created_at": "2026-09-04T12:00:00.000Z", "emails_forwarded": 0, "emails_blocked": 0, "category": null, "expires_at": null }}Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
400 | VALIDATION_ERROR | "domain_id is required" | Request body is missing the required domain_id parameter. |
400 | RESERVED_PREFIX | "Prefix is reserved by system" | System prefixes (admin, support, billing) are blocked on shared domains. |
400 | CUSTOM_DOMAIN_REQUIRED | "Expiring temporary aliases (alias_ttl_days / expires_at) are strictly restricted to your verified custom domains to protect shared reputation." | Attempted to set a TTL or expiration date on a shared platform domain. |
403 | LIMIT_REACHED | "Alias limit reached. Upgrade your subscription plan to create more aliases." | Account has reached the maximum alias quota allowed under its subscription tier. |
403 | PAUSED_LOCK | "Your subscription is paused. New resource creation is locked." | Account subscription is paused. Resume subscription to create aliases. |
403 | DOMAIN_OWNERSHIP_ERROR | "You do not own this domain" | The specified custom domain belongs to another user. |
404 | DOMAIN_NOT_FOUND | "Domain not found" | The specified domain_id does not exist or is inactive. |
409 | ALIAS_EXISTS | "Alias address already taken" | The specified local_part and domain combination already exists. |
429 | RATE_LIMIT_EXCEEDED | "Slow down, you are too fast. Please wait a moment before creating more aliases." | Exceeded the 10 creations / minute threshold. |
Check Alias Availability#
GET /v1/aliases/check
Pre-flight verification endpoint to confirm whether a desired alias local part is available on a specific domain before attempting creation.
Scope:
aliases:readRate Limit: 30 req/minIdempotent: YesQuery Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
local_part | string | Yes | Local part prefix to test (e.g. support). |
domain_id | string | Yes | UUID of the domain to test against. |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/aliases/check?local_part=newsletter&domain_id=1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "available": true, "address": "newsletter@company.com"}If the alias is already registered, the endpoint returns:
JSON
{ "available": false, "address": "newsletter@company.com", "reason": "Alias is already registered", "suggestion": "newsletter-294@company.com"}Get Alias Statistics#
GET /v1/aliases/stats
Retrieves volume metrics and monthly forwarding and block trends across all aliases.
Scope:
aliases:readRate Limit: 60 req/minIdempotent: YescURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/aliases/stats" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "totalAliases": 42, "totalForwarded": 1284, "totalBlocked": 315, "newThisMonth": 6, "newLastMonth": 4, "totalTrend": 50, "forwardedThisMonth": 210, "forwardedLastMonth": 180, "forwardedTrend": 16.7, "blockedThisMonth": 45, "blockedLastMonth": 30, "blockedTrend": 50}Get Alias by ID#
GET /v1/aliases/:id
Retrieves the complete configuration, forwarding statistics, and attached recipients for a single alias.
Scope:
aliases:readRate Limit: 60 req/minIdempotent: YesPath Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | UUID of the alias (aliases.id). |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/aliases/9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "alias": { "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "local_part": "stripe-billing", "domain": "company.com", "full_address": "stripe-billing@company.com", "description": "Billing receipts", "is_active": true, "status": "active", "forward_to_email": "finance@company.com", "emails_forwarded": 38, "emails_blocked": 1, "emails_replied": 0, "emails_sent": 0, "created_at": "2026-07-01T12:00:00.000Z", "destinations": [ { "id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a", "email": "finance@company.com", "is_verified": true } ] }}Update Alias#
PATCH /v1/aliases/:id
Modifies operational status, description, category folder, or primary forwarding destination for an alias.
Scope:
aliases:writeRate Limit: 60 req/minIdempotent: YesRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
is_active | boolean | Optional | Set false to pause forwarding, true to resume. |
description | string | null | Optional | Informative note for organizing the alias. Max 500 chars. |
category_id | string | null | Optional | UUID of the category folder. Set null to unassign. |
forward_to_email | string | Optional | Updated primary destination inbox. Must be verified. |
cURL Example#
Terminal
curl -X PATCH "https://api.aliasfleet.com/v1/aliases/9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Content-Type: application/json" \ -d '{ "is_active": false, "description": "Paused Billing Alias" }'Response (200 OK)#
JSON
{ "alias": { "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "local_part": "stripe-billing", "domain": "company.com", "full_address": "stripe-billing@company.com", "is_active": false, "status": "paused", "description": "Paused Billing Alias" }}Move Alias to Trash (Soft-Delete)#
DELETE /v1/aliases/:id
Moves an alias to the trash folder. Incoming emails sent to trashed aliases are dropped immediately at the mail edge, but the address remains reserved to your account and can be restored at any time.
Scope:
aliases:writeRate Limit: 60 req/minIdempotent: YescURL Example#
Terminal
curl -X DELETE "https://api.aliasfleet.com/v1/aliases/9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"Response (200 OK)#
JSON
{ "message": "Alias moved to trash successfully", "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c"}Purge Alias Permanently#
DELETE /v1/aliases/:id/purge
Permanently deletes an alias and removes all associated routing configurations, logs, and recipients from the database.
Scope:
aliases:writeRate Limit: 60 req/minIdempotent: YesCaution
Irreversible Action: Purging an alias permanently deletes its routing configuration and history. Once purged, the operation cannot be undone.
cURL Example#
Terminal
curl -X DELETE "https://api.aliasfleet.com/v1/aliases/9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c/purge" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"Response (200 OK)#
JSON
{ "message": "Alias permanently deleted", "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c"}Restore Trashed Alias#
POST /v1/aliases/:id/restore
Restores an alias from trash back to active status, re-enabling email forwarding and telemetry tracking.
Scope:
aliases:writeRate Limit: 60 req/minIdempotent: YesResponse (200 OK)#
JSON
{ "success": true, "message": "Alias restored successfully", "alias": { "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "is_active": true, "status": "active", "deleted_at": null }}Get Alias Retention Settings#
GET /v1/aliases/:id/retention
Retrieves per-alias log retention settings alongside the user's plan maximum retention limit.
Scope:
aliases:readRate Limit: 60 req/minResponse (200 OK)#
JSON
{ "success": true, "retention": { "aliasId": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c", "customRetentionDays": 14, "effectiveRetentionDays": 14, "planMaxDays": 90 }}Update Alias Retention Settings#
PATCH /v1/aliases/:id/retention
Configures custom log retention days for a specific alias. The retention days value must be at least 1 and cannot exceed your plan's maximum retention allowance (7 days on Free, 30 days on Pro, 90 days on Business).
Scope:
aliases:writeRate Limit: 60 req/minRequest Body Schema#
| Field | Type | Required | Description |
|---|---|---|---|
retention_days | integer | null | Yes | Retention days (between 1 and plan max). Pass null to inherit account default. |
Response (200 OK)#
JSON
{ "success": true}