Provisioning mailboxes

Mailboxes, aliases, forwarding and quotas over the API.

A mailbox is a real account — IMAP, SMTP, webmail, mobile. Creating one over the API is how you onboard a customer's staff without anybody clicking through a dashboard.

Create one

curl -X POST "$MAILYTE_BASE/api/v1/email-accounts" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@yourdomain.com",
    "name": "Ada Lovelace",
    "password": "a-long-random-passphrase",
    "quota_mb": 5120
  }'

Requires mailboxes:write.

The domain must exist but does not need to be verified. You will usually want mailboxes in place before cutting MX over, not after — see Managing domains and DNS for why that ordering matters.

Passwords

Minimum twelve characters. Generate them; do not let a provisioning script invent a scheme.

If you set a forced password change, know what it governs: webmail and the mobile apps only. IMAP and SMTP clients have no way to present a change-password prompt, so they keep working with the old password until it is changed somewhere that can ask. Treating a forced change as a security boundary for those protocols is a mistake.

Provisioning is asynchronous

Creation returns immediately with a provisioning status. The mailbox is created on the mail server in the background and becomes usable when that completes — usually seconds.

curl "$MAILYTE_BASE/api/v1/email-accounts/{id}" \
  -H "Authorization: Bearer $MAILYTE_API_KEY"

If something stuck, retry rather than recreating:

curl -X POST "$MAILYTE_BASE/api/v1/email-accounts/{id}/retry-provisioning" \
  -H "Authorization: Bearer $MAILYTE_API_KEY"

Creating a second mailbox for the same address because the first "did not work" leaves you with two records and one mailbox, which is harder to unpick than the original problem.

Aliases

An additional address delivering into an existing mailbox.

curl -X POST "$MAILYTE_BASE/api/v1/email-accounts/{id}/aliases" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"alias": "sales@yourdomain.com"}'

Aliases receive only. They cannot be used as an SMTP login, and they are not a second identity for sending — for that you want a sender.

Forwarding rules

curl -X POST "$MAILYTE_BASE/api/v1/email-accounts/{id}/forwarding-rules" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"forward_to": "ada@elsewhere.com", "keep_copy": true}'

keep_copy decides whether the message also stays in the mailbox. Forwarding without keeping a copy means the mailbox is a pipe, and anything that goes wrong downstream loses the mail permanently.

Revoking access is not instant

Deleting or suspending a mailbox updates the record immediately, but Dovecot caches authentication results for up to an hour. Until that expires, an already-authenticated client can keep working.

If you are revoking access because of a compromise, flush the auth cache rather than assuming the API call was sufficient. This is the single most surprising thing about mailbox lifecycle here, and the one worth building into your offboarding runbook.

Mailbox contents are a different API

Reading mail, folders, drafts, scheduled send — everything the webmail does — is the Mailbox API, and it takes a mailbox token, not your organization key. That separation is the point: your organization key provisions mailboxes, and a mailbox token acts as one person inside one of them.

See Building on the Mailbox API.

SMTP or the API.