Destinations & Inboxes API Reference

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

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/destinations`	`GET`	`destinations:read`	List all destination inboxes with default resolution.
`/v1/destinations/verified`	`GET`	`destinations:read`	List only verified inboxes eligible for alias routing.
`/v1/destinations`	`POST`	`destinations:write`	Register a new destination and trigger 6-digit OTP email.
`/v1/destinations/verify`	`POST`	`destinations:write`	Submit 6-digit OTP code to verify ownership.
`/v1/destinations/resend`	`POST`	`destinations:write`	Resend verification code (60-second cooldown).
`/v1/destinations/:id/usage`	`GET`	`destinations:read`	Inspect active aliases linked to this destination.
`/v1/destinations/:id/from-name`	`PATCH`	`destinations:write`	Configure custom sender display name and subject rules.
`/v1/destinations/:id`	`DELETE`	`destinations:write`	Delete destination with smart reassignment support.

List Destinations#

GET /v1/destinations

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

Scope: destinations:readRate Limit: 60 req/minIdempotent: Yes

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/destinations" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "destinations": [    {      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",      "email": "primary-ops@company.com",      "is_verified": true,      "is_active": 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": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",      "email": "alerts@company.com",      "is_verified": false,      "is_active": true,      "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"    }  ]}

List Verified Destinations#

GET /v1/destinations/verified

Returns only destinations that have completed 6-digit OTP verification. Useful for populating destination selection dropdowns.

Scope: destinations:readRate Limit: 60 req/minIdempotent: Yes

Response (`200 OK`)#

JSON

{  "destinations": [    {      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",      "email": "primary-ops@company.com",      "verified_at": "2026-06-16T09:44:04.169Z",      "created_at": "2026-06-01T12:00:00.000Z",      "updated_at": "2026-06-16T09:44:04.169Z"    }  ]}

Register Destination#

POST /v1/destinations

Registers a new destination email address and immediately dispatches a 6-digit verification code to the target inbox.

Scope: destinations:writeRate Limit: 5 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Description
`email`	`string`	Yes	Valid RFC 5322 email address for the destination inbox.

cURL Example#

Terminal

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

Response (`201 Created`)#

JSON

{  "message": "Verification code sent to your email",  "data": {    "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "email": "dev-alerts@company.com",    "is_verified": false,    "is_active": true,    "created_at": "2026-09-04T12:00:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`DESTINATION_SUPPRESSED`	`"This email address or domain is restricted and cannot be added as a destination."`	Address is globally blacklisted or rejected by anti-abuse policies.
`403`	`LIMIT_REACHED`	`"Destination limit reached. Please upgrade your plan."`	Account has reached the maximum allowed destination inboxes (1 on Free, 5 on Pro, 20 on Business).
`409`	`DUPLICATE_DESTINATION`	`"This destination email has already been added to your account."`	Address is already registered to your account.
`429`	`RATE_LIMIT_EXCEEDED`	`"Too Many Requests"`	Destination creation rate limit (5 req/min) exceeded.

Verify Destination (Submit OTP)#

POST /v1/destinations/verify

Submits the 6-digit numeric OTP code received in the destination inbox to complete verification.

Scope: destinations:writeRate Limit: 60 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Constraints	Description
`destination_id`	`string`	Yes	UUID	Identifier of the pending destination.
`token`	`string`	Yes	6 digits	Numeric code from the verification email.

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/destinations/verify" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "destination_id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "token": "482915"  }'

Response (`200 OK`)#

JSON

{  "message": "Email verified successfully",  "destination": {    "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "email": "dev-alerts@company.com",    "is_verified": true,    "verified_at": "2026-09-04T12:05:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`INVALID_CODE`	`"Invalid verification code"`	The entered code does not match. Attempt counter incremented.
`400`	`CODE_EXPIRED`	`"Verification code has expired. Please request a new one."`	Code exceeded the 15-minute validity window.
`429`	`MAX_ATTEMPTS_EXCEEDED`	`"Too many failed attempts. Please request a new code in 15 minutes."`	3 consecutive failures triggered a 15-minute temporary lockout.

Resend Verification Code#

POST /v1/destinations/resend

Generates and dispatches a fresh 6-digit verification code. Enforces a 60-second cooldown between requests.

Scope: destinations:writeRate Limit: 1 req / 60sIdempotent: No

Request Body Schema#

Field	Type	Required	Description
`destination_id`	`string`	Yes	UUID of the pending destination.

Response (`200 OK`)#

JSON

{  "message": "Verification code resent successfully"}

Inspect Destination Usage#

GET /v1/destinations/:id/usage

Retrieves all active aliases linked to this destination either directly (forward_to_email) or through multi-destination recipient links.

Scope: destinations:readRate Limit: 60 req/min

Path Parameters#

Parameter	Type	Required	Description
`id`	`string`	Yes	UUID of the destination inbox.

Response (`200 OK`)#

JSON

{  "destination_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",  "email": "primary-ops@company.com",  "count": 2,  "aliases": [    {      "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",      "local_part": "billing-support",      "domain": "company.com",      "is_active": true    },    {      "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",      "local_part": "security-alerts",      "domain": "company.com",      "is_active": true    }  ]}

Delete Destination#

DELETE /v1/destinations/:id

Deletes a destination inbox with automated dependency checks and smart reassignment support.

Scope: destinations:writeRate Limit: 60 req/minIdempotent: Yes

Request Body Schema (Smart Reassignment)#

When deleting a destination with dependent aliases, provide resolution instructions:

Field	Type	Required	Constraints	Description
`action`	`string`	Optional	`"reassign"` or `"deactivate"`	Strategy for handling dependent aliases.
`reassign_to_destination_id`	`string`	Optional*	UUID	Required when `action === "reassign"`. Target verified destination.

cURL Example (Reassign and Delete)#

Terminal

curl -X DELETE "https://api.aliasfleet.com/v1/destinations/8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "action": "reassign",    "reassign_to_destination_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"  }'

Response (`200 OK`)#

JSON

{  "success": true,  "message": "Destination deleted successfully"}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`PRIMARY_EMAIL_PROTECTED`	`"You cannot delete your primary account email destination"`	Cannot delete the email address linked to your primary account profile.
`400`	`LAST_VERIFIED_PROTECTED`	`"You must keep at least one verified destination"`	Accounts require at least one verified destination inbox for routing.
`400`	`DEPENDENT_ALIASES`	`"Cannot delete destination with dependent aliases"`	Destination is in active use. Response includes `aliases` array and `count`. Provide `action: 'reassign'` or `'deactivate'`.
`404`	`NOT_FOUND`	`"Destination not found"`	Destination ID does not exist.

Frequently Asked Questions

No. Incoming emails are dropped or held until destination ownership is confirmed through the 6-digit OTP verification handshake.

Verification codes expire 15 minutes after issuance. If entered incorrectly 3 consecutive times, a 15-minute lockout activates to prevent brute-force attempts.

The API rejects deletion with HTTP 400 DEPENDENT_ALIASES, returning the list of linked aliases. You can delete by passing a smart reassignment body ({ action: 'reassign', reassign_to_destination_id }) or deactivating them ({ action: 'deactivate' }).

No. The primary account email address is protected against deletion (HTTP 400 PRIMARY_EMAIL_PROTECTED) to prevent accidental account lockouts.

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

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/destinations`	`GET`	`destinations:read`	List all destination inboxes with default resolution.
`/v1/destinations/verified`	`GET`	`destinations:read`	List only verified inboxes eligible for alias routing.
`/v1/destinations`	`POST`	`destinations:write`	Register a new destination and trigger 6-digit OTP email.
`/v1/destinations/verify`	`POST`	`destinations:write`	Submit 6-digit OTP code to verify ownership.
`/v1/destinations/resend`	`POST`	`destinations:write`	Resend verification code (60-second cooldown).
`/v1/destinations/:id/usage`	`GET`	`destinations:read`	Inspect active aliases linked to this destination.
`/v1/destinations/:id/from-name`	`PATCH`	`destinations:write`	Configure custom sender display name and subject rules.
`/v1/destinations/:id`	`DELETE`	`destinations:write`	Delete destination with smart reassignment support.

List Destinations#

GET /v1/destinations

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

Scope: destinations:readRate Limit: 60 req/minIdempotent: Yes

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/destinations" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "destinations": [    {      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",      "email": "primary-ops@company.com",      "is_verified": true,      "is_active": 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": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",      "email": "alerts@company.com",      "is_verified": false,      "is_active": true,      "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"    }  ]}

List Verified Destinations#

GET /v1/destinations/verified

Returns only destinations that have completed 6-digit OTP verification. Useful for populating destination selection dropdowns.

Scope: destinations:readRate Limit: 60 req/minIdempotent: Yes

Response (`200 OK`)#

JSON

{  "destinations": [    {      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",      "email": "primary-ops@company.com",      "verified_at": "2026-06-16T09:44:04.169Z",      "created_at": "2026-06-01T12:00:00.000Z",      "updated_at": "2026-06-16T09:44:04.169Z"    }  ]}

Register Destination#

POST /v1/destinations

Registers a new destination email address and immediately dispatches a 6-digit verification code to the target inbox.

Scope: destinations:writeRate Limit: 5 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Description
`email`	`string`	Yes	Valid RFC 5322 email address for the destination inbox.

cURL Example#

Terminal

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

Response (`201 Created`)#

JSON

{  "message": "Verification code sent to your email",  "data": {    "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "email": "dev-alerts@company.com",    "is_verified": false,    "is_active": true,    "created_at": "2026-09-04T12:00:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`DESTINATION_SUPPRESSED`	`"This email address or domain is restricted and cannot be added as a destination."`	Address is globally blacklisted or rejected by anti-abuse policies.
`403`	`LIMIT_REACHED`	`"Destination limit reached. Please upgrade your plan."`	Account has reached the maximum allowed destination inboxes (1 on Free, 5 on Pro, 20 on Business).
`409`	`DUPLICATE_DESTINATION`	`"This destination email has already been added to your account."`	Address is already registered to your account.
`429`	`RATE_LIMIT_EXCEEDED`	`"Too Many Requests"`	Destination creation rate limit (5 req/min) exceeded.

Verify Destination (Submit OTP)#

POST /v1/destinations/verify

Submits the 6-digit numeric OTP code received in the destination inbox to complete verification.

Scope: destinations:writeRate Limit: 60 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Constraints	Description
`destination_id`	`string`	Yes	UUID	Identifier of the pending destination.
`token`	`string`	Yes	6 digits	Numeric code from the verification email.

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/destinations/verify" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "destination_id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "token": "482915"  }'

Response (`200 OK`)#

JSON

{  "message": "Email verified successfully",  "destination": {    "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",    "email": "dev-alerts@company.com",    "is_verified": true,    "verified_at": "2026-09-04T12:05:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`INVALID_CODE`	`"Invalid verification code"`	The entered code does not match. Attempt counter incremented.
`400`	`CODE_EXPIRED`	`"Verification code has expired. Please request a new one."`	Code exceeded the 15-minute validity window.
`429`	`MAX_ATTEMPTS_EXCEEDED`	`"Too many failed attempts. Please request a new code in 15 minutes."`	3 consecutive failures triggered a 15-minute temporary lockout.

Resend Verification Code#

POST /v1/destinations/resend

Generates and dispatches a fresh 6-digit verification code. Enforces a 60-second cooldown between requests.

Scope: destinations:writeRate Limit: 1 req / 60sIdempotent: No

Request Body Schema#

Field	Type	Required	Description
`destination_id`	`string`	Yes	UUID of the pending destination.

Response (`200 OK`)#

JSON

{  "message": "Verification code resent successfully"}

Inspect Destination Usage#

GET /v1/destinations/:id/usage

Retrieves all active aliases linked to this destination either directly (forward_to_email) or through multi-destination recipient links.

Scope: destinations:readRate Limit: 60 req/min

Path Parameters#

Parameter	Type	Required	Description
`id`	`string`	Yes	UUID of the destination inbox.

Response (`200 OK`)#

JSON

{  "destination_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",  "email": "primary-ops@company.com",  "count": 2,  "aliases": [    {      "id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",      "local_part": "billing-support",      "domain": "company.com",      "is_active": true    },    {      "id": "8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e",      "local_part": "security-alerts",      "domain": "company.com",      "is_active": true    }  ]}

Delete Destination#

DELETE /v1/destinations/:id

Deletes a destination inbox with automated dependency checks and smart reassignment support.

Scope: destinations:writeRate Limit: 60 req/minIdempotent: Yes

Request Body Schema (Smart Reassignment)#

When deleting a destination with dependent aliases, provide resolution instructions:

Field	Type	Required	Constraints	Description
`action`	`string`	Optional	`"reassign"` or `"deactivate"`	Strategy for handling dependent aliases.
`reassign_to_destination_id`	`string`	Optional*	UUID	Required when `action === "reassign"`. Target verified destination.

cURL Example (Reassign and Delete)#

Terminal

curl -X DELETE "https://api.aliasfleet.com/v1/destinations/8b7c6d5e-4f3a-2b1c-0d9e-8f7a6b5c4d3e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "action": "reassign",    "reassign_to_destination_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"  }'

Response (`200 OK`)#

JSON

{  "success": true,  "message": "Destination deleted successfully"}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`PRIMARY_EMAIL_PROTECTED`	`"You cannot delete your primary account email destination"`	Cannot delete the email address linked to your primary account profile.
`400`	`LAST_VERIFIED_PROTECTED`	`"You must keep at least one verified destination"`	Accounts require at least one verified destination inbox for routing.
`400`	`DEPENDENT_ALIASES`	`"Cannot delete destination with dependent aliases"`	Destination is in active use. Response includes `aliases` array and `count`. Provide `action: 'reassign'` or `'deactivate'`.
`404`	`NOT_FOUND`	`"Destination not found"`	Destination ID does not exist.

Quick Reference#

List Destinations#

Request Headers#

cURL Example#

Response (200 OK)#

List Verified Destinations#

Response (200 OK)#

Register Destination#

Request Body Schema#

cURL Example#

Response (201 Created)#

Error Responses#

Verify Destination (Submit OTP)#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Resend Verification Code#

Request Body Schema#

Response (200 OK)#

Inspect Destination Usage#

Path Parameters#

Response (200 OK)#

Delete Destination#

Request Body Schema (Smart Reassignment)#

cURL Example (Reassign and Delete)#

Response (200 OK)#

Error Responses#

Frequently Asked Questions

Can aliases forward to unverified destinations?

How long does a destination verification code remain valid?

What happens if I try to delete a destination with active aliases?

Can I remove my primary account email from destinations?

Was this article helpful?

Related in Developer API

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Quick-Send API

Still need help?

Quick Reference#

List Destinations#

Request Headers#

cURL Example#

Response (200 OK)#

List Verified Destinations#

Response (200 OK)#

Register Destination#

Request Body Schema#

cURL Example#

Response (201 Created)#

Error Responses#

Verify Destination (Submit OTP)#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Resend Verification Code#

Request Body Schema#

Response (200 OK)#

Inspect Destination Usage#

Path Parameters#

Response (200 OK)#

Delete Destination#

Request Body Schema (Smart Reassignment)#

cURL Example (Reassign and Delete)#

Response (200 OK)#

Error Responses#

Frequently Asked Questions

Can aliases forward to unverified destinations?

How long does a destination verification code remain valid?

What happens if I try to delete a destination with active aliases?

Can I remove my primary account email from destinations?

Was this article helpful?

Related in Developer API

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Response (`200 OK`)#

Response (`200 OK`)#

Response (`201 Created`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`201 Created`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#