Tenant Provisioning

Overview

Tenant provisioning is the process of setting up a new customer environment in Easy Mail Archive. When you create a tenant through the API or WHMCS module, the platform automatically configures an isolated environment with its own database, storage, and access URL. This article explains what happens behind the scenes and what you need to know as a reseller.

What Happens During Provisioning

When you send a create request to the API, the following steps are performed automatically:

1. Slug validation - The system checks that the slug is unique, follows naming rules (3-48 characters, lowercase alphanumeric and hyphens), and is not a reserved word
2. Tenant record creation - A record is inserted in the platform database linking the tenant to your reseller account
3. Database creation - A dedicated PostgreSQL database is created with the name ema_t_{slug}
4. Schema migration - All required tables (messages, users, settings, audit logs, etc.) are created in the new database
5. Storage allocation - An S3 storage prefix ema-t-{slug}/ is allocated for the tenant's archived messages
6. Branding inheritance - The tenant inherits your reseller branding (name, logo, colors, favicon) unless overrides are specified

The entire provisioning process typically completes within a few seconds.

The Slug

The slug is the most important identifier for a tenant. It determines:

• The subdomain - {slug}.archive.yourcompany.com
• The database name - ema_t_{slug}
• The storage prefix - ema-t-{slug}/

Because the slug is deeply embedded in the infrastructure, it cannot be changed after creation. Choose slugs carefully and use a consistent naming convention across your customer base.

Slug Naming Rules

• Minimum 3 characters, maximum 48 characters
• Only lowercase letters (a-z), numbers (0-9), and hyphens (-)
• Must start with a letter
• Must not end with a hyphen
• Must be globally unique across all resellers

Recommended Naming Conventions

• Use the customer's company name: acme-corp, smith-law, nordtech
• Use a domain-based approach: acme-com, smith-law-de
• Add a prefix for your own organization: mycompany-acme, mycompany-smith

Data Isolation

Each tenant is fully isolated at the infrastructure level:

• Database isolation - Every tenant has its own PostgreSQL database. There is no shared table or schema. One tenant's queries never touch another tenant's data.
• Storage isolation - Each tenant's archived messages are stored under a unique S3 prefix. Access controls ensure tenants cannot read each other's files.
• Session isolation - User sessions are scoped to a specific tenant. A user authenticated on one tenant cannot access another tenant's data.

Post-Provisioning Setup

After a tenant is provisioned, the tenant administrator typically completes these steps:

1. Add domains - Register the email domains that should be archived
2. Create users - Add user accounts for team members who need archive access
3. Configure email routing - Set up journaling or SMTP forwarding to deliver copies of emails to the archive
4. Set security policies - Configure two-factor authentication requirements and other security settings

As a reseller, you can assist your customers with these steps or provide them with documentation to complete the setup independently.

Provisioning Failures

In rare cases, provisioning may fail due to:

• Slug conflicts - The slug is already taken (API returns 409 Conflict)
• Validation errors - The slug or name does not meet formatting requirements (API returns 422)
• Infrastructure issues - Temporary issues with database or storage provisioning (API returns 500)

If provisioning fails with a server error, wait a moment and retry the request. If the issue persists, contact our support team.