Aliases API

Provision private email aliases, inspect forwarding telemetry, update delivery rules, and manage address lifecycles.

Quick Reference

GET /v1/aliases — List Aliases

Scope: aliases:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves a paginated list of email aliases for your workspace. Results can be filtered by operational status, category folder, or domain.

Query Parameters

Example Request

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)

{
  "aliases": [
    {
      "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
      "address": "billing-support@company.com",
      "local_part": "billing-support",
      "domain": "company.com",
      "domain_id": "dom_bXm9kLpQr2nVwYz3",
      "label": "Billing Inquiries",
      "note": "Shared alias for customer invoices",
      "is_active": true,
      "status": "active",
      "emails_forwarded": 142,
      "emails_blocked": 3,
      "emails_replied": 12,
      "emails_sent": 0,
      "forward_to_email": "ops@company.com",
      "category_id": "acat_cYn0mMqRs3oWxZa4",
      "created_at": "2026-07-01T12:00:00.000Z",
      "updated_at": "2026-08-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 48,
    "total_pages": 24,
    "has_more": true
  }
}

Errors

POST /v1/aliases — Create Alias

Scope: aliases:write · Rate Limit: 10/min · Idempotent: Yes (with Idempotency-Key)

Provisions a new email alias. If local_part is omitted, the API generates a cryptographically random 8-character string. If destinations or forward_to_email is omitted, the alias routes to your account's default destination.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/aliases" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: e6b48325-1e9a-4c26-8ff5-0e31846b9a21" \
  -d '{
    "local_part": "stripe-billing",
    "domain_id": "dom_bXm9kLpQr2nVwYz3",
    "label": "Stripe Invoices",
    "forward_to_email": "finance@company.com"
  }'

Response (201 Created)

{
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "address": "stripe-billing@company.com",
    "local_part": "stripe-billing",
    "domain": "company.com",
    "domain_id": "dom_bXm9kLpQr2nVwYz3",
    "label": "Stripe Invoices",
    "note": null,
    "is_active": true,
    "status": "active",
    "forward_to_email": "finance@company.com",
    "emails_forwarded": 0,
    "emails_blocked": 0,
    "emails_replied": 0,
    "emails_sent": 0,
    "created_at": "2026-09-04T12:00:00.000Z"
  }
}

Errors

GET /v1/aliases/check-availability — Check Availability

Scope: aliases:read · Rate Limit: 60/min · Idempotent: Yes

Pre-flight endpoint to verify whether a desired alias address is available before attempting creation.

Query Parameters

Example Request

curl -X GET "https://api.aliasfleet.com/v1/aliases/check-availability?local_part=newsletter&domain=company.com" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (200 OK)

{
  "available": true,
  "address": "newsletter@company.com",
  "local_part": "newsletter",
  "domain": "company.com"
}

GET /v1/aliases/stats — Aggregate Statistics

Scope: aliases:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves summary totals of your workspace aliases partitioned by operational status.

Example Request

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

Response (200 OK)

{
  "total": 52,
  "active": 45,
  "paused": 4,
  "trash": 3
}

GET /v1/aliases/:id — Retrieve Alias

Scope: aliases:read · Rate Limit: 60/min · Idempotent: Yes

Retrieves the full record and forwarding telemetry for a specific alias.

Path Parameters

Example Request

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

Response (200 OK)

{
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "address": "stripe-billing@company.com",
    "local_part": "stripe-billing",
    "domain": "company.com",
    "domain_id": "dom_bXm9kLpQr2nVwYz3",
    "label": "Stripe Invoices",
    "note": "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"
  }
}

Errors

PATCH /v1/aliases/:id — Update Alias

Scope: aliases:write · Rate Limit: 60/min · Idempotent: Yes

Modifies metadata, destination routing, or delivery status for an alias.

Request Body Parameters

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "label": "Paused Billing Alias"
  }'

Response (200 OK)

{
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "address": "stripe-billing@company.com",
    "is_active": false,
    "status": "paused",
    "label": "Paused Billing Alias"
  }
}

Errors

DELETE /v1/aliases/:id — Delete or Trash Alias

Scope: aliases:write · Rate Limit: 60/min · Idempotent: Yes

Moves an alias to trash (soft-delete) or purges it permanently. Trashed aliases drop incoming emails immediately but can be restored.

Query Parameters

Example: Move to Trash (Soft-Delete)

curl -X DELETE "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

{
  "success": true,
  "message": "Alias moved to trash",
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "status": "trash",
    "deleted_at": "2026-09-04T12:30:00.000Z"
  }
}

Example: Permanent Purge

curl -X DELETE "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN?permanent=true" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

{
  "success": true,
  "message": "Alias permanently deleted"
}

POST /v1/aliases/:id/restore — Restore Trashed Alias

Scope: aliases:write · Rate Limit: 60/min · Idempotent: Yes

Restores an alias from trash back to active status, re-enabling email forwarding and metrics tracking.

Example Request

curl -X POST "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN/restore" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (200 OK)

{
  "success": true,
  "message": "Alias restored successfully",
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "is_active": true,
    "status": "active",
    "deleted_at": null
  }
}

Errors