Mailspace mailboxes
Mailspace is the plan: you buy it for a domain and resize or cancel it. This page covers everything inside one mailspace — the mailboxes, each mailbox's app passwords and filter rules, and its out-of-office reply and forwarding.
Every route is nested under one mailspace, so the mailspace GUID is always the
first path segment. Get it from GET /api/mailspace.
Mailboxes are addressed by their GUID (.../mailboxes/9f3c…), never by email
address. The same GUID is the mailbox_id segment for
app passwords, mail rules,
out-of-office replies and forwarding.
App passwords are the exception: their :id is the credential id (a String).
OAuth scopes: reads need mailspace:read, writes need mailspace:write — the
same scopes as the plan-level endpoints. Session and API-key credentials skip
scope checks (see OAuth).
There is no step-up authentication on this API, and no endpoint on this page accepts the caller's own password in the request body.
Request Guards
Every endpoint on this page runs these checks, in this order. The first one that fails answers the request.
| Applies to | Condition | Response |
|---|---|---|
| all | the mail server is not configured on the platform | 503 stalwart_unavailable |
| all | mailspace GUID unknown, or not visible to your credential | 404, empty body |
| writes only | your user has no edit permission on the workspace that owns the mailspace | 403 not_authorized |
| all, reads included | the mailspace is bound to a different mail server than the one now configured | 503 mailspace_server_mismatch |
| all, reads included | the mailspace is on a staff block or an unpaid-invoice hold | 403 mailspace_suspended |
| writes only | the mailspace is scheduled for deletion | 403 pending_delete |
| all | the mailspace has no mail-server tenant yet | 409 not_provisioned |
Beyond the table:
- Unknown mailbox. Any endpoint that names a mailbox answers
404unknown_mailboxwhen it is not in this mailspace, so a GUID from another workspace is a404, not a403. The app-password, mail-rule, out-of-office and forwarding endpoints give the same404for a mailbox scheduled for deletion. Restore it first. - Writes are gated by HTTP verb. Everything except
GETandHEADis a write, includingrestore,force_delete,toggle,moveandadopt. A view-only member with amailspace:writetoken gets403not_authorizedon all of them. AHEADrequest answers the same status as the matchingGET. The permission is checked against the workspace that owns the mailspace, not the one inX-Auth-Account. - Retention window. After you delete a mailspace, reads keep working for the
whole retention window and every write answers
403pending_delete. Restore the mailspace to write again. A mailspace that is both on hold and pending deletion answerspending_deleteto a write and200to a read. - Differences from the plan-level endpoints.
pending_deleteis403here (422on Mailspace) andnot_provisionedis409(422there). A permission refusal here is{"errors":["Not Authorized"],"code":"not_authorized"}; the plan-level endpoints send nocode. Branch on the code, not the status alone.
Reads that can come back empty
- List Mailboxes is strict: if the mailboxes cannot be read it
answers
503mailboxes_unavailable, never an empty list. See Read failures. - View a Mailbox and List App Passwords
are tolerant: if the mail server cannot be reached they answer
200with empty values. Do not treat an empty result as proof, and do not delete anything based on it alone. - List Out-of-Office State and
List Forwarding answer from a cached summary. Check
synced, and read the single mailbox for live state.
List Mailboxes
GET /api/mailspace/:mailspace_id/mailboxes
Scope: mailspace:read.
Returns the mailspace's live mailboxes and, separately, those inside their
soft-delete grace window. A mailbox scheduled for deletion appears only in
pending, never in mailboxes.
This is a live read against the mail server, so it is slow. There is no
pagination, the result is capped at 500 mailboxes, and q filters within
that cap. The standard rate limit applies.
An empty mailboxes array is authoritative: the mail server was asked and holds
none. When the read fails, the whole response is the 503 error, so pending is
not returned alongside it. Retry.
Params
- q: String (optional) | case-insensitive substring match on the mailbox's primary address. Applies to
mailboxesonly —pendingis never filtered.
Returned Params
- mailboxes: Array | live mailboxes
- id: String | the mailbox GUID — the key for every other endpoint on this page
- email: String | the primary address
- display_name: String
- status: String |
activeorsuspended - quota_mb: Integer |
0means no per-mailbox cap; the mailbox is still bounded by the package's storage pool - used_mb: Integer | rounded up to the next whole megabyte
- aliases: Array |
Array<String>, the addresses after the primary one - stalwart_id: String | the mailbox's id on the mail server
- scheduled_deletion_at: DateTime |
nullon a live mailbox
- pending: Array | mailboxes inside their soft-delete grace window, oldest deletion date first
- id: String | the mailbox GUID
- email: String
- status: String | always
pending_deletionin this bucket - scheduled_deletion_at: DateTime
- days_until_deletion: Integer | never negative;
nullif no date is set
Purged mailboxes are not listed here. Use
GET /purged_mailboxes.
Errors
- 503
mailboxes_unavailable| the live mailbox read could not be performed. Retriable, and not an empty mailspace
Check an Address
GET /api/mailspace/:mailspace_id/mailboxes/check
Scope: mailspace:read. Read-only — nothing is reserved or created.
Asks whether an address is free before you create a mailbox on it. Addresses are unique across mailboxes, groups and mailing lists, including their aliases.
Params
- username: String (required) | the local part only —
sales, notsales@example.com - domain: String (optional) | defaults to the mailspace's own mail domain
Returned Params
- available: Boolean |
true,false, ornull— see the warning below - used_by: String |
"mailbox","group"or"mailing list", ornullwhen the address is free
available: null means could not verify
When the mail server is unreachable the endpoint still answers 200, with
available and used_by both null. Branch on available === false for
taken, never on !available, and treat null as "ask again". Even true is
advisory: the address can be taken before your create arrives.
Errors
- 400
invalid_address|usernameis blank
View a Mailbox
GET /api/mailspace/:mailspace_id/mailboxes/:id
Scope: mailspace:read. :id is the mailbox GUID.
The full detail payload.
Returned Params
- mailbox: Object
- all fields from List Mailboxes's
mailboxesentries, plus: - status: String | here also
pending_deletion— this endpoint reads a soft-deleted mailbox too, andscheduled_deletion_atis then set - allowed_ips: Array |
Array<String>, the addresses and CIDR ranges allowed to sign in with the mailbox's own password.[]means any address. App passwords carry their own lists - groups: Array |
Array<String>, group addresses this mailbox belongs to - lists: Array |
Array<String>, mailing-list addresses this mailbox is subscribed to - two_factor: Object
- enabled: Boolean
- app_passwords: Array | the same objects List App Passwords returns
- created_at: DateTime
- updated_at: DateTime
- all fields from List Mailboxes's
Unreadable fields look empty
If the mail server cannot be reached, allowed_ips, groups, lists,
app_passwords and aliases come back as [], two_factor.enabled as
false, display_name as "" and quota_mb / used_mb as 0, and the
response is still 200. An empty allowed_ips therefore does not tell you
whether any address may sign in. The same applies to the mailbox returned by
create and update. Do not base a security decision, or a deletion, on these
fields alone.
two_factor.enabled is a flag only: the secret is never returned and enrollment
is not part of this API. App-password secrets are also never returned (see
Mint an App Password).
Create a Mailbox
POST /api/mailspace/:mailspace_id/mailboxes
Scope: mailspace:write. Returns 201 Created.
Params
- username: String (required) | the local part. Combined with
domainto form the address - domain: String (optional) | defaults to the mailspace's own mail domain
- password: String (required) | the mailbox's sign-in password
- display_name: String (optional)
- quota_mb: Integer (optional) | per-mailbox cap in megabytes.
0(the default) means no cap — the mailbox is still bounded by the package's storage pool. A value larger than the whole package is refused - aliases: Array (optional) |
Array<String>of additional addresses - groups: Array (optional) |
Array<String>of group addresses in this mailspace. A foreign address is refused - lists: Array (optional) |
Array<String>of mailing-list addresses in this mailspace. A foreign address is refused
totp_secret and allowed_ips are not accepted on create. Set allowed_ips with
a follow-up update.
Returned Params (201 Created)
- mailbox: Object
- the
mailboxesfields from List Mailboxes, plus - created_at: DateTime
- updated_at: DateTime
- the
This is not the full View a Mailbox payload: read the
mailbox back for allowed_ips, groups, lists, two_factor and
app_passwords.
curl -X POST https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/mailboxes \
-H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"username": "sales", "password": "…", "display_name": "Sales", "quota_mb": 2048}'
Errors
- 400
username_blank|usernamemissing or blank - 400
password_blank|passwordmissing or blank. Checked afterusername_blank - 422
create_failed| the mailbox could not be created. Theerrorsmessage says why: the package's mailbox limit is reached,quota_mbis larger than the package, the address is already used by a mailbox, group or mailing list in this mailspace, agroupsorlistsentry is not in this mailspace, or the mail server refused the create
If a later step (aliases, groups or lists) fails, the mailbox still exists and
you get 422 create_failed. Read the mailbox back before retrying, then fix it
with an update.
Update a Mailbox
PATCH /api/mailspace/:mailspace_id/mailboxes/:id
Scope: mailspace:write.
Every field is optional, and an omitted field is left untouched. An empty value
clears a field: an empty aliases array removes every alias, an empty
allowed_ips clears the sign-in restriction.
Params
- display_name: String (optional)
- quota_mb: Integer (optional) | an empty string is treated as omitted, not as
0. Send the number0to remove the per-mailbox cap - status: String (optional) |
activeorsuspended.pending_deletionis refused on a mailbox that is not already pending deletion — use DELETE. Sending it for an already-scheduled mailbox changes nothing - password: String (optional) | blank or omitted keeps the current password
- aliases: Array (optional) |
Array<String>. Replaces the whole list - groups: Array (optional) |
Array<String>. Replaces the whole list. Every address must already exist in this mailspace - lists: Array (optional) |
Array<String>. Replaces the whole list. Every address must already exist in this mailspace - allowed_ips: Array or String (optional) |
Array<String>, or one String separated by commas, semicolons or whitespace. Replaces the whole list; at most 20 entries
Two checks run before anything is written, and when either fails nothing is written at all:
- A
groupsorlistsaddress that is not in this mailspace, or that cannot be verified, is refused with422update_failed. Read the mailbox back before retrying. - A bad
allowed_ipslist is refused with400invalid_allowed_ipsnaming the entry. Entries are normalized and de-duplicated, and a masked range is stored in its masked form (10.0.0.5/8becomes10.0.0.0/8). A restriction that does not match the client locks that credential out of webmail and every device.
Setting status back to active re-checks the package's mailbox limit, like
Restore a Mailbox, which is the preferred way to do it.
Returned Params
- mailbox: Object | identical to Create a Mailbox
allowed_ips is not in this response even when you set it. Read the
mailbox back to see the normalized list.
Errors
- 400
invalid_allowed_ips| an entry is not a valid address or range, or there are more than 20 - 422
update_failed| the mail server refused the change, agroups/listsaddress is not in this mailspace or could not be verified,status: "pending_deletion"was requested on a mailbox that was not already scheduled,quota_mbexceeds the package, or a reactivation would exceed the package's mailbox limit
Delete a Mailbox
DELETE /api/mailspace/:mailspace_id/mailboxes/:id
Scope: mailspace:write.
Soft delete. The mailbox is suspended immediately, so mail stops flowing, and it is permanently erased 7 days later. Until then restore brings it back with its mail intact. Deleting an already-scheduled mailbox succeeds and does not move the date.
Returned Params
- mailbox: Object | the same shape as the
pendingentries in List Mailboxes- id: String
- email: String
- status: String
- scheduled_deletion_at: DateTime
- days_until_deletion: Integer
Errors
- 422
delete_failed| the mail server refused the suspend
Restore a Mailbox
POST /api/mailspace/:mailspace_id/mailboxes/:id/restore
Scope: mailspace:write.
Reactivates the mailbox and clears its deletion date. Restoring an active mailbox succeeds and changes nothing.
The package's mailbox limit is re-checked, so after a downgrade a restore with no
room answers 422 restore_failed. Resize the mailspace up
first.
Returned Params
- mailbox: Object | the same shape as Delete a Mailbox;
scheduled_deletion_atanddays_until_deletionarenullafter a successful restore
Errors
- 422
restore_failed| the package's mailbox limit has no room for it, or the mail server refused the reactivation
Permanently Delete a Mailbox
DELETE /api/mailspace/:mailspace_id/mailboxes/:id/force_delete
Scope: mailspace:write.
Irreversible. Erases the mailbox's mail now instead of leaving it recoverable
for the rest of its grace window. The mailbox must already be scheduled for
deletion with DELETE .../mailboxes/:id; a live mailbox is
refused with 409 not_pending_deletion.
A 200 does not prove the mail is gone
If the mail server cannot erase the mail now, the call still answers 200.
The mail then stays on the server for the rest of its retention window and
appears in List Recoverable Mailboxes.
Do not rely on this call to free storage before a
downgrade; check the recoverable list.
Returned Params
- status: String |
"deleted" - email: String | the address that was deleted
Errors
- 409
not_pending_deletion| the mailbox is not scheduled for deletion - 422
delete_failed| the erase did not complete. Retry - 503
delete_unavailable| the account was removed and mail to the address has stopped, but CloudPress could not confirm whether the mail is still recoverable. The mailbox stays scheduled for deletion, and a retry is safe
App Passwords
An app password is a standalone IMAP/SMTP/JMAP credential for one mailbox. It
keeps working after the mailbox's own password changes, so it suits a device or
script. The :id segment on these endpoints is the credential id (a String), not
a GUID.
List App Passwords
GET /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords
Scope: mailspace:read.
Returned Params
- app_passwords: Array
- id: String | the credential id, used on update and revoke
- description: String |
nullfor a credential created without one - allowed_ips: Array |
Array<String>;[]means any address may authenticate with this credential - created_at: DateTime | may be
null
There is no last-used timestamp. The response never carries secret.
Mint an App Password
POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords
Scope: mailspace:write. Returns 201 Created.
Params
- description: String (required) | what the credential is for. It is the only way to tell two of them apart when revoking
The secret is returned exactly once, here
secret appears in this response and nowhere else. Store it on receipt; a
lost secret can only be revoked and replaced.
Returned Params (201 Created)
- app_password: Object
- id: String | the new credential id
- description: String | as submitted, trimmed
- allowed_ips: Array | always
[]on a mint — the credential is unrestricted. Pin it with Restrict an App Password - created_at: DateTime | always
nullon the mint response - secret: String | the only time this is returned
Errors
- 400
description_blank|descriptionmissing or blank - 422
app_password_create_failed| the mail server refused the mint
Restrict an App Password
PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords/:id
Scope: mailspace:write. :id is the credential id.
Pins one credential to a set of addresses. It never touches the mailbox's own sign-in password.
Params
- allowed_ips: Array or String (required) |
Array<String>, or one String separated by commas, semicolons or whitespace. At most 20 entries. Send an empty value to clear the restriction
allowed_ips is required. A request without the key is refused with 400
allowed_ips_missing and writes nothing, because an empty list means
unrestricted and "not supplied" must not silently unpin a credential. To
clear the restriction send [], "", null or allowed_ips[]=. The list
replaces, it does not append. A bad entry is a 400 invalid_allowed_ips with
nothing written, and entries are normalized as on the mailbox.
Returned Params
- app_password: Object
- id: String
- allowed_ips: Array |
Array<String>— a normalized echo of what was written, not a read-back
description and created_at are not included.
Errors
- 400
allowed_ips_missing| theallowed_ipskey was absent. Nothing was written - 400
invalid_allowed_ips| an entry is not a valid address or range, or there are more than 20. Nothing was written - 422
app_password_update_failed| the mail server refused the change. An unknown credential id lands here, not as a404
Revoke an App Password
DELETE /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords/:id
Scope: mailspace:write.
The credential stops authenticating immediately. The mailbox's own password and every other app password are untouched.
Returned Params
- status: String |
"revoked" - id: String | the credential id that was revoked
Errors
- 422
app_password_delete_failed| the mail server refused the revoke. An unknown credential id lands here, not as a404
Mail Rules
A mailbox's filter rules run top to bottom, so the order of the list is the
evaluation order, and stop_processing skips every rule below it.
Reordering changes behavior.
Rules, the out-of-office reply and forwarding all live in one filter script per mailbox. That has three consequences for every write on any of them:
- Every mutating response returns the whole rule list. Work from that list; a client that writes from a stale one deletes what it forgot. Concurrent writes on one mailbox are serialized for you.
- A script written outside CloudPress is never overwritten implicitly.
unmanaged: truemeans the script was hand-edited or written by another mail client. Every write is refused with409script_unmanageduntil you call Adopt a Filter Script. Check the flag from List Mail Rules before writing. It can also appear between your read and your write. - Script errors. Every rule and out-of-office endpoint except the out-of-office
list can answer
422mail_rules_unavailable(the script could not be read), and every write can answer422save_failed(the script could not be written). A failed write changes nothing.
An unrecognized match_type becomes all
match_type accepts all and any, lower-case. Anything else is not
rejected: it is replaced with all and the write succeeds, so a rule meant to
match any condition now needs every one. Read match_type back from the
response. A bad condition field or action type is refused with 400
invalid_rule.
Rule Vocabulary
A rule is match_type over a list of conditions, plus a list of actions.
Several values in one condition are OR'd together whatever match_type
says.
Condition fields and the comparators each accepts:
| field | comparators | notes |
|---|---|---|
from, to, cc, subject |
contains, not_contains, is, not_is, starts_with, ends_with, matches |
|
body |
contains, is |
|
header |
as from above |
also needs header_name |
size |
greater_than, less_than |
values must be whole numbers of bytes |
attachment |
has_any, has_type |
has_any needs no values |
Action types: move, copy, forward, mark_read, star,
add_label, discard, reject, keep, stop. move, copy, forward,
add_label and reject each need a value — a folder, an address, a label
or a rejection message. A forward value must be a valid email address. A rule
may have at most one forward action, and not together with discard.
While the mailbox's forwarding is on, a rule's forward action
has no effect.
Not everything readable is writable. This API writes only the fields
from, to, cc, subject, body and the actions move, forward,
mark_read, star, discard. A rule outside that subset is still listed and
still runs, with editable: false. It can be toggled, reordered or deleted,
but not rewritten; submitting one to create or update is refused with 422
unsupported_rule.
Rule names are required and capped at 200 characters.
List Mail Rules
GET /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules
Scope: mailspace:read.
Returned Params
- mailbox: Object
- id: String | the mailbox GUID
- email: String
- mail_rules: Array | in evaluation order
- id: String | the rule's own uuid
- name: String | may be empty on a rule written elsewhere
- display_name: String |
name, or"Untitled rule"when it is blank — what a UI should show - enabled: Boolean
- match_type: String |
all(every condition must match) orany - stop_processing: Boolean
- editable: Boolean |
falsewhen the rule uses Sieve this API does not write. It can still be toggled, reordered or deleted - conditions: Array
- field: String
- comparator: String
- values: Array |
Array<String>, OR'd together - header_name: String |
nullunlessfieldisheader
- actions: Array
- type: String
- value: String |
nullfor the actions that take no value
- unmanaged: Boolean |
truemeans the script was written outside CloudPress and every write is refused until it is adopted
Create a Mail Rule
POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules
Scope: mailspace:write. Returns 201 Created.
The new rule is appended to the end of the list. To place it elsewhere, move it.
Params
- name: String (required) | at most 200 characters
- enabled: Boolean (optional) | defaults to
true - match_type: String (optional) |
all(default) orany. Any other value is silently changed toall - stop_processing: Boolean (optional) | defaults to
false - conditions: Array (optional) | objects of
field,comparator,values(Array<String>) andheader_name. A single value may be sent asvalueinstead ofvalues— it is taken whole, not comma-split - actions: Array (optional) | objects of
typeandvalue
Other keys are dropped. A rule needs at least one condition and one action.
Returned Params (201 Created)
- mail_rule: Object | the created rule, in the List Mail Rules shape
- mail_rules: Array | the whole new list, in evaluation order
- unmanaged: Boolean | always
falseafter a successful write
Errors
- 400
invalid_rule| a conditionfieldor an actiontypeis not in the vocabulary - 409
script_unmanaged| the script was written outside CloudPress — adopt it first - 422
invalid_rule| the rule would match nothing: a blank or over-long name, no conditions, no actions, a condition with no value, a comparator that does not apply to the field, aheadercondition with noheader_name, a non-numericsize, or aforwardto a malformed address - 422
unsupported_rule| the combination cannot be written here — the response names the supported fields and actions - 422
forwarding_loop| aforwardaction points back at this mailbox (its address, an alias, or a+tagof either), or at a mailbox in this mailspace that forwards back here
Update a Mail Rule
PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id
Scope: mailspace:write. Note the segment is rule_id, not id.
Rewrites one rule in place, keeping its id and position. An omitted field keeps
its stored value, but sending conditions or actions replaces that whole
array.
Params
- The same fields as Create a Mail Rule, all optional
Returned Params
- mail_rule: Object | the updated rule
- mail_rules: Array | the whole list
- unmanaged: Boolean |
false
Errors
- The create errors, plus:
- 404
unknown_rule| no rule with that id in this mailbox's script - 409
rule_not_editable| the stored rule uses Sieve this API cannot rewrite. Toggle, reorder and delete still work on it - 422
invalid_rule| also raised when the stored rule has more than oneforwardaction, orforwardwithdiscard, even if you only sentname. Remove the extra action
Delete a Mail Rule
DELETE /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id
Scope: mailspace:write.
Removes one rule. Works on a rule that is not editable.
Returned Params
- deleted_rule_id: String
- mail_rules: Array | the remaining list
- unmanaged: Boolean |
false
Errors
- 404
unknown_rule| no rule with that id in this mailbox's script - 409
script_unmanaged| the script was written outside CloudPress — adopt it first
Enable or Disable a Mail Rule
PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id/toggle
Scope: mailspace:write.
A disabled rule keeps its place and settings but has no effect. Works on a rule
that is not editable.
Params
- enabled: Boolean (optional) | set the state explicitly
Omitting enabled flips the rule
With no enabled the endpoint toggles the current state, so a retried request
flips the rule back. Always send enabled explicitly.
Returned Params
- mail_rule: Object | the toggled rule
- mail_rules: Array | the whole list
- unmanaged: Boolean |
false
Errors
- Identical to Delete a Mail Rule, plus:
- 422
forwarding_loop| enabling a rule whoseforwardaction points back at this mailbox
Reorder a Mail Rule
PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id/move
Scope: mailspace:write.
Moves one rule one place up or down. To go further, repeat the call. Works on
a rule that is not editable.
Params
- direction: String (required) |
upordown
Returned Params
- mail_rule: Object | the moved rule
- mail_rules: Array | the whole list, in its new evaluation order
- unmanaged: Boolean |
false
Errors
- 400
invalid_direction|directionis missing or is notupordown. Checked before the script is read - 404
unknown_rule| no rule with that id in this mailbox's script - 409
script_unmanaged| the script was written outside CloudPress — adopt it first - 422
invalid_move| the rule is already first and was moved up, or already last and was moved down
Adopt a Filter Script
POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/adopt
Scope: mailspace:write. This is a collection route — there is no rule_id.
Takes over a filter script this API did not write, replacing it with the rules that could be parsed out of it. This also unblocks the out-of-office reply and forwarding writes.
Adopting is destructive and cannot be undone
Anything in the customer's own script that the rule model cannot represent
is gone afterwards. Call List Mail Rules first and show a
person what is about to be replaced. On an already-managed script it is a
harmless no-op and answers 200.
Returned Params
- adopted: Boolean |
true - mail_rules: Array | what the script holds now
- unmanaged: Boolean |
falsefrom here on
This endpoint never answers script_unmanaged.
Out-of-Office Replies
One reply per mailbox, stored in the same script as the
filter rules, so the script rules above (including
script_unmanaged and a single adoption) apply here.
There is no POST route: Set an Out-of-Office Reply
creates and edits. The route segment mailbox_id is the mailbox GUID.
List Out-of-Office State
GET /api/mailspace/:mailspace_id/vacation_responses
Scope: mailspace:read.
One row per mailbox, ordered by address. Mailboxes scheduled for deletion are omitted. Answers from a cached summary that is refreshed whenever the script is read or written through CloudPress, so a script changed elsewhere is stale here. For live state, use View an Out-of-Office Reply.
Returned Params
- vacation_responses: Array
- mailbox_id: String | the mailbox GUID
- email: String
- synced: Boolean |
falsemeans this mailbox has no cached summary at all - configured: Boolean | a reply exists
- enabled: Boolean | it is switched on
- from_date: String |
YYYY-MM-DD, ornullfor no start bound - to_date: String |
YYYY-MM-DD, ornullfor no end bound
Check synced before believing the row
With synced: false, configured and enabled are false and the dates
null — the same as a mailbox with no reply. Treat it as "unknown" and read
that mailbox's own reply. This list has no unmanaged flag; the per-mailbox
read does.
View an Out-of-Office Reply
GET /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id
Scope: mailspace:read. Read live from the mailbox's script.
Returned Params
- vacation_response: Object
- mailbox_id: String | the mailbox GUID
- email: String
- configured: Boolean | a reply exists
- enabled: Boolean | it is switched on
- subject: String |
nullwhenever it is blank - text_body: String |
nullwhen unset - html_body: String |
nullwhen unset. Clients that render HTML prefer this overtext_body - from_date: String |
YYYY-MM-DD, ornull - to_date: String |
YYYY-MM-DD, ornull
- unmanaged: Boolean |
truemeans the script was written outside CloudPress and writes are refused until it is adopted
A reply can be written and switched off, so configured and enabled are
separate. configured: false with null fields means there is no reply.
Set an Out-of-Office Reply
PATCH /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id
Scope: mailspace:write. An upsert — the same call creates and edits.
Every field is optional. Omitting a field keeps its stored value; send an empty
string to clear one. {"enabled": false} switches the reply off and leaves its
text alone.
Params
- enabled: Boolean (optional) | whether the reply goes out. Defaults to
truefor a mailbox that has no reply yet - subject: String (optional)
- text_body: String (optional)
- html_body: String (optional) | send
""to stop sending an HTML version - from_date: String (optional) |
YYYY-MM-DD. The reply only answers inside the window - to_date: String (optional) |
YYYY-MM-DD
Dates are whole days in ISO 8601; a datetime is trimmed to its date. Anything else
is a 400 invalid_date. Enabling a reply with no subject and no body is refused
with 422 vacation_body_required. Use DELETE to remove a reply.
Returned Params
- The same shape as View an Out-of-Office Reply, with
unmanagedalwaysfalseafter a successful write
Errors
- 400
invalid_date|from_dateorto_dateis not a valid date. Nothing was written - 409
script_unmanaged| the script was written outside CloudPress. Adopt it first; there is no separate adopt for the reply - 422
vacation_body_required| an enabled reply with no subject and no body
Remove an Out-of-Office Reply
DELETE /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id
Scope: mailspace:write.
Removes the reply and leaves the filter rules as they were. Removing a reply that
does not exist answers 200.
Returned Params
- The same shape as View an Out-of-Office Reply, with the reply now cleared —
configuredandenabledfalse, every other fieldnull
Errors
- 409
script_unmanaged| the script was written outside CloudPress — adopt it first
Forwarding
Send every message a mailbox receives on to one other address. Forwarding is
stored in the same script as the filter rules and
out-of-office reply, so script_unmanaged and
adopting a script apply here too. There is no POST
route: Set Forwarding creates and edits. The mailbox_id
segment is the mailbox GUID.
While forwarding is enabled, a rule's forward action on the same
mailbox has no effect. rule_forward_addresses lists those destinations.
Every forwarding endpoint except the list can also answer 409
mailbox_not_provisioned (the mailbox has no account on the mail server yet; do
not retry) and 503 forwarding_unavailable (the script could not be read).
List Forwarding
GET /api/mailspace/:mailspace_id/forwardings
Scope: mailspace:read.
One row per mailbox, ordered by address. Mailboxes scheduled for deletion are omitted. The list is cached, so a script changed outside CloudPress is out of date here. For live state, use View Forwarding.
Returned Params
- forwardings: Array
- mailbox_id: String | the mailbox GUID
- email: String
- synced: Boolean |
falsemeans this mailbox has no cached summary at all - configured: Boolean | a forwarding address is set
- enabled: Boolean | forwarding is switched on
- address: String | the destination, or
null - keep_copy: Boolean | whether the message also stays in this mailbox
With synced: false the other fields are null, meaning "unknown", not "no
forwarding". Read that mailbox's forwarding instead.
View Forwarding
GET /api/mailspace/:mailspace_id/forwardings/:mailbox_id
Scope: mailspace:read. Read live from the mailbox's script.
Returned Params
- forwarding: Object
- mailbox_id: String | the mailbox GUID
- email: String
- configured: Boolean | a forwarding address is set
- enabled: Boolean | forwarding is switched on
- address: String | the destination.
nullwhenconfiguredisfalse - keep_copy: Boolean |
falsemeans nothing is stored in the mailbox and its filter rules do not run
- rule_forward_addresses: Array |
Array<String>: addresses this mailbox's enabled rules forward to - unmanaged: Boolean |
truemeans writes are refused until the script is adopted
An address can be stored (configured: true) with forwarding switched off
(enabled: false).
Set Forwarding
PATCH /api/mailspace/:mailspace_id/forwardings/:mailbox_id
Scope: mailspace:write. Creates or edits forwarding. Every field is optional;
an omitted field keeps its stored value, so {"enabled": false} switches
forwarding off and keeps the address.
Params
- enabled: Boolean (optional) | whether mail is sent on. Defaults to
truefor a mailbox with no forwarding yet - address: String (optional) | the destination email address.
""removes forwarding, likeDELETE - keep_copy: Boolean (optional) | whether the message also stays in this mailbox. Defaults to
true
Returned Params
- The same shape as View Forwarding, with
unmanagedalwaysfalseafter a successful write
Errors
- 409
script_unmanaged| the script was written outside CloudPress — adopt it first - 422
invalid_address|addressis not a valid email address - 422
forwarding_loop| the address is this mailbox, one of its aliases or a+tagof either, or an enabled forward would loop back through another mailbox in this mailspace - 422
save_failed| the script could not be written
Remove Forwarding
DELETE /api/mailspace/:mailspace_id/forwardings/:mailbox_id
Scope: mailspace:write.
Removes forwarding only; filter rules and the out-of-office reply are untouched.
Removing forwarding that is not set answers 200.
Returned Params
- The same shape as View Forwarding, with forwarding now cleared —
configured,enabledandkeep_copyfalse,addressnull
Errors
- 409
script_unmanaged| the script was written outside CloudPress — adopt it first - 422
save_failed| the script could not be written
Error Codes
All errors use the {"errors": [...], "code": "..."} envelope in
Error Responses, except an unknown or invisible
mailspace GUID, which answers a bare 404 with an empty body. The codes shared by
every endpoint are in Request Guards.
| Code | Status | Raised by |
|---|---|---|
unknown_mailbox |
404 | every endpoint that names a mailbox |
invalid_address |
400 / 422 | mailbox check (400); forwarding update (422) |
username_blank |
400 | mailbox create |
password_blank |
400 | mailbox create |
invalid_allowed_ips |
400 | mailbox update, app-password update |
allowed_ips_missing |
400 | app-password update — the key was not sent at all |
create_failed |
422 | mailbox create |
update_failed |
422 | mailbox update |
delete_failed |
422 | mailbox delete, mailbox force_delete |
delete_unavailable |
503 | mailbox force_delete — the removal went through, the recoverability record did not |
mailboxes_unavailable |
503 | list mailboxes — the live read could not be performed. Not an empty mailspace |
restore_failed |
422 | mailbox restore |
not_pending_deletion |
409 | mailbox force_delete |
description_blank |
400 | app-password create |
app_password_create_failed |
422 | app-password create |
app_password_update_failed |
422 | app-password update |
app_password_delete_failed |
422 | app-password revoke |
invalid_rule |
400 / 422 | mail-rule create, update — 400 for an unknown field or action, 422 for a rule that would match nothing |
unsupported_rule |
422 | mail-rule create, update |
rule_not_editable |
409 | mail-rule update |
unknown_rule |
404 | mail-rule update, delete, toggle, move |
invalid_direction |
400 | mail-rule move |
invalid_move |
422 | mail-rule move |
script_unmanaged |
409 | every mail-rule write except adopt; out-of-office and forwarding update, delete |
mail_rules_unavailable |
422 | every mail-rule and out-of-office endpoint except the out-of-office list |
save_failed |
422 | every mail-rule, out-of-office and forwarding write |
forwarding_loop |
422 | forwarding update; mail-rule create, update, toggle |
forwarding_unavailable |
503 | every forwarding endpoint except the list |
mailbox_not_provisioned |
409 | every forwarding endpoint except the list |
invalid_date |
400 | out-of-office update |
vacation_body_required |
422 | out-of-office update |
Error messages are always English, even with an Accept-Language header —
branch on code, not the message.