All help articles

The command line

Everything the admin API and the SaaS admin panel can change can also be changed from a shell on the server: tenants, domains, mailboxes, aliases, shared domains, plans, platform settings, DKIM keys, DMARC reports, filters, out-of-office replies, per-user limits, two-step sign-in resets, app passwords and panel administrators.

Running it

On a server installed with make install, use corpsuite as root:

sudo corpsuite help
sudo corpsuite mailbox show amy@example.com

corpsuite runs corpsuited as the service user with the service's settings, so it reaches the same database and key file. The server does not need to be running, and no platform key is needed. Anyone who can run it as root could read the database anyway.

sudo corpsuite logs shows the service log. It takes journalctl options, such as -f to follow or --since today.

In development, or wherever the CORPSUITE_* variables are already set, run corpsuited directly: corpsuited help.

From another machine, through the API

The same commands can run from your own computer, or any other machine, against a server's admin API. Copy the corpsuited binary there and tell it where the API is and where to find the platform API key:

export CORPSUITE_API_URL=https://admin.mailo.city
export CORPSUITE_API_KEY_FILE=~/.config/zappocity/platform-key
corpsuited tenant list
corpsuited user suspend amy@example.com

• The key file holds the platform API key printed by corpsuited gen-platform-key. Keep it readable only by you (chmod 600). CORPSUITE_API_KEY works too, and without either the command asks for the key.
• CORPSUITE_API_URL must start with https://, except for this machine (http://localhost:…), so the key never crosses a network in clear. Redirects are not followed, so the key goes only to the server named.
• Every command goes through the API, with the same checks as the panel and API clients. Mailboxes are still named by address; the command finds them through the tenants' account lists.
• Panel administrators (admin list, admin set, admin disable) are not part of the API, so those commands work only on the server.

How commands look

corpsuite tenant add slug=acme name="Acme Inc" seatLimit:=10 plan=team
corpsuite domain request acme name=acme.com   # then publish the TXT record
corpsuite domain verify acme acme.com
corpsuite domain dns acme acme.com format=zone > acme.com.zone
corpsuite mailbox add acme address=amy@acme.com displayName=Amy password=-
corpsuite mailbox limits set amy@acme.com sendPerHour:=50
corpsuite settings set hstsMaxAge:=31536000 hstsIncludeSubdomains:=true

• TENANT is a tenant's slug (such as acme) or its id.
• MAILBOX is the address the mailbox signs in with (user still works for mailbox).
• Fields are written name=value for text and name:=value for numbers, true, false, null, lists and objects, as in JSON.
• name=@file takes the text of a file, for example a filter script.
• name=- asks for the value without showing it, which is how to type a password. When the input is a pipe, one line is read from it instead.

Results are printed as JSON, so they can be piped to jq. Errors say what was wrong in the same words as the API, and exit with status 1.

The commands

Run corpsuite help for the full list, or corpsuite help user for one group. In short:

set-admin and disable-admin still work as the old names of admin set and admin disable.

zappocityd

When Zappocity runs apart from the mail server, zappocityd has three commands of its own; the operator commands above still go through corpsuited (or the API), which forwards platform calls to it.

zappocityd                 # serve the platform
zappocityd migrate         # apply the platform's migrations and exit
zappocityd copy-data postgres://.../corpsuite   # move the platform's data

copy-data copies the platform's tables from the database it shared with the mail server into its own (CORPSUITE_PLATFORM_DATABASE_URL). Stop the servers first and start this release's corpsuited once, so both sides have the same migrations. The new database must be unused: nobody signed up and nothing set up. Every table is counted and compared row by row before the copy is kept; if anything differs nothing is kept. The source is not changed, so you can go back to it.

Good to know

• On a machine without the server's key file (while setting up), commands work on the database, but nothing can be emailed: a reply to a ticket is saved and the command says the requester was not told. Run it on the server, or through the API from anywhere, to notify them.
• Commands go through the same checks as the API. A plan limit, a taken address or a bad value is refused here too.
• Changes are written to the service log as admin: command line ... lines, like changes made in the panel.
• Domains are proved before they are added: domain request returns a TXT record to publish, and domain verify adds the domain once that record is found. domain add TENANT name=DOMAIN skipProof:=true adds one at once without proof (logged); such a domain can still be claimed by whoever proves it, if nothing uses it. Turn the requirement off with settings set requireDomainProof:=false (see Tenant administration).
• mailbox password signs the mailbox out of their other sessions and mail apps, as a password change in webmail does.
• mailbox app-passwords shows only names and dates. App passwords cannot be read back, only revoked.
• Platform settings that the server caches, such as the webmail host name, take effect within 30 seconds.
• New DKIM keys need the key file the server uses (CORPSUITE_KEY_FILE). When it is missing, dkim add is refused, and new domains get their first key when the server next starts.