Alias Destinations & Batch Operations API

Attach verified destinations for multi-destination forwarding fanout, execute bulk operations across up to 100 aliases, and fine-tune per-alias privacy settings.

Quick Reference

GET /v1/aliases/:id/recipients — List Attached Destinations

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

Returns all verified destinations attached to an alias. Incoming emails to this alias are duplicated and forwarded to every listed destination.

Path Parameters

Example Request

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

Response (200 OK)

{
  "recipients": [
    {
      "id": "rcpt_x9Kl2mNopQrStUv1",
      "created_at": "2026-08-24T06:30:00.000Z",
      "destinations": {
        "id": "dest_adn6UTmkzn6OWpGq",
        "email": "primary-ops@company.com",
        "is_verified": true,
        "can_reply": true,
        "can_send": true
      }
    },
    {
      "id": "rcpt_mNoP3qRsTuVwXyZ2",
      "created_at": "2026-08-25T14:15:00.000Z",
      "destinations": {
        "id": "dest_rNZO2x0c8GPOJxiR",
        "email": "audit-archive@company.com",
        "is_verified": true,
        "can_reply": false,
        "can_send": false
      }
    }
  ]
}

Errors

POST /v1/aliases/:id/recipients — Attach Destination to Alias

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

Attaches a verified destination inbox to an alias for multi-destination forwarding fanout.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN/recipients" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_rNZO2x0c8GPOJxiR"
  }'

Response (201 Created)

{
  "recipient": {
    "id": "rcpt_mNoP3qRsTuVwXyZ2",
    "created_at": "2026-08-25T14:15:00.000Z",
    "destinations": {
      "id": "dest_rNZO2x0c8GPOJxiR",
      "email": "audit-archive@company.com",
      "is_verified": true,
      "can_reply": false,
      "can_send": false
    }
  }
}

Errors

DELETE /v1/aliases/:id/recipients/:recipientId — Detach Destination from Alias

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

Detaches a destination from an alias. Forwarded messages will no longer deliver to this destination inbox.

Path Parameters

Example Request

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

Response (200 OK)

{
  "success": true
}

Errors

POST /v1/aliases/batch-toggle — Bulk Pause or Activate

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

Updates forwarding status (active: true or false) across up to 100 aliases in a single atomic request.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/aliases/batch-toggle" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "al_6c5J5LMXd5E3Yq1Wx1zN",
      "al_WTSGM57cIGy4oLUMoPQ2"
    ],
    "active": false
  }'

Response (200 OK)

{
  "success": true,
  "updated_count": 2,
  "active": false
}

Errors

POST /v1/aliases/batch-delete — Bulk Move to Trash

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

Soft-deletes up to 100 aliases in a single operation. Trashed aliases drop incoming emails immediately and can be restored.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/aliases/batch-delete" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "al_6c5J5LMXd5E3Yq1Wx1zN",
      "al_WTSGM57cIGy4oLUMoPQ2"
    ]
  }'

Response (200 OK)

{
  "success": true,
  "deleted_count": 2
}

GET /v1/aliases/:id/settings — Inspect Alias Settings

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

Retrieves privacy transformations, tracking protection, custom sender names, and safety banner configurations for a specific alias.

Path Parameters

Example Request

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

Response (200 OK)

{
  "alias": {
    "id": "al_6c5J5LMXd5E3Yq1Wx1zN",
    "local_part": "billing-support",
    "aliasName": "billing-support",
    "settings": {
      "fromName": "Acme Billing",
      "subject": "[Invoice] ",
      "useFromName": true,
      "useSubject": true,
      "bannerEnabled": true,
      "bannerText": "Received via AliasFleet billing alias.",
      "bannerLocation": "top",
      "bannerShowSender": true,
      "bannerShowDeactivateLink": false,
      "neutralizeTrackers": true,
      "rawForwarding": false,
      "fromAddressFormat": "name_and_email"
    }
  }
}

PATCH /v1/aliases/:id/settings — Update Alias Settings

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

Updates per-alias delivery modifications and privacy protections. All fields are optional.

Request Body Parameters

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/aliases/al_6c5J5LMXd5E3Yq1Wx1zN/settings" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "useFromName": true,
    "fromName": "Acme Billing Support",
    "neutralizeTrackers": true,
    "rawForwarding": false
  }'

Response (200 OK)

{
  "success": true
}

Errors