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.

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

Creates (or reuses) a webmail-<serverId> project, queues a deployment, and starts the build. Returns { deploymentId, projectId } so the dashboard can redirect to /build/[deploymentId].

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"}}'

Errors you might see