Mail

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.

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 "$OPENSHIP_URL/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 "$OPENSHIP_URL/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 "$OPENSHIP_URL/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 "$OPENSHIP_URL/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 "$OPENSHIP_URL/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", "serverId": "srv_managed" } — on a selected managed Openship Cloud server.

Both targets need a real server ID. Use GET /api/system/servers/destinations to list accessible servers. For a Cloud server that is not connected to this installation yet, use POST /api/system/servers/managed/connect and pass its returned local serverId here. The dashboard uses the same connection flow. A missing Cloud destination is refused before creating a webmail project. Redeploying an existing managed webmail preserves its server binding; moving it to another server requires the normal project migration flow.

curl -X POST "$OPENSHIP_URL/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"}}'

Reconnecting an existing webmail

Forgetting and re-adopting a mail server can leave its catalog webmail running with a missing control-plane link. mail.getStatus({ serverId }) returns webmailRecoveryCandidates for accessible, unlinked catalog apps on that mail server which already route its mail.<domain> hostname. Reading status grants no routing rights.

Choose the existing app in Emails → Deploy webmail, then press Reconnect and deploy. With the SDK, pass its projectId as reconnectProjectId to mail.deployWebmail(input); the CLI accepts the same input through mail webmail deploy reconnect.json. Keep the app's existing server and mail hostname for this recovery. It reuses the project, service, generated credentials and persistent volumes, and restores the link before queuing deployment. The mail certificate record stays owned by the mail service.

An omitted selection returns WEBMAIL_RECONNECT_REQUIRED when a recoverable app exists. WEBMAIL_LINK_CHANGED means another operation changed the link; refresh status and review the current app before retrying. A project from another organization, another mail server's linked app, or a different destination cannot be adopted through this path.

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

Operations

SDK and CLI

The remote SDK exposes client.mail; its methods below cover setup, health and administration through the same server permissions as the dashboard. Certificate renewal uses the existing edge pipeline.

const certificate = await client.mail.getCertificate("srv_mail");
await client.mail.updateCertificate("srv_mail", { autoRenew: true });
const domains = await client.mail.listDomains("srv_mail");
const mailboxes = await client.mail.listMailboxes("srv_mail", { domain: "example.com" });

client.mail.setup(input) returns the existing event stream. Observe its completion or DNS/PTR checkpoint before continuing. The CLI supplies mail setup, mail domain, mail mailbox, mail alias, mail relay, mail certificate, mail backup, mail inbound, mail component and mail webmail. Use --schema for JSON configuration commands. Mail is a remote, self-hosted feature.