Skip to main content
WisMail

Run an email hosting business with WisMail

This guide is for a hosting reseller: you buy WisMail, run it on your own server, and sell mailboxes and domains to your own clients. It walks you from the first plan to automatic provisioning from your billing system, in the order you do it. Allow an afternoon for a first test client, more if you build your own integration. You need a working server first: follow the install guide and the DNS guide.

1. How it fits together

You run one or more WisMail servers. Your clients bring their own domains (client1.com) and get mailboxes on them. Three pieces cooperate:

  • Your WisMail server: stores the mail, runs SMTP, IMAP, webmail and web administration. It enforces the plan limits.
  • Your billing system (WHMCS, a control panel, or your own code): takes the order and the payment, then tells the server what to create, suspend or delete through the provisioning API.
  • Your clients' domains: DNS records at the client's registrar or yours point the domain to your server (MX, SPF, DKIM, DMARC).

The provisioning API is a REST interface built into the server. It runs the same operations as web administration, so password rules, license limits and the audit log behave the same whether a person or your billing system makes the change. Every mailbox you create for a client counts against your WisMail license user count; when the license is full, creating or enabling a mailbox is refused (license_limit_reached). Check the license terms for resale with us before you launch; see license activation and pricing.

2. Define your plans and their limits

A plan is a set of limits applied to a client's domain when it is created. WisMail supports these:

Limit What it controls Starting value
Domain storage Total disk for all mailboxes of the domain. A message that would exceed it is refused with 5.2.2 User quota exceeded and the sender gets a bounce 10 GB
Mailbox quota Disk for each mailbox, given to new mailboxes 2 GB
Max mailboxes How many mailboxes (enabled and suspended) the domain may have 5
Forwarding Whether mailboxes may forward to other addresses through the API allowed
Send rate per mailbox Messages one mailbox may send per hour and per day 50 per hour, 500 per day
Send rate for the whole domain Optional cap on all mailboxes together off (0)

0 always means unlimited. A starting ladder you can adapt:

Plan Mailboxes Domain storage Per mailbox Per hour / per day
Starter 5 10 GB 2 GB 50 / 500
Business 25 50 GB 5 GB 100 / 1,000
Pro 100 250 GB 10 GB 200 / 2,000

These are suggestions, not product defaults: tune them to your costs and your clients.

Why a send rate matters. One compromised mailbox on one client can send thousands of spam messages in an hour and put your server IP on blacklists, which hurts every other client. The send-rate limit is your safety net. It counts one unit per recipient of every message sent through SMTP, webmail, ActiveSync or EWS, over rolling 60-minute and 24-hour windows. Over the limit the server answers a temporary error (452 4.7.25 Sending rate limit exceeded, retry later), the client keeps the message and retries, and the event is written to the security log. Start strict and raise it for a client who asks. A mailbox can have its own override of the domain value.

Where to set them:

  • By hand: in web administration open Configuration, Domains, edit the domain, and use the Quota tab (domain disk space) and the Messages tab (sending rate limit, per mailbox and whole domain).
Web administration, domain settings, Messages tab: sending rate limit per mailbox and for the whole domain
  • Automatically: the same values travel in the provisioning API call that creates the domain, or in your WHMCS product (sections 4 and 5).

Know the limits of the limits: the maximum number of mailboxes is enforced by the provisioning API and the WHMCS module; a mailbox you create by hand in web administration is not blocked by it (it still counts). The forwarding switch only governs forwards set through the API; it does not stop a user from adding a forward with a webmail rule. A changed domain default quota applies to new mailboxes only, not to existing ones.

3. Turn on automation: create an API key

  1. Sign in to web administration as a full administrator and open Configuration, API Keys.
  2. Choose Generate key. Give it a label such as whmcs-prod, pick the scope, and keep the default requests-per-minute limit unless you need more.
  3. Copy the key now. It looks like wmk_1a2b3c4d_... and is shown once; the server stores only a hash and cannot show it again. If you lose it, revoke it and generate another.
Web administration, Configuration, API Keys: the Generate API key dialog with a label, scope and request limit

Scopes: Read and write (provisioning) for the billing system that creates and changes things; Read only (provisioning.read) for a metering or reporting tool that only reads usage (a write with it is refused). Use a separate key per system so you can revoke one without breaking the others.

Rules for the key:

  • It is a password for your whole hosting estate. Keep it in your billing system's server settings, never in a web page, a script in a public repository, or a ticket.
  • Use HTTPS only. The API refuses plain HTTP from anywhere except the server itself. Install a real certificate first: SSL with Let's Encrypt.
  • Every call is written to the config log with the key's label as the actor, so you can see who did what. Revoke in the same screen stops a key immediately.
  • Each key has a request rate limit; going over it answers 429 with a Retry-After header.

4. Option A: sell with WHMCS

If you already bill with WHMCS 8, use the ready-made server module. It needs PHP 7.4 to 8.3 with the curl extension.

  1. Download the module: wismail-whmcs-1.0.0.zip. Unzip it into your WHMCS root so that modules/servers/wismail/wismail.php exists. The zip contains a README.md with the full reference.
  2. In WHMCS open System Settings, Products/Services, Servers, Add New Server. Set the Hostname to your mail server name, the Module to WisMail Email Hosting, and paste the API key into Password. Tick Secure. Choose Test Connection: it calls the server status endpoint and tells you if the key or its scope is wrong.
  3. Create a product: Products/Services, Create, type Hosting Account, then Module Settings, module WisMail Email Hosting. Map your plan in the Config Options:
    • Max Mailboxes, Storage GB (whole domain), Per-mailbox Quota GB
    • Send rate/hour and Send rate/day (per mailbox)
    • Allow Forwarding, Admin Mailbox Name (default admin)
    • 0 means unlimited. Choose automatic setup after the first payment.
  4. Place a test order. The client types their mail domain in the Domain field. WHMCS creates the domain with the plan limits and the first mailbox admin@<domain>, which is also a delegated administrator (section 6).

What the module does for each WHMCS action:

In WHMCS On the mail server
Create Domain with the plan, then the admin mailbox
Change Package Applies the new plan limits to the domain
Change Password Resets the admin mailbox password
Suspend / Unsuspend Suspends or re-enables the domain (section 8)
Terminate Deletes the domain, its mailboxes and mail, irreversibly
Services tab, client area Shows status, mailboxes, storage and sent counts
Usage update Reads disk usage for each service

Retries are safe: an existing domain or mailbox from a half-finished attempt is reconciled, and suspending twice is harmless. The Module Log in WHMCS records every call with the key and passwords masked. The service password must satisfy the domain password policy (minimum length, three of four character classes, not containing the user or domain name). Note that this module has been verified against the live API with a test harness; run your first orders on a WHMCS test installation before you take real payments.

5. Option B: call the REST API directly

For your own panel or billing code, use the API at https://<your-server>/api/provisioning/v1 (port 443, or 4040). The full contract is an OpenAPI 3 document, served without a key at https://<your-server>/api/provisioning/v1/openapi.json; generate a client from it in the language you use. Requests and answers are JSON, sizes are in bytes, 0 is unlimited, and unknown fields are rejected so a typo never passes silently.

KEY=wmk_1a2b3c4d_REPLACE_WITH_YOUR_KEY
BASE=https://mail.example.com/api/provisioning/v1

# Test the key
curl -sS $BASE/status -H "Authorization: Bearer $KEY"

# Create a client domain with its plan (10 GB, 5 mailboxes, 2 GB each, 50/hour, 500/day)
curl -sS -X POST $BASE/domains -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
  "name": "client1.com",
  "limits": {"max_mailboxes": 5, "storage_bytes": 10737418240, "default_mailbox_quota_bytes": 2147483648,
             "allow_forwarding": true, "send_rate": {"per_mailbox_hour": 50, "per_mailbox_day": 500}}}'

# Create a mailbox that is also the domain administrator
curl -sS -X POST $BASE/mailboxes -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"address": "[email protected]", "password": "Zq7!kTr82vLp", "full_name": "Info", "domain_admin": true}'

# Read usage for invoicing
curl -sS $BASE/usage/client1.com -H "Authorization: Bearer $KEY"

Errors always have the form {"error": {"code": "...", "message": "..."}}; switch on code (for example mailbox_limit_reached, domain_suspended, weak_password). Creating something that already exists answers 409, which a retrying client can treat as done after a read. Change a plan later with PATCH /domains/<domain> and only the members you send change.

6. Give each client a domain administrator

So that you do not have to create every mailbox for your client, make one mailbox of their domain a domain administrator (the AccountAdmin role): tick it when you create the mailbox through the API ("domain_admin": true, the WHMCS module does this for the admin mailbox), or open the user in web administration, tab Rights.

That person signs in to web administration at https://<your-server>:4040/admin/ with their mailbox address and password and sees only the Accounts section of their own domain: users, groups, aliases, mailing lists and resources. They can add and remove their own mailboxes and reset passwords. They cannot change plan limits, cannot see other domains, and cannot see server settings, so your plan stays under your control. Server-wide administrator accounts are never touched by the API.

Everyone else uses webmail at https://<your-server>/webmail/ or a mail client; send them the webmail guide and the phone setup guide. If you want a branded address for the admin console, put a reverse proxy in front of port 4040.

7. Deliverability for every client domain

A mailbox is only useful if its mail reaches inboxes. Every client domain needs its own records, which the API does not create for you:

  • MX pointing to your server, so inbound mail arrives.
  • SPF allowing your server to send for the domain.
  • DKIM: turn on signing for the domain in web administration and give the client the TXT record to publish.
  • DMARC so receivers know your policy.
  • PTR (reverse DNS) for your server's IP address. This one is yours, once, for the server, and is the record clients cannot fix.

The DNS guide lists each record with a dig check. In web administration, Status, Setup & Health shows the records to publish and the readiness of the server. Put a "DNS records to add" email or page in your onboarding so clients publish them on day one, and read anti-spam and anti-virus to protect inbound mail. If your server IP has a poor reputation or port 25 is blocked, send through a relay: SMTP relay.

8. Lifecycle: suspend, resume, cancel and bill

Connect your billing events to the API (the WHMCS module already does):

  • Suspend (unpaid invoice): suspending a domain disables every active mailbox in it and remembers which ones, and new mailboxes cannot be created there. Unsuspend re-enables exactly those. Mail, folders and settings are kept.
  • Terminate (cancellation): deleting a domain with its mailboxes and mail cannot be undone. Decide your retention and backup policy before you offer self-service cancellation (backup and restore).
  • Usage for invoicing: GET /usage returns one row per domain, and GET /usage/<domain> adds a row per mailbox: mailbox count and limit, storage used and limit, last login, and messages sent in the last hour and day.

Current limits, stated plainly:

  • A suspended mailbox is a disabled account. Login and sending are refused, and incoming mail to it is rejected with a "mailbox does not exist" bounce. There is no "hold the mail" mode yet, so a sender is told the address does not exist while the client is suspended. Warn clients before suspension, and keep suspension periods short.
  • Sessions that are already open end when the client disconnects; they are not cut off at once.
  • Sent-message counters are in memory: they exist only while a send-rate limit applies and a server restart resets them. Storage and mailbox counts are exact. For exact monthly sending totals, read the mail log.
  • The primary domain of the server cannot be suspended or deleted through the API.

Next steps