Managing Tenants

Overview

As a reseller, tenants are the core unit you manage. Each tenant represents one of your customers and gets its own isolated environment with a separate database, storage space, and subdomain. You can manage tenants through the REST API or via the WHMCS integration.

Creating a Tenant

To create a new tenant, you need to provide at minimum a slug and a name. The slug becomes the subdomain (e.g., slug acme becomes acme.archive.yourcompany.com) and must be globally unique, contain only lowercase letters, numbers, and hyphens, and be between 3 and 48 characters long.

When you create a tenant, the following happens automatically:

• A dedicated PostgreSQL database is created (ema_t_{slug})
• A dedicated S3 storage prefix is allocated (ema-t-{slug}/)
• All required database tables are provisioned via migrations
• The tenant becomes accessible at its subdomain

Listing Tenants

You can retrieve a list of all tenants under your reseller account via the API. The list includes each tenant's slug, name, status, user count, storage usage, and creation date. Results are paginated for accounts with many tenants.

Updating a Tenant

After creation, you can update a tenant's display name and branding overrides (custom name, primary color, logo, favicon). The slug cannot be changed after creation because it is tied to the database name and storage prefix.

Suspending a Tenant

If a customer fails to pay or you need to temporarily disable access, you can suspend a tenant. Suspended tenants:

• Cannot be accessed by any users (login is blocked)
• Retain all their data (messages, users, settings)
• Continue to receive incoming email for archiving
• Can be unsuspended at any time to restore full access

Suspension is non-destructive. It is the recommended way to handle billing disputes or temporary deactivation.

Unsuspending a Tenant

Unsuspending a tenant restores full access immediately. All users can log in again, and the tenant functions as if it was never suspended. No data is lost during the suspension period.

Deleting a Tenant

Tenant deletion is a permanent action and is not available through the self-service API. To delete a tenant and all associated data, contact our support team. This safeguard exists to prevent accidental data loss, especially in compliance-sensitive environments.

Best Practices

• Use meaningful slugs - Choose slugs that identify the customer (e.g., acme-corp) because they cannot be changed later.
• Monitor usage regularly - Use the usage stats endpoint to track active users and storage consumption per tenant.
• Suspend before deleting - If a customer cancels, suspend first. This gives you time to confirm the cancellation and allows the customer to change their mind.
• Test with a sandbox tenant - Create a test tenant to verify branding and configuration before onboarding production customers.