User Profile & Account API Reference

Inspect user account profile, subscription plan tier, monthly bandwidth consumption, and global forwarding preferences.

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/user`	`GET`	`user:read`	Retrieve account profile, active plan tier, and summary telemetry stats.
`/v1/user/profile`	`GET`	`user:read`	Retrieve detailed user profile, 2FA status, and identity settings.
`/v1/user/profile`	`PATCH`	`user:write`	Update profile information (name, username, website).
`/v1/user/settings`	`GET`	`user:read`	Retrieve global alias generation defaults and setup status.
`/v1/user/settings`	`PATCH`	`user:write`	Update generation rules and default domain configuration.
`/v1/user/bandwidth`	`GET`	`user:read`	Retrieve real-time monthly bandwidth usage and remaining transfer quota.
`/v1/user/entitlements`	`GET`	`user:read`	Inspect active plan entitlements and resource limits.
`/v1/user/email-settings`	`GET`	`user:read`	Retrieve global email delivery headers and banner configurations.
`/v1/user/email-settings`	`PATCH`	`user:write`	Update global delivery headers and banner configurations.

Plan Quotas & Tier Limits#

Tier	Monthly Bandwidth	Developer API Key Access	Sanitized Mode	WKD Auto-Encryption
Free	50 MB (`52,428,800` bytes)	Disabled (`403 FORBIDDEN`)	Disabled (Raw only)	Disabled (`403 PLAN_REQUIRED`)
Pro	1 GB (`1,073,741,824` bytes)	Disabled (Web dashboard only)	Enabled	Enabled
Business	Unlimited (`-1`)	Enabled (`api_access`)	Enabled	Enabled

Identity & Settings Hierarchy#

AliasFleet applies configuration settings hierarchically. Identity and formatting options cascade from account-level defaults down to specific aliases:

MERMAID

flowchart TD    A["Level 4: Global Account Settings (/v1/user/email-settings)"] --> B["Level 3: Destination Inboxes (/v1/destinations)"]    B --> C["Level 2: Custom Domains (/v1/domains)"]    C --> D["Level 1: Dedicated Alias Overrides (/v1/aliases/:id)"]    D --> E["Final Outbound Delivery Envelope"]

When an inbound email is processed, the system resolves sender display names, subject prefixes, and tracking preferences from Level 1 first. If unconfigured, it cascades downward to the global defaults set at Level 4.

Get User Summary & Stats#

GET /v1/user

Retrieves the authenticated user's core profile, subscription plan tier, and high-level forwarding telemetry.

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

Response (`200 OK`)#

JSON

{  "user": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "name": "Alex Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "plan": "pro"  },  "stats": {    "aliases_count": 42,    "aliases_limit": -1,    "emails_forwarded": 1284,    "emails_blocked": 315,    "emails_today": 18,    "emails_forwarded_week": 142,    "bandwidth_used": 4194304,    "bandwidth_limit": 1073741824  }}

Response Fields#

Field	Type	Description
`user.id`	`string (UUID)`	Unique identifier for the account user.
`user.email`	`string`	Primary login email address.
`user.name`	`string`	User display name.
`user.avatar_url`	`string \| null`	Hosted profile avatar URL.
`user.plan`	`string`	Active subscription tier (`"free"`, `"pro"`, `"business"`).
`stats.aliases_count`	`integer`	Total number of active aliases.
`stats.aliases_limit`	`integer`	Maximum aliases permitted on current plan (`-1` indicates unlimited).
`stats.emails_forwarded`	`integer`	All-time count of forwarded messages.
`stats.emails_blocked`	`integer`	All-time count of messages blocked by rules or denylists.
`stats.emails_today`	`integer`	Messages forwarded since midnight UTC.
`stats.emails_forwarded_week`	`integer`	Messages forwarded over the trailing 7 days.
`stats.bandwidth_used`	`integer`	Monthly data transferred in bytes.
`stats.bandwidth_limit`	`integer`	Monthly bandwidth cap in bytes (`-1` indicates unlimited).

Get User Profile#

GET /v1/user/profile

Retrieves detailed account profile information, security settings (2FA), and destination limits.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "profile": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "full_name": "Alex Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "username": "alexm",    "website": "https://example.com",    "identity_number": null,    "require_explicit_recipients": false,    "has_2fa_enabled": true,    "two_factor_method": "totp",    "bandwidth": 4194304,    "bandwidth_limit": 1073741824,    "subscription_plan": "pro",    "subscription_status": "active",    "subscription_expires_at": "2026-10-01T00:00:00.000Z",    "max_aliases": -1,    "max_destinations": 5,    "allowed_destinations": [      "alex.mercer@example.com"    ]  }}

Update User Profile#

PATCH /v1/user/profile

Updates user profile attributes such as display name, public username, and personal website.

Scope: user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`full_name`	`string`	Optional	Updated user display name (1–100 chars).
`username`	`string`	Optional	Unique handle (letters, numbers, hyphens).
`website`	`string`	Optional	Public website URL.
`require_explicit_recipients`	`boolean`	Optional	When enabled, aliases require explicit destination bindings before forwarding.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/profile" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "full_name": "Alexander Mercer",    "website": "https://alexmercer.dev"  }'

Response (`200 OK`)#

JSON

{  "success": true,  "profile": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "full_name": "Alexander Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "username": "alexm",    "website": "https://alexmercer.dev",    "identity_number": null,    "require_explicit_recipients": false,    "has_2fa_enabled": true,    "two_factor_method": "totp"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`VALIDATION_ERROR`	`"No valid fields provided to update"`	Payload contained no recognized profile fields.
`409`	`USERNAME_TAKEN`	`"Username already in use"`	Desired username is already claimed by another account.
`429`	`RATE_LIMIT`	`"Too many profile updates. Please wait a moment."`	Profile update rate limit exceeded.

Get User Settings#

GET /v1/user/settings

Retrieves global alias generator defaults and initial onboarding setup state.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "settings": {    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "setup_completed": true,    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": "-",      "add_random_number": true,      "char_count": 8    },    "default_domain_id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",    "default_destination_id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"  }}

Update User Settings#

PATCH /v1/user/settings

Modifies default alias generation parameters, primary domain selections, and onboarding status.

Scope: user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`default_generation_method`	`string`	Optional	Generator method: `"manual"`, `"random-words"`, `"website"`, `"uuid"`, `"keyword-random"`, `"bulk"`.
`generation_preferences`	`object`	Optional	Preferences dictionary (`word_count`, `separator`, `add_random_number`, `char_count`).
`default_domain_id`	`string (UUID)`	Optional	UUID of active system or custom domain to pre-select.
`default_destination_id`	`string (UUID)`	Optional	UUID of verified forwarding destination.
`setup_completed`	`boolean`	Optional	Onboarding setup completion status.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/settings" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": ".",      "add_random_number": false    }  }'

Response (`200 OK`)#

JSON

{  "success": true,  "settings": {    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "setup_completed": true,    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": ".",      "add_random_number": false,      "char_count": 8    },    "default_domain_id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",    "default_destination_id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"  }}

Get Bandwidth Usage#

GET /v1/user/bandwidth

Retrieves real-time data transfer metrics, monthly limits, current percentage consumption, and the next billing cycle reset timestamp.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "current": 4194304,  "limit": 1073741824,  "percentage": 0.39,  "remaining": 1069547520,  "status": "normal",  "plan": "pro",  "resetsAt": "2026-10-01T00:00:00.000Z",  "formatted": {    "current": "4.0 MB",    "limit": "1.0 GB",    "remaining": "1019.99 MB"  }}

Response Fields#

Field	Type	Description
`current`	`integer`	Bytes transmitted during current cycle.
`limit`	`integer`	Maximum bytes allowed per month (`-1` indicates unlimited).
`percentage`	`number`	Float percentage of monthly bandwidth consumed.
`remaining`	`integer`	Bytes remaining in the active cycle.
`status`	`string`	Bandwidth health status (`"normal"`, `"warning"`, `"critical"`, `"exceeded"`, `"unlimited"`).
`plan`	`string`	Active subscription plan identifier.
`resetsAt`	`string`	ISO 8601 timestamp when usage counters reset.
`formatted`	`object`	Human-readable string representations (e.g. `"4.0 MB"`, `"1.0 GB"`).

Get Plan Entitlements#

GET /v1/user/entitlements

Inspects exact quota allowances, active resource counts, and feature entitlements for your account.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "userId": "d3b07384-d113-4674-bc50-a88981298418",  "plan": "pro",  "status": "active",  "reason": "active",  "isEntitled": true,  "features": {    "sanitized_forwarding": true,    "pgp_encryption": true,    "custom_domains": true,    "advanced_routing": true,    "api_access": false,    "webhook_raw_mime": false  },  "limits": {    "aliases": { "max": -1, "used": 42, "remaining": -1, "overage": 0 },    "custom_domains_count": { "max": 3, "used": 2, "remaining": 1, "overage": 0 },    "destinations": { "max": 5, "used": 3, "remaining": 2, "overage": 0 },    "categories": { "max": 15, "used": 4, "remaining": 11, "overage": 0 },    "rules": { "max": 20, "used": 6, "remaining": 14, "overage": 0 },    "webhook_endpoints": { "max": 2, "used": 1, "remaining": 1, "overage": 0 },    "bandwidth_bytes_per_month": { "max": 1073741824, "used": 4194304, "remaining": 1069547520, "overage": 0 }  },  "currentPeriodEnd": "2026-10-01T00:00:00.000Z"}

Global Email Routing Settings#

GET /v1/user/email-settings and PATCH /v1/user/email-settings

Configure Level 4 account-wide identity defaults, tracking pixel neutralization, and spam handling behaviors.

Scope: user:read / user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema (`PATCH`)#

Field	Type	Required	Description
`globalFromName`	`string \| null`	Optional	Fallback sender display name (max 255 chars).
`useGlobalFromName`	`boolean`	Optional	Toggle whether to apply the fallback display name.
`globalSubject`	`string \| null`	Optional	Fallback subject prefix or override.
`useGlobalSubject`	`boolean`	Optional	Toggle whether to apply the global subject prefix.
`trackerNeutralizationEnabled`	`boolean`	Optional	Strip remote tracking beacons and 1x1 pixels from forwarded HTML.
`rawForwarding`	`boolean`	Optional	When set to `false`, enables Sanitized Mode (requires Pro or Business plan).
`spamFilterMode`	`string`	Optional	Spam evaluation mode: `"off"`, `"flag"`, or `"aggressive"`.
`fromAddressFormat`	`string`	Optional	Options: `"name_only"` or `"name_and_email"`.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/email-settings" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "globalFromName": "Alex Mercer",    "useGlobalFromName": true,    "trackerNeutralizationEnabled": true,    "spamFilterMode": "aggressive"  }'

Response (`200 OK`)#

JSON

{  "success": true}

Error Responses#

Status Code	Code	Error Message	Reason
`403`	`ENTITLEMENT_FORBIDDEN`	`"Sanitized Mode is a premium feature. Please upgrade your plan to enable tracker blocking and safety banners."`	Setting `rawForwarding: false` on Free plan.
`429`	`RATE_LIMIT`	`"Too many settings updates. Please wait a moment."`	Settings update rate limit exceeded.

Frequently Asked Questions

Bandwidth tracks the total raw byte volume of emails routed and forwarded across all your account aliases during the billing cycle. It resets automatically on the first day of each calendar month.

When usage reaches 100% of your plan allowance, status updates to 'exceeded'. Accounts on free tiers may experience forwarding throttling or temporary pauses until the reset date or until upgraded to a higher tier.

Global identity settings (such as globalFromName and globalSubject) serve as account-wide fallbacks. Per-alias identity configurations override destination-level settings, which in turn override global account defaults.

Yes. Querying GET /v1/user/entitlements returns an exhaustive breakdown of active resource limits (aliases, destinations, custom domains, categories, webhooks) and boolean feature flags for your current subscription plan.

Inspect user account profile, subscription plan tier, monthly bandwidth consumption, and global forwarding preferences.

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/user`	`GET`	`user:read`	Retrieve account profile, active plan tier, and summary telemetry stats.
`/v1/user/profile`	`GET`	`user:read`	Retrieve detailed user profile, 2FA status, and identity settings.
`/v1/user/profile`	`PATCH`	`user:write`	Update profile information (name, username, website).
`/v1/user/settings`	`GET`	`user:read`	Retrieve global alias generation defaults and setup status.
`/v1/user/settings`	`PATCH`	`user:write`	Update generation rules and default domain configuration.
`/v1/user/bandwidth`	`GET`	`user:read`	Retrieve real-time monthly bandwidth usage and remaining transfer quota.
`/v1/user/entitlements`	`GET`	`user:read`	Inspect active plan entitlements and resource limits.
`/v1/user/email-settings`	`GET`	`user:read`	Retrieve global email delivery headers and banner configurations.
`/v1/user/email-settings`	`PATCH`	`user:write`	Update global delivery headers and banner configurations.

Plan Quotas & Tier Limits#

Tier	Monthly Bandwidth	Developer API Key Access	Sanitized Mode	WKD Auto-Encryption
Free	50 MB (`52,428,800` bytes)	Disabled (`403 FORBIDDEN`)	Disabled (Raw only)	Disabled (`403 PLAN_REQUIRED`)
Pro	1 GB (`1,073,741,824` bytes)	Disabled (Web dashboard only)	Enabled	Enabled
Business	Unlimited (`-1`)	Enabled (`api_access`)	Enabled	Enabled

Identity & Settings Hierarchy#

AliasFleet applies configuration settings hierarchically. Identity and formatting options cascade from account-level defaults down to specific aliases:

MERMAID

flowchart TD    A["Level 4: Global Account Settings (/v1/user/email-settings)"] --> B["Level 3: Destination Inboxes (/v1/destinations)"]    B --> C["Level 2: Custom Domains (/v1/domains)"]    C --> D["Level 1: Dedicated Alias Overrides (/v1/aliases/:id)"]    D --> E["Final Outbound Delivery Envelope"]

Get User Summary & Stats#

GET /v1/user

Retrieves the authenticated user's core profile, subscription plan tier, and high-level forwarding telemetry.

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

Response (`200 OK`)#

JSON

{  "user": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "name": "Alex Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "plan": "pro"  },  "stats": {    "aliases_count": 42,    "aliases_limit": -1,    "emails_forwarded": 1284,    "emails_blocked": 315,    "emails_today": 18,    "emails_forwarded_week": 142,    "bandwidth_used": 4194304,    "bandwidth_limit": 1073741824  }}

Response Fields#

Field	Type	Description
`user.id`	`string (UUID)`	Unique identifier for the account user.
`user.email`	`string`	Primary login email address.
`user.name`	`string`	User display name.
`user.avatar_url`	`string \| null`	Hosted profile avatar URL.
`user.plan`	`string`	Active subscription tier (`"free"`, `"pro"`, `"business"`).
`stats.aliases_count`	`integer`	Total number of active aliases.
`stats.aliases_limit`	`integer`	Maximum aliases permitted on current plan (`-1` indicates unlimited).
`stats.emails_forwarded`	`integer`	All-time count of forwarded messages.
`stats.emails_blocked`	`integer`	All-time count of messages blocked by rules or denylists.
`stats.emails_today`	`integer`	Messages forwarded since midnight UTC.
`stats.emails_forwarded_week`	`integer`	Messages forwarded over the trailing 7 days.
`stats.bandwidth_used`	`integer`	Monthly data transferred in bytes.
`stats.bandwidth_limit`	`integer`	Monthly bandwidth cap in bytes (`-1` indicates unlimited).

Get User Profile#

GET /v1/user/profile

Retrieves detailed account profile information, security settings (2FA), and destination limits.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "profile": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "full_name": "Alex Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "username": "alexm",    "website": "https://example.com",    "identity_number": null,    "require_explicit_recipients": false,    "has_2fa_enabled": true,    "two_factor_method": "totp",    "bandwidth": 4194304,    "bandwidth_limit": 1073741824,    "subscription_plan": "pro",    "subscription_status": "active",    "subscription_expires_at": "2026-10-01T00:00:00.000Z",    "max_aliases": -1,    "max_destinations": 5,    "allowed_destinations": [      "alex.mercer@example.com"    ]  }}

Update User Profile#

PATCH /v1/user/profile

Updates user profile attributes such as display name, public username, and personal website.

Scope: user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`full_name`	`string`	Optional	Updated user display name (1–100 chars).
`username`	`string`	Optional	Unique handle (letters, numbers, hyphens).
`website`	`string`	Optional	Public website URL.
`require_explicit_recipients`	`boolean`	Optional	When enabled, aliases require explicit destination bindings before forwarding.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/profile" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "full_name": "Alexander Mercer",    "website": "https://alexmercer.dev"  }'

Response (`200 OK`)#

JSON

{  "success": true,  "profile": {    "id": "d3b07384-d113-4674-bc50-a88981298418",    "email": "alex.mercer@example.com",    "full_name": "Alexander Mercer",    "avatar_url": "https://avatar.aliasfleet.com/u/d3b07384-d113-4674-bc50-a88981298418.png",    "username": "alexm",    "website": "https://alexmercer.dev",    "identity_number": null,    "require_explicit_recipients": false,    "has_2fa_enabled": true,    "two_factor_method": "totp"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`VALIDATION_ERROR`	`"No valid fields provided to update"`	Payload contained no recognized profile fields.
`409`	`USERNAME_TAKEN`	`"Username already in use"`	Desired username is already claimed by another account.
`429`	`RATE_LIMIT`	`"Too many profile updates. Please wait a moment."`	Profile update rate limit exceeded.

Get User Settings#

GET /v1/user/settings

Retrieves global alias generator defaults and initial onboarding setup state.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "settings": {    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "setup_completed": true,    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": "-",      "add_random_number": true,      "char_count": 8    },    "default_domain_id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",    "default_destination_id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"  }}

Update User Settings#

PATCH /v1/user/settings

Modifies default alias generation parameters, primary domain selections, and onboarding status.

Scope: user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`default_generation_method`	`string`	Optional	Generator method: `"manual"`, `"random-words"`, `"website"`, `"uuid"`, `"keyword-random"`, `"bulk"`.
`generation_preferences`	`object`	Optional	Preferences dictionary (`word_count`, `separator`, `add_random_number`, `char_count`).
`default_domain_id`	`string (UUID)`	Optional	UUID of active system or custom domain to pre-select.
`default_destination_id`	`string (UUID)`	Optional	UUID of verified forwarding destination.
`setup_completed`	`boolean`	Optional	Onboarding setup completion status.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/settings" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": ".",      "add_random_number": false    }  }'

Response (`200 OK`)#

JSON

{  "success": true,  "settings": {    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "setup_completed": true,    "default_generation_method": "random-words",    "generation_preferences": {      "format": "random-words",      "word_count": 3,      "separator": ".",      "add_random_number": false,      "char_count": 8    },    "default_domain_id": "9f83a21b-4c7d-4e9a-8b7c-6d5e4f3a2b1c",    "default_destination_id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"  }}

Get Bandwidth Usage#

GET /v1/user/bandwidth

Retrieves real-time data transfer metrics, monthly limits, current percentage consumption, and the next billing cycle reset timestamp.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "current": 4194304,  "limit": 1073741824,  "percentage": 0.39,  "remaining": 1069547520,  "status": "normal",  "plan": "pro",  "resetsAt": "2026-10-01T00:00:00.000Z",  "formatted": {    "current": "4.0 MB",    "limit": "1.0 GB",    "remaining": "1019.99 MB"  }}

Response Fields#

Field	Type	Description
`current`	`integer`	Bytes transmitted during current cycle.
`limit`	`integer`	Maximum bytes allowed per month (`-1` indicates unlimited).
`percentage`	`number`	Float percentage of monthly bandwidth consumed.
`remaining`	`integer`	Bytes remaining in the active cycle.
`status`	`string`	Bandwidth health status (`"normal"`, `"warning"`, `"critical"`, `"exceeded"`, `"unlimited"`).
`plan`	`string`	Active subscription plan identifier.
`resetsAt`	`string`	ISO 8601 timestamp when usage counters reset.
`formatted`	`object`	Human-readable string representations (e.g. `"4.0 MB"`, `"1.0 GB"`).

Get Plan Entitlements#

GET /v1/user/entitlements

Inspects exact quota allowances, active resource counts, and feature entitlements for your account.

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

cURL Example#

Terminal

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

Response (`200 OK`)#

JSON

{  "userId": "d3b07384-d113-4674-bc50-a88981298418",  "plan": "pro",  "status": "active",  "reason": "active",  "isEntitled": true,  "features": {    "sanitized_forwarding": true,    "pgp_encryption": true,    "custom_domains": true,    "advanced_routing": true,    "api_access": false,    "webhook_raw_mime": false  },  "limits": {    "aliases": { "max": -1, "used": 42, "remaining": -1, "overage": 0 },    "custom_domains_count": { "max": 3, "used": 2, "remaining": 1, "overage": 0 },    "destinations": { "max": 5, "used": 3, "remaining": 2, "overage": 0 },    "categories": { "max": 15, "used": 4, "remaining": 11, "overage": 0 },    "rules": { "max": 20, "used": 6, "remaining": 14, "overage": 0 },    "webhook_endpoints": { "max": 2, "used": 1, "remaining": 1, "overage": 0 },    "bandwidth_bytes_per_month": { "max": 1073741824, "used": 4194304, "remaining": 1069547520, "overage": 0 }  },  "currentPeriodEnd": "2026-10-01T00:00:00.000Z"}

Global Email Routing Settings#

GET /v1/user/email-settings and PATCH /v1/user/email-settings

Configure Level 4 account-wide identity defaults, tracking pixel neutralization, and spam handling behaviors.

Scope: user:read / user:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema (`PATCH`)#

Field	Type	Required	Description
`globalFromName`	`string \| null`	Optional	Fallback sender display name (max 255 chars).
`useGlobalFromName`	`boolean`	Optional	Toggle whether to apply the fallback display name.
`globalSubject`	`string \| null`	Optional	Fallback subject prefix or override.
`useGlobalSubject`	`boolean`	Optional	Toggle whether to apply the global subject prefix.
`trackerNeutralizationEnabled`	`boolean`	Optional	Strip remote tracking beacons and 1x1 pixels from forwarded HTML.
`rawForwarding`	`boolean`	Optional	When set to `false`, enables Sanitized Mode (requires Pro or Business plan).
`spamFilterMode`	`string`	Optional	Spam evaluation mode: `"off"`, `"flag"`, or `"aggressive"`.
`fromAddressFormat`	`string`	Optional	Options: `"name_only"` or `"name_and_email"`.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/user/email-settings" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "globalFromName": "Alex Mercer",    "useGlobalFromName": true,    "trackerNeutralizationEnabled": true,    "spamFilterMode": "aggressive"  }'

Response (`200 OK`)#

JSON

{  "success": true}

Error Responses#

Status Code	Code	Error Message	Reason
`403`	`ENTITLEMENT_FORBIDDEN`	`"Sanitized Mode is a premium feature. Please upgrade your plan to enable tracker blocking and safety banners."`	Setting `rawForwarding: false` on Free plan.
`429`	`RATE_LIMIT`	`"Too many settings updates. Please wait a moment."`	Settings update rate limit exceeded.

Quick Reference#

Plan Quotas & Tier Limits#

Identity & Settings Hierarchy#

Get User Summary & Stats#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Get User Profile#

cURL Example#

Response (200 OK)#

Update User Profile#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Get User Settings#

cURL Example#

Response (200 OK)#

Update User Settings#

Request Body Schema#

cURL Example#

Response (200 OK)#

Get Bandwidth Usage#

cURL Example#

Response (200 OK)#

Response Fields#

Get Plan Entitlements#

cURL Example#

Response (200 OK)#

Global Email Routing Settings#

Request Body Schema (PATCH)#

cURL Example#

Response (200 OK)#

Error Responses#

Frequently Asked Questions

How is monthly bandwidth usage calculated and reset?

What happens when bandwidth quota is exceeded?

How do global identity defaults interact with per-alias settings?

Can I inspect feature entitlements programmatically?

Was this article helpful?

Related in Developer API

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Destinations API

Still need help?

Quick Reference#

Plan Quotas & Tier Limits#

Identity & Settings Hierarchy#

Get User Summary & Stats#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Get User Profile#

cURL Example#

Response (200 OK)#

Update User Profile#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Get User Settings#

cURL Example#

Response (200 OK)#

Update User Settings#

Request Body Schema#

cURL Example#

Response (200 OK)#

Get Bandwidth Usage#

cURL Example#

Response (200 OK)#

Response Fields#

Get Plan Entitlements#

cURL Example#

Response (200 OK)#

Global Email Routing Settings#

Request Body Schema (PATCH)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Request Body Schema (`PATCH`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Request Body Schema (`PATCH`)#

Response (`200 OK`)#