Mail API

The Mail API drives Openship's self-hosted email feature: it installs an iRedMail stack on one of your servers over SSH, tracks the wizard's progress, then exposes an admin panel for the running server — domains, mailboxes, stats, backups, DNS health, and per-component control — plus a one-click webmail deploy. In the dashboard this is the Emails page.

Endpoints

Setup wizard

Post-install

Admin — domains

Admin — mailboxes

Admin — stats, backups, DNS, components

Webmail

Start (or resume) setup

Kicks off the iRedMail install wizard against a server and streams progress as Server-Sent Events. The wizard is idempotent: re-POST with startStep to resume from where a previous run stopped (or was gated). Only one install may run per instance at a time.

POST /api/mail/setup

config is an optional IRedMailConfig:

curl -N -X POST https://your-host/api/mail/setup \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","domain":"example.com"}'

The stream emits step_start, log, and step_done events per step, plus these control events:

• dns_records / dns_pending — the DKIM step publishes the records you must add, then holds. Add the records at your DNS provider and call POST /api/mail/setup/dns-ack, then re-POST /setup with the resumeStep from the event.
• ptr_pending — after DNS is acknowledged, the wizard holds again for reverse-DNS (PTR). Set the PTR record at your VPS provider, call POST /api/mail/setup/ptr-ack, and resume.
• complete — carries domain, webmailUrl, and adminUrl.
• error — carries message and (when resumable) resumeStep.

The terminal verify_reachability step reads the target's TCP listener table and then connects from the API host to the public-DNS address on 25, 465, 587, and 993. Listener failures and off-box failures remain distinct in the result. A measured failure blocks completion and points at both the host firewall and the provider-level firewall/security group/security list/NSG; an unavailable probe is returned as a non-blocking warning rather than being invented as an outage.

GET /api/mail/health/:serverId reuses one public-port sweep for 60 seconds. Pass ?refreshReachability=1 after changing firewall rules to force an immediate recheck; concurrent requests are still coalesced into one bounded four-port probe.

Acknowledge DNS / PTR

Both flip a single flag in the on-server state file so the wizard can move past its gate on the next /setup POST. Both take the same body.

POST /api/mail/setup/dns-ack
POST /api/mail/setup/ptr-ack

The same { serverId } body applies to POST /api/mail/scan, POST /api/mail/adopt, POST /api/mail/setup/cancel, and POST /api/mail/setup/reset.

Adopt an existing install

If Openship lost its record of a mail server (rebuilt desktop, wiped DB), scan the server, then adopt it — no reinstall, nothing changes on the box.

POST /api/mail/scan
POST /api/mail/adopt

# 1. Probe for iRedMail + its on-server state
curl -X POST https://your-host/api/mail/scan \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123"}'

# 2. Re-adopt it (idempotent)
curl -X POST https://your-host/api/mail/adopt \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123"}'

Rotate the postmaster password

POST /api/mail/credentials/postmaster

Add a mail domain

POST /api/mail/admin/:serverId/domains

PATCH /api/mail/admin/:serverId/domains/:domain accepts the same fields (all optional) plus active (boolean).

curl -X POST https://your-host/api/mail/admin/srv_123/domains \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","defaultQuotaMB":2048}'

Create a mailbox

POST /api/mail/admin/:serverId/mailboxes

PATCH /api/mail/admin/:serverId/mailboxes/:email accepts name, password, quotaMB, and active (all optional). DELETE soft-deletes by default; add ?hard=true to purge the maildir.

curl -X POST https://your-host/api/mail/admin/srv_123/mailboxes \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"alice","domain":"example.com","password":"a-strong-password"}'

Configure backups

Plugs the mail server into the general backup system — pick a destination and what to capture. Requires an existing backup destination in your organization.

POST /api/mail/admin/:serverId/backup-policy

Send a test email

POST /api/mail/admin/:serverId/test-email

Deploy webmail

Installs the webmail app from the app catalog, pointed at this mail server's IMAP/SMTP, then queues a deployment and starts it. Returns { deploymentId, projectId } so the dashboard can redirect to /build/[deploymentId]. Re-deploying an existing webmail reuses its project (and its stored sessions).

The IMAP/SMTP backend is derived from the mail server — mail.<domain> on 993/465 — so there is nothing to configure here. To point a webmail at a mailbox host you run elsewhere, install the webmail app from /apps (or use POST /api/mail/webmail/deploy-external) instead.

POST /api/mail/webmail/deploy-project

target is one of:

• { "kind": "self", "serverId": "srv_123" } — self-hosted on one of your Openship servers.
• { "kind": "cloud" } — managed by Openship Cloud.

curl -X POST https://your-host/api/mail/webmail/deploy-project \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mailServerId":"srv_123","hostname":"mail.example.com","target":{"kind":"self","serverId":"srv_123"}}'

Replacing a pre-catalog webmail

Openship 0.6.1 and earlier shipped webmail as a prebuilt bundle rather than an image. Those installs can't be redeployed — they have to be replaced by the catalog app. GET /api/mail/status reports one as webmail.legacy: true, and a deploy over it is refused with 409 and "code": "LEGACY_WEBMAIL" until you retry the same request with replaceLegacy: true.

The replace tears the old project down — container, routes, host state directory, project row — and then installs the webmail app at the same hostname. Mailboxes, mail data and every message live on the mail server and are untouched; the old webmail's sign-in sessions and per-user settings are not, so everyone signs in again. If the old install can't be removed, nothing is installed and the existing webmail keeps running.

Errors you might see