Skip to content

Mailspace

Mailspace is workspace-level mailbox hosting: you buy it for a domain, and it provides the mailboxes, aliases and groups for that domain. These endpoints cover the mailspace itself — purchase, inspect, resize, delete and purge.

Everything inside a mailspace has its own reference page:

OAuth scopes: reads require mailspace:read, writes require mailspace:write. Session and API-key credentials bypass scope checks entirely (see OAuth).

Mailspace IDs are GUIDs. A mailspace that is not visible to your credential returns 404; a credential without edit permission on the owning account returns 403 {"errors":["Not Authorized"]}. Purchasing and resizing also charge the billing account, so they additionally need billing permission on the workspace being billed (403 not_authorized).

Mailspace is sold on an annual term only, so no endpoint on this page accepts a term parameter.

A 202 Accepted does not mean the charge succeeded

POST /api/mailspace and PATCH /api/mailspace/:id are asynchronous: they build a cart, charge the billing account off-session, and return 202 with the shared cart envelope.

A declined off-session charge is also a 202. The envelope then reports payment.status as "awaiting_authentication" and carries a payment.hosted_invoice_url the customer can pay through (this also covers 3DS/SCA). Branch on payment.status, never on the HTTP status alone.

On a billing plan that charges a saved card, the cart settles asynchronously as described above, and a saved default payment method is required (400 no_default_payment_method). On a plan billed externally (payment method "none"), no charge is attempted and that check is skipped; the response is still the same 202 envelope. Read payment (and, on a post-pay order, billing) in the response to see which path applied. See Orders and site plan changes.


Read failures

Listings inside a mailspace read the mail server live. If a read cannot be performed, the endpoint answers 503 with a code naming the read that failed, never 200 with an empty payload. These errors are transient: retry.

Endpoint Code
GET /api/mailspace/:mailspace_id/mailboxes mailboxes_unavailable
GET /api/mailspace/:mailspace_id/domains domains_unavailable
GET /api/mailspace/:mailspace_id/aliases aliases_unavailable
GET /api/mailspace/:mailspace_id/groups groups_unavailable
GET /api/mailspace/:mailspace_id/mailing_lists mailing_lists_unavailable
GET /api/mailspace/:mailspace_id/archived_items archived_items_unavailable
GET /api/mailspace/:mailspace_id/purged_mailboxes purged_mailboxes_unavailable

Rules that apply across the Mailspace endpoints:

  • A 200 list means the read happened, not that the list is complete. Principal listings (mailboxes, groups and so on) are capped at 500 rows and masked emails at 2000, with no total and no flag. The 500 is shared across mailboxes and groups, so a mailspace with 500 or more mailboxes can return zero groups.
  • Never delete your own records because a response omits them. This applies most to purged_mailboxes, where a listed snapshot is real but an empty list only means "nothing found", not "the mail is gone".
  • Some reads return 200 with an empty or partial payload when the mail server cannot be reached: delivery logs, mailbox detail (group and list memberships, app passwords, TOTP flag), GET .../app_passwords and GET .../masked_emails. GET .../groups/:stalwart_id and GET .../mailing_lists/:stalwart_id answer 404 instead, so a single 404 there does not prove the group or list is gone; check the index.
  • Deleted-mail archive: GET .../archived_items answers 200 with an empty list when the archive feature is unavailable, so "nothing archived" and "unavailable" look the same.
  • Groups have two codes. groups_unavailable means the group list could not be read. group_members_unavailable means the groups came back but the member counts did not. It also appears on GET .../groups/:stalwart_id, and on PATCH .../groups/:stalwart_id, where the update has already been applied: re-read the group instead of re-sending the change.
  • stalwart_unavailable (503) means mail hosting is not configured on the platform, or one individual read failed (for example the domain lookup on /api/mailspace/:mailspace_id/domains/:name; see Mailspace domains). It is retriable. An unknown or out-of-scope :mailspace_id always answers 404 with an empty body.
  • Two endpoints use a different status: the mail-rule and out-of-office endpoints answer 422 mail_rules_unavailable when a mailbox's filter script cannot be read back (see Mailspace mailboxes), and downloading an archived message answers download_unavailable with 404 when the message is gone (stop) or 503 on any other read failure (retry). See Mailspace logs & recovery.

Writes that return 503

On a write, check the code: some mean nothing was attempted, others mean the outcome is unknown.

Nothing was attempted. Retry:

  • PATCH .../purged_mailboxes/:guid → restore_unavailable
  • POST, DELETE, GET and the download on .../archived_items/:stalwart_id → archived_item_lookup_unavailable

The outcome is unknown. Re-read before retrying:

  • POST .../archived_items/:stalwart_id/restore → restore_unconfirmed. The restore may already be queued.
  • DELETE .../archived_items/:stalwart_id → delete_unconfirmed. The erase may already have happened and is irreversible. Read the item back; a 404 means it went through.
  • POST .../aliases and DELETE .../aliases/:address → aliases_unavailable. The alias may have been created or removed. Re-read GET .../aliases; repeating either write is safe.
  • DELETE .../mailboxes/:id/force_delete → delete_unavailable. The mailbox is already gone from the mail server, but its recoverability is unconfirmed. The mailbox still appears in the list and the cleanup retries.

A 422 means the mail server replied and refused. On the purged-mailbox restore, 409 not_recoverable means nothing can be done, 422 restore_failed means a retry may work, and 503 restore_unavailable means the check could not be made.


List Mailspaces

GET /api/mailspace

Returns the mailspaces newest-first. Soft-deleted (pending-deletion) mailspaces are included — they remain listed for their retention window; purged rows are gone. This endpoint is not paginated.

With the X-Auth-Account header the list is that account's mailspaces; without it, an account-less credential falls back to every mailspace the token's user can reach.

Returned Params
  • mailspaces: Array
    • id: String | GUID
    • domain: String | the mail domain, e.g. example.com
    • account_name: String | the mail account name stored on the record
    • package: String | mail Product short_name, e.g. mail_5
    • package_name: String | display name, e.g. Mailspace 5GB
    • status: String | pending, active, suspended, or inactive
    • storage_gb: Integer | storage included with the package
    • max_mailboxes: Integer | mailbox limit of the package
    • used_mb: Integer | last measured storage use, in MB
    • mailbox_count: Integer | mailboxes currently defined
    • provisioned: Boolean | the mail tenant exists and is ready to use
    • verified: Boolean | domain ownership has been confirmed
    • needs_domain_verification: Boolean | a DNS TXT record is still owed — see View a Mailspace
    • pending_deletion: Boolean | soft-deleted; restore or purge only
    • delete_scheduled_at: DateTime | frozen purge date, null while live
    • created_at: DateTime
    • updated_at: DateTime
    • account: Object
      • id: String
      • name: String

View a Mailspace

GET /api/mailspace/:id

Serialized from local state — no live call to the mail server, so used_mb and mailbox_count are whatever was last measured, not live figures.

synced_at does not timestamp the usage figures

synced_at is stamped when someone opens the mailspace in the dashboard — and it is stamped even if that page's usage read failed. used_mb and mailbox_count carry their own measurement time internally, which this API does not expose. So a workspace that only ever uses the API can see synced_at: null alongside perfectly current usage figures (a resize re-measures usage without touching synced_at), or a synced_at newer than the numbers beside it. Treat the two as unrelated.

Returned Params
  • mailspace: Object
    • all fields from List Mailspaces, plus:
    • synced_at: DateTime | when the mailspace was last opened in the dashboard, null if never. Not a timestamp for used_mb / mailbox_count — see above
    • webmail_url: String | webmail entry point for the domain
    • webmail_ready: Boolean | whether webmail_url works yet (it needs a live DNS record and a certificate). Branch on this, not on the URL being present
    • verification: Object | present only while needs_domain_verification is true
      • txt_prefix: String | _mailspace-verify
      • txt_host: String | the record host, e.g. _mailspace-verify.example.com
      • txt_value: String | the token to publish as the TXT value
    • subscription: Object | present only when a billing subscription is linked
      • id: String
      • status: String
      • created_at: DateTime
      • updated_at: DateTime
      • price: Object
        • amount_cents: Integer
        • term: String
    • account: Object
      • id: String
      • name: String

The verification block is the post-purchase to-do

For a domain the workspace does not already own, the mailspace is created in awaiting verification after payment settles. Poll this endpoint, publish the TXT record from the verification block, and the mailspace provisions itself on the next sweep. The block is gated on needs_domain_verification, so it disappears as soon as ownership is confirmed — before provisioned flips to true. Don't treat its absence as "the mailspace is ready"; check provisioned. For a domain the workspace already owns, verification is skipped and the block never appears at all.


Purchase a Mailspace

POST /api/mailspace

Builds a standalone mailspace cart and submits it. Returns 202 Accepted with the cart envelope — re-read the warning at the top of this page before handling the response.

An account context is required, because the purchase has to know what to bill: send the X-Auth-Account header or use an account-scoped credential.

The mailspace itself does not exist yet when the 202 is returned — it is created only after payment settles, so there is no mailspace ID in the response. Poll cart.poll_url until the cart completes, then find the new mailspace with GET /api/mailspace.

Params
  • domain: String (required) | the mail domain, lower-cased and trimmed for you. Must look like a real hostname and must be a domain that actually exists (registered with us or elsewhere).
  • package: String (optional) | mail Product short_name — mail_5, mail_20, mail_50, mail_200, mail_500. Defaults to the base (smallest) tier.
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "package": "mail_50"}' \
  https://my.cloudpress.com/api/mailspace
Returned Params (always 202 Accepted)

The shared cart envelope, identical to POST /api/orders:

  • status: String | "accepted"
  • cart: Object | { token, status, rollup_status, poll_url }
  • payment: Object | { status, method_type, hosted_invoice_url }
  • orders: Array | [{ id, status, poll_url }] (empty during the async window)
Errors
  • 503 stalwart_unavailable | mail hosting is not currently available
  • 400 account_required | no account context — send X-Auth-Account or use an account-scoped credential
  • 400 invalid_domain | domain missing or not a plausible hostname
  • 400 unknown_product | package is not one of the mail packages
  • 422 domain_not_registered | the domain is not registered anywhere, so mail for it could never work. Checked after unknown_product, so a request that is wrong in both ways still answers unknown_product.
  • 422 mailspace_exists | the domain already has a mailspace. Includes your own pending-deletion mailspace — the domain stays claimed for the whole retention window, so restore it instead of buying it again.
  • 400 no_default_payment_method | Stripe billing plans only: the billing account has no Stripe customer, no saved default payment method, or an incomplete billing contact. The body carries a remediation string alongside errors and code.
  • 403 not_authorized | the user cannot manage billing on the workspace being billed
  • 422 cart_item_rejected | the cart refused the mail item — most often mail pricing is not yet configured for the requested package
  • 422 cart_pay_failed | the cart was valid but the charge could not be initiated (a decline that was initiated is a 202, not this)

Checkout-lane refusals: 400 billing_details_incomplete; 403 billing_permission_required; 409 bank_transfer_in_progress, bank_transfer_busy, postpay_busy; 422 outstanding_balance_exceeded, in_flight_limit_exceeded, payer_in_dunning, recent_dispute, instant_payment_method_required, bank_transfer_refused, bank_transfer_failed, postpay_route_changed, postpay_pay_open_invoices, postpay_contact_support, postpay_payment_in_progress, postpay_failed. See Orders

No WordPress site is required

The in-cart rule that mail can only be added on top of WordPress or cPanel hosting does not apply here: this endpoint builds a dedicated mailspace cart, which satisfies that rule by construction. A mailspace can be bought standalone over the API, for any existing domain.


Resize a Mailspace

PATCH /api/mailspace/:id

Moves the mailspace to a different package. Like the purchase, this is cart-mediated and asynchronous — 202 Accepted with the same envelope, and the same payment.status caveat.

On a Stripe billing plan the change is prorated against the mailspace's existing subscription. On an externally-billed plan there is no Stripe charge; the new package is applied and billed outside the platform.

Current storage use is re-measured against the mail server on every resize — upgrades included, even though only a downgrade can be blocked by it — so a resize request is not instantaneous even before the charge.

Params
  • package: String (required) | the target mail Product short_name. Must differ from the current package.
Returned Params (always 202 Accepted)

The shared cart envelope — see Purchase a Mailspace.

Errors

Evaluated in this order:

  • 503 stalwart_unavailable | mail hosting is not currently available
  • 403 not_authorized | no edit permission on the owning workspace (no code key), or no billing permission on the workspace being billed (code is not_authorized)
  • 503 mailspace_server_mismatch | the mailspace belongs to a different mail server than the one currently configured; nothing is read or written. Contact support
  • 403 mailspace_suspended | the mailspace is on hold (staff block or an unpaid-invoice hold) and cannot be modified
  • 422 pending_delete | the mailspace is scheduled for deletion — restore it first
  • 400 unknown_product | package is not one of the mail packages
  • 422 package_unchanged | already on that package
  • 422 not_provisioned | the mailspace has not finished setting up yet
  • 422 resize_unavailable | Stripe billing plans only: the mailspace has no active billing subscription to prorate against
  • 422 downgrade_blocked | the target package is smaller than the mailspace's current mailbox count or stored mail. Delete mailboxes or free storage first.
  • 400 no_default_payment_method | Stripe billing plans only, as on purchase
  • 422 cart_item_rejected | the cart could not build the change
  • 422 cart_pay_failed | the prorated charge could not be initiated

The checkout-lane refusals listed under Purchase a Mailspace apply here too, plus 422 postpay_change_refused.


Delete a Mailspace

DELETE /api/mailspace/:id

What this does depends on whether the mailspace was ever provisioned — the two outcomes are materially different, and the endpoint gives you no way to ask for one or the other. Both return 200 with an empty body, so check provisioned on the mailspace before you call this if the difference matters.

Soft delete. The mailspace stops serving mail and enters a retention window; pending_deletion becomes true and delete_scheduled_at is the frozen purge date. It still appears in GET /api/mailspace. Billing is cancelled with a prorated early-cancellation credit. Purging it before the window runs out is Purge a Mailspace below; restoring it is not part of this API — use the dashboard.

Idempotent: deleting an already-pending-deletion mailspace succeeds and changes nothing.

Hard delete, and the full first term is credited back. A mailspace that is still awaiting domain verification has no mail server tenant to suspend and has used none of its prepaid term, so this cancels the purchase outright: the record is destroyed (it disappears from GET /api/mailspace; pending_deletion is never set, delete_scheduled_at is never assigned), the originating order is refunded in full and marked cancelled, and the subscription seat is removed.

Because the record is gone, the domain is released immediately — a re-purchase for the same domain succeeds rather than hitting mailspace_exists.

Runs synchronously in both cases.

curl -X DELETE \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID

A soft-deleted mailspace keeps its domain claimed

A provisioned mailspace holds its mail domain for the whole retention window. Purchasing a new mailspace for that domain in the meantime fails with 422 mailspace_exists — restore the existing one instead. This does not apply to the never-provisioned case above, where the record is destroyed and the domain frees up at once.

Errors
  • 503 stalwart_unavailable | mail hosting is not currently available
  • 503 mailspace_server_mismatch | the mailspace belongs to a different mail server than the one currently configured; nothing is changed. Contact support
  • 403 mailspace_suspended | the mailspace is on hold (staff block or an unpaid-invoice hold) and cannot be deleted
  • 422 delete_failed | the deletion could not be completed. On the never-provisioned path this also covers a failed credit — the refund could not be processed, so the mailspace is deliberately left intact rather than deleted unpaid. Retry.

Purge a Mailspace

POST /api/mailspace/:mailspace_id/purge

Permanently destroys a mailspace that is already soft-deleted, instead of waiting out its retention window. Returns 200.

Irreversible, and it takes the mail with it

The mail server tenant — every domain, mailbox and stored message — and the local record are destroyed, and the mail records CloudPress wrote into the customer's hosted DNS zone are removed. Nothing here is recoverable, and no task is created to follow: the work is done by the time you get the response.

There is no confirmation parameter. The only precondition is that the mailspace is already pending deletion.

Billing is untouched — it was already cancelled when the mailspace was soft-deleted, so purging early neither refunds nor charges anything.

Every purge is written to the platform audit log with the credential that made the call.

Returned Params
  • purged: Boolean | always true; a purge that removed nothing is a 409 instead
  • domain: String | the mail domain that was released, captured before the record was destroyed
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/purge

Purge a live mailspace and you get a 409

409 not_pending_deletion means nothing was purged and the mailspace is still there. It covers both a mailspace that was never deleted — call DELETE /api/mailspace/:id first — and the race where a restore lands between the check and the destroy.

Errors
  • 404 | the mailspace is not visible to your credential
  • 503 stalwart_unavailable | mail hosting is not currently available
  • 403 not_authorized | the credential has no edit permission on the owning workspace
  • 503 mailspace_server_mismatch | the mailspace belongs to a different mail server than the one currently configured. Contact support
  • 403 mailspace_suspended | the mailspace is live and on hold (staff block or unpaid-invoice hold)
  • 409 not_provisioned | the mailspace has no mail server tenant to destroy
  • 409 not_pending_deletion | the mailspace is not scheduled for deletion — see above
  • 422 purge_failed | the purge could not be completed; nothing was destroyed

Error Codes

All errors use the standard {"errors": [...], "code": "..."} envelope described in Error Responses.

The same code name, a different status, inside a mailspace

The endpoints on this page raise pending_delete and not_provisioned themselves, as 422. The nested endpoints — mailboxes, addresses, domains, logs — inherit them from a shared gate instead, which answers 403 for pending_delete and 409 for not_provisioned. A client that branches on the status rather than the code will read one of the two families wrong.

The edit-permission 403 on this page carries no code key at all ({"errors":["Not Authorized"]}); the nested gate emits not_authorized beside it. The billing-permission 403 on purchase and resize does carry not_authorized.

The nested endpoints, reads included, also answer mailspace_server_mismatch (503).

Code Status Raised by
stalwart_unavailable 503 create, update, destroy, purge
mailspace_server_mismatch 503 update, destroy, purge
account_required 400 create
invalid_domain 400 create
domain_not_registered 422 create
unknown_product 400 create, update
mailspace_exists 422 create
no_default_payment_method 400 create, update
cart_item_rejected 422 create, update
cart_pay_failed 422 create, update
mailspace_suspended 403 update, destroy, purge
pending_delete 422 update
package_unchanged 422 update
not_provisioned 422 update
resize_unavailable 422 update
downgrade_blocked 422 update
delete_failed 422 destroy
not_authorized 403 create, update (billing permission), purge
billing_details_incomplete 400 create, update
billing_permission_required 403 create, update
bank_transfer_in_progress, bank_transfer_busy, postpay_busy 409 create, update
outstanding_balance_exceeded, in_flight_limit_exceeded, payer_in_dunning, recent_dispute, instant_payment_method_required, bank_transfer_refused, bank_transfer_failed, postpay_route_changed, postpay_pay_open_invoices, postpay_contact_support, postpay_payment_in_progress, postpay_failed 422 create, update
postpay_change_refused, postpay_add_payment_method 422 update
not_provisioned 409 purge
not_pending_deletion 409 purge
purge_failed 422 purge