Skip to content

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 404 unknown_mailbox when it is not in this mailspace, so a GUID from another workspace is a 404, not a 403. The app-password, mail-rule, out-of-office and forwarding endpoints give the same 404 for a mailbox scheduled for deletion. Restore it first.
  • Writes are gated by HTTP verb. Everything except GET and HEAD is a write, including restore, force_delete, toggle, move and adopt. A view-only member with a mailspace:write token gets 403 not_authorized on all of them. A HEAD request answers the same status as the matching GET. The permission is checked against the workspace that owns the mailspace, not the one in X-Auth-Account.
  • Retention window. After you delete a mailspace, reads keep working for the whole retention window and every write answers 403 pending_delete. Restore the mailspace to write again. A mailspace that is both on hold and pending deletion answers pending_delete to a write and 200 to a read.
  • Differences from the plan-level endpoints. pending_delete is 403 here (422 on Mailspace) and not_provisioned is 409 (422 there). A permission refusal here is {"errors":["Not Authorized"],"code":"not_authorized"}; the plan-level endpoints send no code. Branch on the code, not the status alone.

Reads that can come back empty


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 mailboxes only — pending is 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 | active or suspended
    • quota_mb: Integer | 0 means 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 | null on 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_deletion in this bucket
    • scheduled_deletion_at: DateTime
    • days_until_deletion: Integer | never negative; null if 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, not sales@example.com
  • domain: String (optional) | defaults to the mailspace's own mail domain
Returned Params
  • available: Boolean | true, false, or null — see the warning below
  • used_by: String | "mailbox", "group" or "mailing list", or null when 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 | username is 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 mailboxes entries, plus:
    • status: String | here also pending_deletion — this endpoint reads a soft-deleted mailbox too, and scheduled_deletion_at is 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

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 domain to 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 mailboxes fields from List Mailboxes, plus
    • created_at: DateTime
    • updated_at: DateTime

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 | username missing or blank
  • 400 password_blank | password missing or blank. Checked after username_blank
  • 422 create_failed | the mailbox could not be created. The errors message says why: the package's mailbox limit is reached, quota_mb is larger than the package, the address is already used by a mailbox, group or mailing list in this mailspace, a groups or lists entry 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 number 0 to remove the per-mailbox cap
  • status: String (optional) | active or suspended. pending_deletion is 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 groups or lists address that is not in this mailspace, or that cannot be verified, is refused with 422 update_failed. Read the mailbox back before retrying.
  • A bad allowed_ips list is refused with 400 invalid_allowed_ips naming the entry. Entries are normalized and de-duplicated, and a masked range is stored in its masked form (10.0.0.5/8 becomes 10.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

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, a groups/lists address is not in this mailspace or could not be verified, status: "pending_deletion" was requested on a mailbox that was not already scheduled, quota_mb exceeds 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 pending entries 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_at and days_until_deletion are null after 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 | null for 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 null on the mint response
    • secret: String | the only time this is returned
Errors
  • 400 description_blank | description missing 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 | the allowed_ips key 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 a 404

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 a 404

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: true means the script was hand-edited or written by another mail client. Every write is refused with 409 script_unmanaged until 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 422 mail_rules_unavailable (the script could not be read), and every write can answer 422 save_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) or any
    • stop_processing: Boolean
    • editable: Boolean | false when 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 | null unless field is header
    • actions: Array
      • type: String
      • value: String | null for the actions that take no value
  • unmanaged: Boolean | true means 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) or any. Any other value is silently changed to all
  • stop_processing: Boolean (optional) | defaults to false
  • conditions: Array (optional) | objects of field, comparator, values (Array<String>) and header_name. A single value may be sent as value instead of values — it is taken whole, not comma-split
  • actions: Array (optional) | objects of type and value

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 false after a successful write
Errors
  • 400 invalid_rule | a condition field or an action type is 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, a header condition with no header_name, a non-numeric size, or a forward to a malformed address
  • 422 unsupported_rule | the combination cannot be written here — the response names the supported fields and actions
  • 422 forwarding_loop | a forward action points back at this mailbox (its address, an alias, or a +tag of 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
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 one forward action, or forward with discard, even if you only sent name. 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 whose forward action 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) | up or down
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 | direction is missing or is not up or down. 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 | false from 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 | false means 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, or null for no start bound
    • to_date: String | YYYY-MM-DD, or null for 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 | null whenever it is blank
    • text_body: String | null when unset
    • html_body: String | null when unset. Clients that render HTML prefer this over text_body
    • from_date: String | YYYY-MM-DD, or null
    • to_date: String | YYYY-MM-DD, or null
  • unmanaged: Boolean | true means 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 true for 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
Errors
  • 400 invalid_date | from_date or to_date is 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
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 | false means 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. null when configured is false
    • keep_copy: Boolean | false means 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 | true means 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 true for a mailbox with no forwarding yet
  • address: String (optional) | the destination email address. "" removes forwarding, like DELETE
  • keep_copy: Boolean (optional) | whether the message also stays in this mailbox. Defaults to true
Returned Params
  • The same shape as View Forwarding, with unmanaged always false after a successful write
Errors
  • 409 script_unmanaged | the script was written outside CloudPress — adopt it first
  • 422 invalid_address | address is not a valid email address
  • 422 forwarding_loop | the address is this mailbox, one of its aliases or a +tag of 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, enabled and keep_copy false, address null
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.