All help articles

Tenant administration

A tenant's owners and admins manage their own tenant in the domain admin panel at /manage, or at its own host name (see Host names). They use the same address and password as for webmail. Everything else stays with the platform operator in the SaaS admin panel.

Turning it on

Tenant administration is a plan feature, off until the operator turns it on:

1. In the admin panel open Plans, edit the plan, and tick Tenant administration (team_admin). From the command line: corpsuite plan set team entitlements:=[..., "team_admin"] with the plan's other entitlements.
2. Give the people who run the tenant the Owner or Admin role on the tenant's page under Mailboxes. Members and guests never see the panel.

They then find Manage your tenant (the people icon) in webmail's top bar. It opens the panel signed in. On another host name, they sign in there with their mail address, password and, if they use it, the code from their authenticator app.

What a tenant can do

• See the tenant's plan, seats and usage, and the outgoing mail queue.
• Mailboxes: add mailboxes on the tenant's own domains, change names, passwords, recovery addresses and roles, suspend and reactivate them, reset two-step sign-in, revoke app passwords, lower a mailbox's limits, turn plan features off for one user (Features) and choose what happens to their name+tag@ mail.
• Support: answer the tenant's tickets and keep notes on mailboxes (see The support desk).
• Import: copy a mailbox's mail from their old server over IMAP (see Importing mail).
• Sign-ins: a mailbox's sign-in history and open webmail sessions, sign them out everywhere, and Unlock an account locked after wrong passwords (see Sign-in security).
• Aliases: add and remove aliases on the tenant's own domains.
• Domains: add domains after proving them (below), change their mail settings (SPF, DMARC, MTA-STS, plus addressing), manage DKIM keys, read DMARC reports, and see the DNS records to publish.
• Filters: the tenant-wide and domain-wide filter rules, and a mailbox's filters and vacation reply.

What stays with the operator

• The plan, the number of seats, the tenant's name and status.
• Raising a mailbox's limits above the plan's, or giving a mailbox features the plan lacks.
• Addresses on shared domains (those come from signup, where reserved names are kept back).
• Invitations, plans, shared domains and platform settings.
• externalRef, the link to a billing or platform system.

Roles

A mailbox has one of the six roles a Zappocity organization's members have: owner, admin, billing, support, member or guest. In Mailocity, owners and admins manage the tenant; billing and support work as member does (on Zappocity they see the organization's invoices and its tickets); guests cannot edit the tenant's wikis. Only an owner gives the owner or billing role, since billing members pay for the organization on Zappocity.

The tenant's people are its Zappocity organization's members, with the same roles: a role changed here reaches the organization within a minute, and one changed there (by Zappocity's staff) reaches the mailboxes. See Members, roles and names stay the same.

Owners and admins

Both can do everything above, with these differences:

• Only an owner can make someone an owner, or change, suspend or reset anything of an owner.
• Only an owner can change the tenant-wide and domain-wide filter rules, because they run for everyone's mail, owners' included. Admins can read them.
• Nobody can change their own role or suspend themselves in the panel. A tenant that wants a new owner has an owner make them one first.

Tenant roles

Owners and admins can let other members manage parts of the tenant without making them admins. On the tenant page, Tenant roles → New role names a role and ticks what it manages:

Give the role on the member's mailbox (Tenant role), or with corpsuite mailbox set USER teamRoleId=ROLE-ID. They then sign in to the tenant manager like an admin and see only those parts. Whatever the role, they never change owners or admins, give roles, manage roles, open a mailbox, or touch the archive and legal holds, and they can only add members and guests. Deleting a role takes it from its members.

From the command line: corpsuite tenant roles TENANT, tenant role create TENANT name=Helpdesk permissions:='["users","support"]', tenant role set, tenant role delete.

Adding a domain

A tenant proves that a domain is theirs before it is added, so nobody can claim a domain they do not control and catch mail meant for it.

1. Under Domains, choose Add domain, type the name and choose Get the DNS record.
2. Publish the TXT record shown, for example _zappocity-verify.example.com with the text zappocity-verify=3k7q..., at the domain's DNS provider.
3. Choose Check now. Once the record is found, the domain is added with a first DKIM key, and its page lists the other records to publish (MX, SPF, DKIM, DMARC, MTA-STS). Until then nothing about the domain counts as mail for this server.

The record can be removed once the domain is added. A tenant can have 20 domains waiting, and the plan's domain limit applies when one is added.

The platform operator proves domains the same way, unless they choose Add it now without proof (or skipProof in the API) for a domain they know the tenant owns. Domains need a DNS TXT record before they are added in the admin panel's settings (on by default) controls this.

Claiming a domain someone else added

Only a proved domain is taken. If a domain was added without proof, by another tenant or by the operator, its rightful owner can still request it and publish the record:

• When nothing uses it where it is (no mailboxes or aliases), it moves to the tenant that proved it.
• When it has mailboxes or aliases there, the claim waits and says so; contact the platform operator, who moves or removes those mailboxes, and then Check now succeeds.
• A tenant that already has the domain without proof proves it the same way, and the domain is marked proved.
• A domain already on the tenant without proof shows its ownership record in its DNS list, with Verify on its page; publishing the record and choosing Verify proves it.
• The platform operator can also mark a domain proved by hand (Mark as proved next to it on the tenant's page, on the domain's page, or on a domain still waiting for its record; corpsuite domain prove TENANT DOMAIN) after checking who owns it. From then on nobody can claim it.

Removing a domain

On the tenant's page, Domains, choose Remove next to the domain (or on the domain's own page) and type its name to confirm. Every mailbox on it is deleted, with its mail, and its aliases, mailing lists, rooms, DKIM keys and settings are removed:

• after the platform's deletion grace period (see Deleting accounts). Until then the domain and its mailboxes work as before, the list shows when it goes, and Keep the domain cancels the removal and the mailboxes' deletion. Restoring one of its mailboxes keeps the domain too;
• at once with now=true on the command line or API (corpsuite domain remove TENANT DOMAIN confirm=DOMAIN now=true), when nothing can be restored.

Only staff and the tenant's owners remove domains, and an owner cannot remove the domain of their own mailbox. A mailbox on it under a legal hold stops the removal until the hold is lifted. DNS records published for the domain elsewhere (Route53, dnso.city) are left as they are: remove them there. The deleted mailboxes are listed under Deleted mailboxes.

Moving a domain to another tenant

A tenant's owners and admins can give a domain to another tenant, which has to accept it:

1. On the domain's page, under Move to another tenant, type the address of an owner or admin on the receiving tenant and choose Offer the domain (corpsuite domain transfer TEAM DOMAIN to=ADDRESS).
2. The receiving tenant's owners and admins get an email; the offer is on their tenant page under Domains offered between tenants, where they Accept or Decline it within 14 days. The giving tenant can Withdraw it.

The domain moves with its settings, DKIM keys, BIMI logo and DMARC reports; its DNS records stay as they are. It can move only when:

• both tenants are in good standing: active, approved, and with no mailbox whose sending is paused;
• nothing uses it: move or remove its mailboxes and aliases first;
• the receiving tenant has room in its plan's domain limit.

The platform's staff can move a domain at once, without the receiving tenant accepting (Move it now on the domain's page; corpsuite domain move TEAM DOMAIN toTenantId=ID), with the same checks.

Letting people join

Under Joining the tenant:

1. Pick the domain new members' addresses go on (New members' addresses are on). Until one is picked nobody can join.
2. Either give out invitation links, or tick Anyone with the join page link can join. Open joining needs the Team signup feature in the plan (team_signup); links work without it.

The join page is /join/{team} (on the signup host when there is one). People choose their address and password there and become members of the tenant, within its seats. While single sign-on is on, they Continue with Zappocity first (signing in at zappo.city, or creating their account there) and choose only their address: the mailbox has no password of its own and signs in through their Zappocity account. The platform's reserved names (such as postmaster@) are refused, and the platform's limit on signups per network applies.

Invitation links (New link) are for one person by default, or up to 1000, for 14 days by default, or up to a year. The list shows how often each was used and by whom it was made; Revoke stops one at once.

Welcome message

Tick Send new members a welcome message and write a subject and text. {name}, {address} and {webmail} are filled in. It goes to people who join on the join page and to mailboxes added in the panel or through the API, from the platform's notice address, and replaces the platform's own welcome message for the tenant.

The tenant's pages

Page title, Page message and Colour brand the join page and webmail's sign-in when it is opened as /mail?team={team} (the join page links there). The colour is a hex value such as #1a73e8 and colours the main button. Tenants with no title, message or colour, closed signup and no valid link have no public page at all.

API keys

On plans with API access (api_access), API keys → New key makes a key for the tenant's own scripts. It is shown once; only a hash is kept. Scripts send it as Authorization: Bearer cs_tk_... to the same /v1 routes the panel uses, for this tenant only and with an admin's rights: a key can never change an owner, and cannot make or revoke keys. Revoke stops a key at once, and a suspended tenant's keys stop working. A tenant can have 20.

Opening a mailbox for support

An owner chooses who may open webmail as the tenant's mailboxes: nobody, the platform's support staff, or also the tenant's own owners and admins. See Staff permissions and impersonation.

Sessions

The panel accepts a webmail session for 12 hours from signing in and one hour unused, like the operator's panel; after that it asks to sign in again, while webmail itself keeps working. A suspended account, or a role changed to member, stops working in the panel at once. Every change is written to the service log as an admin: team admin ... line.

For developers

The panel calls the /v1 routes marked x-team: true in api/openapi.yaml, with the webmail session cookie and its X-CSRF-Token. Webmail's GET /api/mail/session includes tenantId and teamRole for those who may use the panel. Domains are proved with POST /v1/tenants/{tenantId}/pending-domains and .../{domain}/verify; the command line has domain request, domain verify, domain pending and domain withdraw. Tenant settings, links and keys are /team-settings, /team-invites and /api-keys under the tenant (corpsuite tenant team, tenant invites, tenant keys), and the public join page uses /api/join/{slug} (see api/signup.yaml).