Users

A User represents an end customer in your platform.

Every user is provisioned under your partner account and can own domains, mailboxes, subscriptions, orders, and billing information.

Quick Reference

Aspect	Information
Route Prefix	`/users`
Primary Identifier	`userId`
Returned From	`POST /users`
Required For	All domain, mailbox, subscription, and order operations
Deletion Rule	User must have 0 domains and 0 mailboxes before deletion

Endpoints

Method	Endpoint	Description
`GET`	`/users/list`	List all users with pagination and search support.
`GET`	`/users?userId=`	Retrieve details for a specific user.
`POST`	`/users`	Create a new user.
`PUT`	`/users?userId=`	Update billing information.
`DELETE`	`/users?userId=`	Permanently delete a user.

INFO

All string fields (except email) support Unicode letters, numbers, spaces, and the following characters:

. , ' # & ( ) / -

HTML-encoded characters such as ' are automatically decoded before validation.

Deletion Eligibility

Condition	Can Delete?
No domains and no mailboxes	✅ Yes
Active mailboxes exist	❌ No
Active domains exist	❌ No

TIP

Delete or transfer all domains and remove all mailboxes before attempting to delete a user.

Common Workflows

Create a User

Create User

Endpoint: POST /users

Submit the user's billing information.

Store userId

Save the returned userId.

You'll use this value for all future requests involving this customer.

Update Billing Information

Retrieve Current Information

Endpoint: GET /users?userId=

Retrieve the existing billing information.

Update

Endpoint: PUT /users?userId=

Send the complete billing object with the modified values.

Delete a User

Cancel Active Subscriptions

Cancel all active mailbox subscriptions.

Remove Domains

Delete or transfer every domain owned by the user.

Delete User

DELETE /users?userId=

Once no resources remain, the user can be permanently deleted.

WARNING

Deleting a user is permanent.

The operation removes all associated data, including billing records, wallet balance, workspaces, orders, and related resources.

This action cannot be undone.

Avoid These Common Issues

Incorrect userId: Always use the userId returned by POST /users or GET /users/list. Do not use internal UUIDs.

Partial Billing Updates: PUT /users requires the complete billing object. Sending only the modified fields returns a 400 Bad Request.

Existing Resources: A user cannot be deleted while they still own mailboxes or domains. If deletion fails, check the returned mailboxCount and domainCount values, remove those resources, and retry the request.

Next Steps

Domains

Manage domains owned by a user.

Mailboxes

Provision and manage mailboxes.

Subscriptions

Manage mailbox renewals and billing.

Quick Reference#

Endpoints#

Deletion Eligibility#

Common Workflows#

Create a User#

Update Billing Information#

Delete a User#

Avoid These Common Issues#

Next Steps#

Quick Reference

Endpoints

Deletion Eligibility

Common Workflows

Create a User

Update Billing Information

Delete a User

Avoid These Common Issues

Next Steps