Multi-Domain Management
Relevant source files
The following files were used as context for generating this wiki page:The Multi-Domain Management system is a core feature of the platform, enabling users to add, verify, and manage their own domain names to create custom email inboxes. This functionality supports a multi-tenant architecture where individual users can operate within their own domains, and also contribute domains for public use by other platform users, subject to administrator approval.
The system handles the entire lifecycle of a domain, from initial creation and DNS-based ownership verification to managing its visibility (public vs. private) and eventual deletion. It is supported by a dedicated set of API endpoints and user interface components for both standard users and administrators.
Sources: README.md, blueprint.md:41-46
Data Model
The domain management feature revolves around the Domain model. Each domain is associated with a User who owns it and can have multiple Inboxes.
Sources: blueprint.md:112-115
ER Diagram
This diagram shows the relationship between the User, Domain, and Inbox models.
Domain Model Fields
The Domain table stores all information related to a user-added domain.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the domain. |
name | String | The domain name (e.g., example.com). Must be unique. |
ownerId | String | Foreign key linking to the User who owns the domain. |
status | Enum | The verification status of the domain. Can be PENDING or VERIFIED. |
verificationToken | String | A unique token generated for DNS-based ownership verification. |
isPublic | Boolean | If true, the domain is available for all users to create inboxes on. |
contributionStatus | Enum | The status of a user's request to make their domain public. Values: NONE, PENDING_REVIEW, APPROVED, REJECTED. |
createdAt | DateTime | Timestamp of when the domain was added. |
sharedAt | DateTime | Timestamp of when the domain was made public. |
Sources: blueprint.md:113-114, services/api/src/routes/domains.ts:208-212,234-242
Domain Onboarding and Verification
The process for a user to add and verify a new domain involves interaction between the frontend, the API, and the domain's DNS provider.
Verification Flow
This sequence diagram illustrates the steps a user takes to verify ownership of their domain.
Required DNS Records
For a domain to be fully functional for receiving emails and to be verified, the user must configure specific DNS records. The UI provides guidance on this.
| Type | Host | Value | Purpose |
|---|---|---|---|
MX | @ | mail.[your-server] (priority 10) | Required to route emails for the domain to the platform's mail server. |
A | mail | <YOUR_SERVER_IP> | Points the mail subdomain to the server's IP address. |
TXT | @ | [verification token] | Used to prove ownership of the domain during the verification step. |
Sources: services/web/src/pages/MyDomains.tsx:149-171, services/web/src/components/AdminPanel.tsx:405-430, blueprint.md:73-77
API Endpoints
Domain management is handled through a set of RESTful API endpoints. All endpoints require authentication.
Source: services/api/src/routes/domains.ts
| Endpoint | Method | Description |
|---|---|---|
/domains | GET | Lists domains. Admins see all domains; users see their own and public domains. Supports search and pagination. |
/domains | POST | Creates a new domain. It is assigned to the authenticated user with PENDING status and a verificationToken. |
/domains/:id/verify | POST | Triggers the DNS verification process for a domain. |
/domains/:id | PATCH | Updates a domain. Used to change isPublic status or contributionStatus. |
/domains/:id | DELETE | Deletes a domain. Can only be done by the owner or an admin. |
GET /domains
Retrieves a list of domains.
Query Parameters:
| Parameter | Type | Optional | Description |
|---|---|---|---|
search | string | Yes | Filters domains by name. |
limit | number | Yes | Number of records to return (default 100, max 200). |
offset | number | Yes | Number of records to skip for pagination. |
contributionStatus | enum | Yes | Filters by contribution status (NONE, PENDING_REVIEW, APPROVED, REJECTED). |
Sources: services/api/src/routes/domains.ts:6-47
POST /domains
Adds a new domain.
Request Body:
{
"name": "example.com"
}
If the creator is an admin, the domain is automatically made public (isPublic: true).
Sources: services/api/src/routes/domains.ts:49-80
POST /domains/:id/verify
Verifies domain ownership via DNS. The backend logic calls verifyDomainOwnership to perform a live TXT record lookup.
Sources: services/api/src/routes/domains.ts:82-132
PATCH /domains/:id
Updates a domain's properties, primarily for sharing and contribution.
Request Body:
{
"isPublic": true,
"contributionStatus": "PENDING_REVIEW"
}
- Only an admin can approve/reject a contribution.
- A domain must be
VERIFIEDbefore it can be made public. - When a contribution is
APPROVED, the domain is automatically set toisPublic: true.
Sources: services/api/src/routes/domains.ts:155-255
Domain Sharing & Contribution
The platform allows users to share their verified domains with other users. This can be done directly by the owner or through a formal contribution process moderated by an administrator.
State Management
The isPublic and contributionStatus fields control the sharing state of a domain.
This diagram shows the lifecycle of a domain's sharing status.
Key Logic
- Owner Request: A domain owner can set
contributionStatustoPENDING_REVIEWto offer their domain for public use. The domain must beVERIFIED. - Admin Approval: An admin can change the
contributionStatustoAPPROVED. This action automatically setsisPublictotrue. - Direct Sharing: An owner or admin can directly toggle the
isPublicflag on a verified domain without going through the contribution flow. - Un-sharing: An owner cannot make a domain private if other users have created inboxes on it. An admin can override this.
Sources: services/api/src/routes/domains.ts:192-221, services/api/src/test/shared_domains.test.ts
User Interface
Domain management is exposed to users and administrators through dedicated UI components.
My Domains Page
Located at services/web/src/pages/MyDomains.tsx, this page is the primary interface for users to manage the domains they own.
Features:
- List owned domains with their status (
VERIFIEDorPENDING). - Add new domains.
- View DNS configuration instructions and copy the verification token.
- Trigger the verification process.
- Toggle the
isPublicstatus for verified domains. - Delete domains.
Sources: services/web/src/pages/MyDomains.tsx
Admin Panel
The admin panel, defined in services/web/src/components/AdminPanel.tsx, provides a DomainsList component for comprehensive management of all domains in the system.
Admin-Specific Features:
- View all domains, regardless of owner.
- See owner information for each domain.
- Force-verify a domain.
- Toggle the
isPublicstatus for any domain. - Delete any domain.
Sources: services/web/src/components/AdminPanel.tsx:376-566, services/api/src/routes/admin.ts:133-255
Conclusion
The Multi-Domain Management system is a robust and flexible feature that forms the backbone of the platform's multi-tenancy. It provides a clear and secure workflow for users to add and verify domains, with powerful administrative controls for oversight. The inclusion of a domain sharing and contribution model further enhances collaboration and resource utilization across the platform.