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:
- Mailspace mailboxes — mailboxes, app passwords, filter rules, out-of-office replies, forwarding
- Mailspace addresses — aliases, groups, mailing lists, masked emails
- Mailspace domains — extra domains, their DNS records, and domain verification
- Mailspace logs & recovery — delivery logs, deleted-mail archive, mailbox recovery
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
200list 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
200with 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_passwordsandGET .../masked_emails.GET .../groups/:stalwart_idandGET .../mailing_lists/:stalwart_idanswer404instead, so a single404there does not prove the group or list is gone; check the index. - Deleted-mail archive:
GET .../archived_itemsanswers200with an empty list when the archive feature is unavailable, so "nothing archived" and "unavailable" look the same. - Groups have two codes.
groups_unavailablemeans the group list could not be read.group_members_unavailablemeans the groups came back but the member counts did not. It also appears onGET .../groups/:stalwart_id, and onPATCH .../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_idalways answers404with an empty body.- Two endpoints use a different status: the mail-rule and out-of-office
endpoints answer
422mail_rules_unavailablewhen a mailbox's filter script cannot be read back (see Mailspace mailboxes), and downloading an archived message answersdownload_unavailablewith404when the message is gone (stop) or503on 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_unavailablePOST,DELETE,GETand 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; a404means it went through.POST .../aliasesandDELETE .../aliases/:address→aliases_unavailable. The alias may have been created or removed. Re-readGET .../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, orinactive - 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,
nullwhile 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,
nullif never. Not a timestamp forused_mb/mailbox_count— see above - webmail_url: String | webmail entry point for the domain
- webmail_ready: Boolean | whether
webmail_urlworks 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_verificationis 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
- txt_prefix: String |
- 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 — sendX-Auth-Accountor use an account-scoped credential - 400
invalid_domain|domainmissing or not a plausible hostname - 400
unknown_product|packageis not one of the mail packages - 422
domain_not_registered| the domain is not registered anywhere, so mail for it could never work. Checked afterunknown_product, so a request that is wrong in both ways still answersunknown_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 aremediationstring alongsideerrorsandcode. - 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 a202, 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 (nocodekey), or no billing permission on the workspace being billed (codeisnot_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|packageis 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 a409instead - 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 |