Version: 1.3.5 · Blesta: 5.x · PHP: 8.2+ · Zimbra: 10.x
The Zimbra module integrates Blesta with a Zimbra 10.x mail server via its Admin SOAP API. It supports two distinct subscription models:
| Model | Description |
|---|---|
| Domain | Provision and manage an entire mail domain
(example.com). The domain owner controls all mailboxes via
admin or client tabs. |
| Mailbox | Provision a single email account (user@example.com).
The mailbox owner can change their password and manage aliases. |
Both models can be sold independently or together: a client can hold a domain subscription and then order additional mailbox subscriptions on top of it.
Upload the module — copy the
zimbra/ folder into your Blesta installation at:
<blesta_root>/components/modules/zimbra/Install in Blesta — navigate to: Settings → Company → Modules → Available Modules Find Zimbra and click Install.
Add a server — the module will show a prompt to add your first server. See Server Configuration below.
Manual installation only. The module is not distributed via Blesta’s marketplace importer; upload the files directly.
A valid license is required before any services can be provisioned. The module will still install and display tabs without a license, but creating new services will be blocked.
https://accounts.fxrm.com/ to
validate the key.| Status | Meaning |
|---|---|
valid |
License is active. Services can be provisioned. |
invalid |
Key was entered but failed validation. |
unlicensed |
No key has been set. |
expired |
License period has lapsed. |
suspended |
License has been administratively suspended. |
canceled |
License has been canceled. |
Click the Remove button on the module management page. This clears the stored key and data. The module remains installed and usable for managing existing services; only new provisioning is blocked.
The module re-validates the license with the license server approximately every 24 hours. If the server is temporarily unreachable, the cached status is used.
Each Zimbra server is added as a Module Row. Go to:
Settings → Company → Modules → Zimbra → Add Server
| Field | Required | Description |
|---|---|---|
| Server Label | Yes | A friendly name shown in the Blesta admin UI (e.g.,
Production Mail Server). Not sent to Zimbra. |
| Hostname | Yes | The fully qualified hostname or IP of the Zimbra server (e.g.,
mail.example.com). Must be a valid hostname or IP. |
| Admin Username | Yes | The Zimbra admin account used for API calls (e.g.,
admin@example.com). Stored encrypted. |
| Admin Password | Yes | Password for the admin account. Stored encrypted. |
| Use SSL | Yes | Enables HTTPS for Admin SOAP API calls. Strongly recommended. Uncheck only for HTTP-only setups. |
| Admin Port | No | The Admin SOAP port. Defaults to 7071. Some Zimbra
installations use 9071. Must be 1–65535. |
| Domain Limit | No | Maximum number of domains this server will accept. Leave blank for unlimited. |
| Notes | No | Free-text internal notes. Not used operationally. |
When you save a server, the module immediately tests the connection by authenticating with the Zimbra Admin SOAP API. If authentication fails, the server is not saved and an error is shown. Common causes:
7071 and 9071)Every Zimbra package has a Package Type selector. This determines what the package provisions and which tabs are shown on the service.
Use when: Selling email hosting for a complete
domain — the client gets their own @theirdomain.com and
manages all mailboxes within it.
Go to Packages → Create Package, select the Zimbra module, and set:
| Setting | Description | Notes |
|---|---|---|
| Package Type | Domain |
Determines the provisioning workflow. |
| Domain Aggregate Quota (GB) | Total storage pool for all mailboxes under this domain. | Default: 10. Set to 0 for unlimited. |
| Maximum Accounts | Maximum number of mailboxes the client can create. | Leave blank for unlimited. |
| Default Class of Service | The COS applied to new mailboxes created via Zimbra (not via Blesta). | Populated from your Zimbra server’s COS list. |
When a client orders a domain package:
zimbraMailQuota is set from Aggregate
Quota (converted to bytes).zimbraMaxAccountsLimit is set from Maximum
Accounts.zimbraDefaultCOSId is set if Default COS
is selected.| Field | Description |
|---|---|
| Domain | The domain name to create, e.g. myclientdomain.com.
Must be a valid domain format. |
The domain is automatically lowercased before provisioning.
Use when: Selling individual email accounts, either as standalone subscriptions or as add-ons under a domain service.
| Setting | Description | Notes |
|---|---|---|
| Package Type | Mailbox |
|
| Mailbox Domain | The Zimbra domain where accounts will be created. | Required unless using a parent domain service. E.g.
mail.yourcompany.com. |
| Class of Service | The COS assigned to each provisioned mailbox. | Populated from Zimbra server. Leave blank to use Zimbra’s default. |
| Mailbox Quota (MB) | Storage limit for each mailbox. | Default: 1024. Set to 0 for
unlimited. |
When a mailbox service is provisioned, the target domain is determined in this order:
This means you can:
| Field | Who Sees It | Description |
|---|---|---|
| Email Local Part | Admin + Client | The part before the @ (e.g. john.smith).
1–64 characters,
letters/numbers/./_/- only. |
| Password | Admin only | Initial mailbox password. If left blank, a random secure password is generated automatically. |
| Display Name | Admin + Client | The full name shown in email clients (e.g. John Smith).
1–256 characters. |
Clients cannot set their own password at order time; only admins can. Clients change their password via the self-service tab after the service is active.
If you run multiple Zimbra servers, you can create a Module Group to spread load across them.
| Strategy | Behaviour |
|---|---|
| First | Assigns to the first server in the group that has not reached its domain limit. |
| Round Robin | Distributes domains evenly across servers in order. |
Client places order for domain package
→ Blesta calls addService()
→ License check (fails? error shown, service not created)
→ Client-supplied domain name validated
→ API: AuthRequest (get session token)
→ API: CreateDomainRequest
name = "theirdomain.com"
zimbraMailQuota = <aggregate_quota in bytes>
zimbraMaxAccountsLimit = <max_accounts>
zimbraDefaultCOSId = <default_cos>
→ On success: stores zimbra_domain, zimbra_domain_id
→ Updates server domain count cacheClient places order for mailbox package
→ Blesta calls addService()
→ License check
→ Determine domain (parent service → package setting → error)
→ Validate email local part format (1–64 chars, alphanumeric + ._-)
→ Generate password if not provided
→ API: AuthRequest
→ API: CreateAccountRequest
name = "localpart@domain.com"
password = <password>
displayName = <display_name>
zimbraCOSId = <cos_id> (if set on package)
zimbraMailQuota = <quota_bytes> (if set on package)
→ On success: stores zimbra_domain, zimbra_email, zimbra_email_local,
zimbra_password (encrypted), zimbra_display_name, zimbra_account_iduse_module = false)If you need to create a service record in Blesta without actually provisioning it on Zimbra (e.g., importing an existing domain), uncheck Use Module during admin service creation. The service fields are stored but no API calls are made.
Admins can manage services from Clients → [client] → Services → [service] → Manage.
Available for both domain and mailbox services.
| Field | Source |
|---|---|
| Domain Name | Stored service field |
| Status | zimbraDomainStatus from Zimbra API |
| Aggregate Quota | zimbraMailQuota attribute (displayed in GB) |
| Quota Used | GetQuotaUsageRequest (sum of all mailbox usage) |
| Max Accounts | zimbraMaxAccountsLimit attribute |
| Current Accounts | Live count from GetDomainRequest COS breakdown |
| Field | Source |
|---|---|
| Email Address | Stored service field |
| Display Name | displayName attribute |
| Class of Service | zimbraCOSName attribute |
| Status | zimbraAccountStatus attribute |
| Quota | zimbraMailQuota attribute (displayed in MB) |
| Quota Used | GetQuotaUsageRequest |
Available for domain services only. Allows admins to manage all mailboxes within the domain.
The tab displays a table of all accounts under the domain with columns:
used / limit MB, or
used MB / UnlimitedThe heading shows current account count vs. the configured limit
(e.g., Mailboxes (3 / 10)). If Aggregate Quota is set on
the package, an info note shows the total domain quota.
Fill in the inline form at the bottom of the table:
| Field | Notes |
|---|---|
| Local Part | The username before the @.
Auto-lowercased. 1–64 chars. |
@domain.com |
Displayed automatically — cannot be changed here. |
| Display Name | Optional. Defaults to the local part if blank. |
| Password | Required. Enter a secure password. |
| Quota (MB) | Storage limit for this mailbox. 0 = unlimited. |
Click + Add. If the domain is at its account limit, the form is hidden and a message is displayed instead.
Click Quota next to any mailbox. A detail panel expands below the row showing the current quota value. Edit and click Save Quota.
Setting quota to
0removes the quota limit (unlimited storage, subject to the domain’s aggregate quota).
Click Reset Password next to any mailbox. A detail panel expands with a password field. Enter the new password and click Save Password.
Click Aliases next to any mailbox. A detail panel expands showing:
support), the @domain.com suffix is shown
automatically.Aliases are full email addresses that deliver to this mailbox. There is no limit other than what Zimbra enforces.
To add an alias: type the local part and click + Add. To remove an alias: click the red Remove button on the alias row.
The Aliases button shows a badge with the current alias count when aliases exist.
Click Delete next to any mailbox. A confirmation prompt is shown. On confirm, the account is permanently deleted from Zimbra.
Deletion is immediate and permanent. There is no recycle bin.
Available for domain services only. Distribution lists are group email addresses that forward to multiple recipients.
The tab shows all distribution lists under the domain with:
Fill in the form at the bottom:
| Field | Notes |
|---|---|
| Local Part | The listname before the @. |
| Display Name | Optional friendly name. |
| Description | Optional description. |
Click Create List.
Click Members next to a list. A detail panel expands showing current members and an add form.
Adding members: Enter one or more email addresses in the text area (one per line or comma-separated). Click Add Members.
Removing a member: Click Remove next to any individual member.
Click Delete next to the list. Confirmed via prompt. The list is permanently removed.
Clients access service management from their Client Portal → Services → [service] → Manage.
Clients with a domain subscription see the same tabs as admins (Statistics, Mailboxes, Distribution Lists) with the same functionality. This allows resellers to grant full domain management to their clients without Blesta admin access.
All forms use the same client-facing URIs and the same validation rules as the admin tabs.
Clients with a mailbox subscription see two tabs:
Displays their mailbox’s current statistics (read-only). See Mailbox Statistics above.
Two sections:
Change Password
| Field | Notes |
|---|---|
| New Password | Minimum 8 characters. |
| Confirm Password | Must match New Password. |
Click the button to save. A success message confirms the change.
Email Aliases
Displays a table of current aliases, each with a Remove button, followed by an Add Alias form.
| Field | Notes |
|---|---|
| Local Part | The alias username before the @. |
@domain.com |
Shown automatically from the account’s domain. |
Click Add Alias to create. Click Remove next to any existing alias to delete it.
Triggered when a service is suspended in Blesta (e.g., non-payment).
| Type | Zimbra Action |
|---|---|
| Domain | Sets zimbraDomainStatus → closed. All
mailboxes in the domain are immediately inaccessible. |
| Mailbox | Sets zimbraAccountStatus → closed. The
single account is inaccessible. |
Triggered when a suspended service is reactivated.
| Type | Zimbra Action |
|---|---|
| Domain | Sets zimbraDomainStatus → active. |
| Mailbox | Sets zimbraAccountStatus → active. |
Triggered when a service is cancelled or terminated.
| Type | Zimbra Action |
|---|---|
| Domain | Permanently deletes the domain from Zimbra. All mailboxes, data, and emails under the domain are destroyed. |
| Mailbox | Permanently deletes the account from Zimbra. All emails and data are destroyed. |
Cancellation is irreversible at the Zimbra level. Blesta does not archive data before deletion.
Admins can edit service fields in Blesta. Editable fields and their effect:
| Package Type | Field | Zimbra Action |
|---|---|---|
| Domain | Domain name | Not updated in Zimbra — domain rename is not supported. Stored value only. |
| Mailbox | Display Name | Updates displayName and cn on the Zimbra
account. |
| Mailbox | Password | Updates the account password in Zimbra. |
| Mailbox | Email Local Part | Not updated in Zimbra — email rename is not supported. |
These variables are available in Blesta email templates for Zimbra services:
| Tag | Value |
|---|---|
{m.host_name} |
Zimbra server hostname |
| Tag | Value |
|---|---|
{p.package_type} |
domain or mailbox |
{p.aggregate_quota} |
Domain quota in GB (domain packages) |
{p.max_accounts} |
Max mailbox limit (domain packages) |
{p.cos_id} |
Class of Service ID (mailbox packages) |
{p.mailbox_quota} |
Per-mailbox quota in MB (mailbox packages) |
| Tag | Value |
|---|---|
{s.zimbra_domain} |
The domain name (e.g. example.com) |
{s.zimbra_email} |
Full email address (mailbox packages) |
{s.zimbra_password} |
Mailbox password — use in welcome emails |
{s.zimbra_display_name} |
Mailbox display name |
Security note: Include
{s.zimbra_password}only in the initial welcome email. Do not include it in renewal or other routine emails.
The module communicates with Zimbra via the Admin SOAP API (port 7071 HTTPS). Ensure:
createDomain / deleteDomaincreateAccount / deleteAccount /
modifyAccountsetPasswordgetQuotaUsagecreateDistributionList /
deleteDistributionListaddAccountAlias / removeAccountAliasThe module does not enforce SSL certificate validation, so self-signed certificates on your Zimbra server are supported.
The module targets Zimbra 10.x. The SOAP API is stable across Zimbra versions, so earlier 8.x installations may work but are untested.
Classes of Service (COS) in Zimbra control what features a mailbox has access to. Configure COS in Zimbra Admin Console before setting up packages in Blesta.
| COS Name | Features to Enable | Blesta Package Idea |
|---|---|---|
| Basic | IMAP, POP3, Webmail only | Starter mailbox, small quota |
| Professional | + Calendar, Contacts, Tasks, Shared Folders | Business mailbox |
| Enterprise | + Mobile Sync (ActiveSync), Delegation, Briefcase | Premium mailbox |
Once created in Zimbra, they appear in the COS dropdowns on both domain and mailbox package configuration pages.
| Symptom | Likely Cause | Fix |
|---|---|---|
| “Connection failed” | Port unreachable | Check firewall; try port 9071 if 7071
fails. |
| “Authentication failed” | Bad credentials | Re-enter username/password; ensure account is not locked in Zimbra. |
| SSL errors | Hostname mismatch | The module bypasses SSL validation, so this should not occur. Check
use_ssl setting. |
| Timeout | Zimbra not running | Check Zimbra services with zmcontrol status. |
| Error | Cause | Fix |
|---|---|---|
Domain already exists |
Domain was previously created in Zimbra | Delete from Zimbra first, or use manual provisioning to import. |
api.result: ... |
Zimbra API error | Check Zimbra logs at /opt/zimbra/log/zimbra.log. |
license.required |
No valid license | Activate a license on the module management page. |
| Error | Cause | Fix |
|---|---|---|
Email address already exists |
Account exists in Zimbra | Delete from Zimbra first, or use manual provisioning. |
parent_service.required |
No domain to create mailbox on | Set Mailbox Domain on the package, or link the service to a parent domain service. |
zimbra_email_local.format |
Invalid characters in local part | Only a–z 0–9 . _ - are allowed; no spaces or special
characters. |
| COS not found | COS ID set on package no longer exists in Zimbra | Update package COS selection to match current Zimbra COS. |
Quota usage is fetched live from Zimbra’s
GetQuotaUsageRequest. If it shows 0:
zmmailboxdctl start or wait for the nightly indexing
job.Ensure you are on module version 1.3.2 or later.
Earlier versions did not explicitly request the
zimbraMailAlias attribute from Zimbra’s
SearchDirectoryRequest, which caused aliases to not be
returned on some Zimbra configurations.
The tab fetches live data from Zimbra on every page load. If data appears stale, it is likely a browser caching issue — hard refresh the page.
The license is re-validated every 24 hours. If validation recently failed (e.g., temporary network issue reaching the license server), the cached status may be stale. Go to Settings → Modules → Zimbra → Manage and check the license status. The module will attempt re-validation automatically on the next cycle.
For support, contact FXRM Services.