Destinations API

Register forwarding inboxes, manage 6-digit OTP verification challenges, configure custom sender identities, and manage routing targets.

Quick Reference

GET /v1/destinations — List Destinations

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

Returns all destination inboxes registered to your account, including pending verification states and default inbox resolution.

Example Request

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

Response (200 OK)

{
  "destinations": [
    {
      "id": "dest_adn6UTmkzn6OWpGq",
      "email": "primary-ops@company.com",
      "is_verified": true,
      "is_active": true,
      "can_reply": true,
      "can_send": true,
      "verified_at": "2026-06-16T09:44:04.169Z",
      "failed_attempts": 0,
      "blocked_until": null,
      "is_default": true,
      "created_at": "2026-06-01T12:00:00.000Z"
    },
    {
      "id": "dest_rNZO2x0c8GPOJxiR",
      "email": "alerts@company.com",
      "is_verified": false,
      "is_active": true,
      "can_reply": false,
      "can_send": false,
      "verification_sent_at": "2026-09-04T14:30:00.000Z",
      "verified_at": null,
      "failed_attempts": 0,
      "blocked_until": null,
      "is_default": false,
      "created_at": "2026-09-04T14:30:00.000Z"
    }
  ],
  "default_destination": {
    "id": "dest_adn6UTmkzn6OWpGq",
    "email": "primary-ops@company.com",
    "is_verified": true,
    "is_active": true
  }
}

GET /v1/destinations/verified — List Verified Destinations

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

Returns only destinations that have passed OTP verification and are actively available to receive forwarded emails.

Example Request

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

Response (200 OK)

{
  "destinations": [
    {
      "id": "dest_adn6UTmkzn6OWpGq",
      "email": "primary-ops@company.com",
      "is_verified": true,
      "is_active": true,
      "can_reply": true,
      "can_send": true
    }
  ]
}

POST /v1/destinations — Register New Destination

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

Registers an external email address as a destination inbox. Dispatches a 6-digit numeric verification code to the specified address.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/destinations" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "audit-inbox@company.com"
  }'

Response (201 Created)

{
  "destination": {
    "id": "dest_kLpQr2nVwYz3a4b5",
    "email": "audit-inbox@company.com",
    "is_verified": false,
    "is_active": true,
    "can_reply": false,
    "can_send": false,
    "verification_sent_at": "2026-09-04T15:00:00.000Z",
    "failed_attempts": 0,
    "created_at": "2026-09-04T15:00:00.000Z"
  }
}

Errors

POST /v1/destinations/verify — Verify Destination OTP

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

Submits the 6-digit verification code sent to the destination email address. Upon verification, the inbox unlocks immediately for alias routing.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/destinations/verify" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "audit-inbox@company.com",
    "code": "481923"
  }'

Response (200 OK)

{
  "message": "Destination verified"
}

Errors

POST /v1/destinations/resend — Resend Verification OTP

Scope: destinations:write · Rate Limit: 5/min · Idempotent: Yes

Generates and emails a fresh 6-digit OTP code to the destination address. Enforces a 60-second cooldown period per address.

Request Body Parameters

Example Request

curl -X POST "https://api.aliasfleet.com/v1/destinations/resend" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "audit-inbox@company.com"
  }'

Response (200 OK)

{
  "message": "Verification email resent"
}

Errors

PATCH /v1/user/default-destination — Set Default Destination

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

Sets the primary default inbox for your account. New aliases provisioned without an explicit recipient will automatically forward to this address.

Request Body Parameters

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/user/default-destination" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dest_adn6UTmkzn6OWpGq"
  }'

Response (200 OK)

{
  "success": true,
  "default_destination": {
    "id": "dest_adn6UTmkzn6OWpGq",
    "email": "primary-ops@company.com"
  }
}

Errors

GET /v1/destinations/:id/usage — Inspect Destination Usage

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

Returns the total number of active aliases currently forwarding to this destination inbox.

Path Parameters

Example Request

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

Response (200 OK)

{
  "alias_count": 27
}

PATCH /v1/destinations/:id/from-name — Configure Sender Identity

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

Configures sender display names, subjects, and format overrides on messages routed through this destination.

Request Body Parameters

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/destinations/dest_adn6UTmkzn6OWpGq/from-name" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send",
    "fromName": "Acme Operations Team",
    "useFromName": true,
    "subject": "[Acme Notice] ",
    "useSubject": true
  }'

Response (200 OK)

{
  "success": true
}

DELETE /v1/destinations/:id — Delete Destination

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

Permanently removes a destination inbox from your workspace.

Path Parameters

Example Request

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

Response (200 OK)

{
  "success": true,
  "message": "Destination removed"
}

Errors