Skip to content

Mailspace logs & recovery

These endpoints answer "what happened to my mail?" and "can I get it back?" for one mailspace: the delivery logs, the archive of deleted messages that can still be restored, and mailboxes whose mail the mail server still holds after a permanent delete. Buying, resizing and deleting the mailspace itself is covered on Mailspace.

Every path on this page begins /api/mailspace/:mailspace_id/…, where :mailspace_id is the mailspace GUID from GET /api/mailspace.

OAuth scopes: reads require mailspace:read, writes require mailspace:write. Session and API-key credentials bypass scope checks entirely (see OAuth). A token that lacks the required scope is refused with 403 {"error":"insufficient_scope", ...} — the OAuth error envelope, not the {"errors":[...],"code":"..."} envelope used by every other failure on this page. See Scope Enforcement Errors.

Nothing on this page is paginated; page and per_page are ignored. Every call reads live from the mail server, so poll on a human timescale. The normal API rate limit applies.

An empty result is not evidence that nothing is wrong

Delivery tracing and deleted-mail archiving are not available on every deployment. Where one is unavailable, or the mail server cannot be reached, the delivery-log arrays and the archive listing come back as an empty list, not an error, and the response does not say why. Never show "no delivery problems" or "nothing to recover" from an empty response alone. Only the recoverable-mailbox listing answers 503 here; see Read failures.

Request Guards

Every endpoint on this page passes the same checks, in this order. The first one that fails answers the request.

Applies to Condition Response
all mail hosting is not configured on the platform 503 stalwart_unavailable
all :mailspace_id unknown, or not visible to your credential 404, empty body
writes user has no edit permission on the mailspace's own workspace 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 mailspace is on hold (staff block or unpaid-invoice hold) 403 mailspace_suspended
writes mailspace is soft-deleted (pending deletion) 403 pending_delete
all mailspace is not provisioned yet 409 not_provisioned
  • A write is any request that is not GET or HEAD. So Restore an Archived Item is a write, and Download an Archived Message is a read. A view-only member holding a mailspace:write token can read everything here but gets 403 not_authorized on every restore and delete.
  • A mailspace pending deletion still answers reads for its retention window; every write is refused with 403 pending_delete until it is restored. See Delete a Mailspace. A held mailspace (mailspace_suspended) blocks reads as well as writes.
  • An unknown or out-of-scope :mailspace_id answers 404 with an empty body, not the error envelope.

Delivery Logs

GET /api/mailspace/:mailspace_id/logs

Scope mailspace:read.

Recent mail for this mailspace, in four separate arrays: incoming and outgoing delivery traces, the live outbound queue, and issues — deliveries that failed or are still being retried.

This endpoint takes no parameters. It returns at most the 100 most recent entries per dataset (100 traces, split across incoming and outgoing; 100 queue entries; 100 issues). One call makes several round trips to the mail server, so do not poll it tightly.

The four arrays are not equally available

  • incoming / outgoing come from delivery tracing, which is not available on every deployment. Where it is unavailable, both arrays are always empty, however much mail flowed.
  • queue is available everywhere.
  • issues combines permanent failures (from the traces) and still-retrying messages (from the queue), so where tracing is unavailable, retrying messages still appear but completed bounces do not.

A populated queue with both trace arrays empty means tracing is unavailable, not that no mail moved. There is no flag that tells you; do not read empty trace arrays as "no mail problems".

Internal mail is listed twice

A message between two mailboxes in the same mailspace appears under both incoming and outgoing, with internal: true so you can badge it rather than double-count it.

Returned Params
  • incoming: Array<Object> | traces for mail delivered to this mailspace's mailboxes
  • outgoing: Array<Object> | traces for delivery attempts to other mail servers, plus every internal message
  • queue: Array<Object> | messages still sitting in the outbound queue
  • issues: Array<Object> | permanent failures (from traces) and still-retrying messages (from the queue)

Each entry in incoming and outgoing is a trace:

  • id: String | null — the mail server's trace id, passed straight through with no guard, so a trace the mail server recorded without one arrives as null. Do not key or de-duplicate the trace arrays on it unguarded — the non-null guarantee on queue and issues below does not extend here
  • timestamp: String | ISO 8601, as the mail server recorded it
  • from: String | the envelope sender, as the mail server recorded it
  • to: String | recipients as a comma-separated string, not an array. On mail from a sender outside this mailspace, co-recipients on domains this mailspace does not host are removed before you see it
  • subject: String | null if the mail server recorded none
  • size: Integer | null — bytes
  • direction: String | incoming or outgoing
  • internal: Boolean | true for mailbox-to-mailbox mail inside this mailspace (see above)
  • status: String | derived from the SMTP log: delivered, bounced, failed, retrying, or sending
  • events: Array<Object> | the SMTP log, in the order the mail server recorded it
    • name: String | the mail-server event name, e.g. delivery.attempt-start
    • timestamp: String | ISO 8601
    • key_values: Array<Object> | the event's detail fields, as a list rather than an object because the same key can legitimately repeat within one event
      • key: String
      • value: String, Integer or Boolean | passed through from the mail server

Each entry in queue and issues is a queued message:

  • id: String | the mail server's own queue id on a queue entry, and a stable synthetic trace-<…> id on an issue derived from a trace. Never null on these two arrays (unlike a trace's own id).
  • source: String | queue or trace — which dataset the entry came out of. Present on every entry of queue and issues; the trace arrays do not carry it
  • created_at: String | ISO 8601
  • return_path: String | the envelope sender. Empty means a null return path (<>): the message is a bounce notification
  • subject: String | null
  • size: Integer | null — bytes
  • flags: Array<String> | mail-server flags, e.g. dsnSent once a bounce notification has been sent
  • recipients: Array<Object>
    • address: String
    • status: String | Completed, TemporaryFailure or PermanentFailure; null while the recipient is still queued and nothing has been attempted
    • retry_due: String | null — ISO 8601, when the next attempt is due
    • retry_count: Integer | null
    • error: Object | null when the mail server reported no error detail for that recipient
      • type: String | null — the mail server's error type
      • response_code: Integer | null — the SMTP status code. Passed straight through, so a trace-derived issue carries whatever the SMTP log recorded and may hand back a String
      • response_enhanced: String | null — the enhanced status code, e.g. 5.1.1
      • response_hostname: String | null — the server that answered
      • message: String | null — the remote server's text
  • events: Array<Object> | the SMTP log in the same shape as a trace's. Empty for a live queue entry, which has no trace yet; populated only on an issue that came from a trace

Derive the message-level status yourself

A queued message has no top-level status. Derive it from recipients and flags:

  1. any recipient PermanentFailure → bounced if flags includes dsnSent, otherwise failed;
  2. else any recipient TemporaryFailure → retrying;
  3. else all recipients Completed → delivered;
  4. else → sending.

An issues entry has the queue shape but two possible sources

Check source ("queue" or "trace"; present on every queue and issues entry, absent on the trace arrays).

  • "trace" — a completed bounce or rejection. It is terminal and carries the full SMTP log in events. Its id is a stable synthetic trace-<…> value you may key on. recipients holds one entry whose address is the trace's whole comma-separated recipient string, with status PermanentFailure, retry_due, retry_count and error.type null. flags is ["dsnSent"] if a bounce notification was sent, otherwise [].
  • "queue" — a real queue entry still being retried, listed with only its failing recipients (a subset of the entry under queue). events is empty.

The two sources never double-count a message.

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

Deleted Mail Archive

Mail a user deleted that the mail server is still holding. An item stays until its archived_until deadline, then is purged for good. The retention window is server-wide and cannot be changed through the API.

An empty archive is not proof that nothing was deleted

List Archived Mail answers 200 with an empty archived_items array both when nothing is archived and when archiving is unavailable on the deployment (every by-id endpoint then answers 404 unknown_archived_item). Nothing in the response tells them apart. An unreachable mail server is different: it answers 503.

  • Item ids are opaque. Use the id from the list as the :stalwart_id segment; an id that does not belong to this mailspace answers 404 unknown_archived_item.
  • Branch on code, never on errors[0]. Archive failures carry an English sentence whatever Accept-Language you send, and its wording can change.

List Archived Mail

GET /api/mailspace/:mailspace_id/archived_items

Scope mailspace:read.

Every restorable deleted message across the mailspace's mailboxes, newest-archived first. Unpaginated: the list is capped at 500 items per mailbox, and anything past that is dropped without a marker.

Returned Params
  • archived_items: Array
    • id: String | the opaque item id — this is the :stalwart_id segment for every by-id endpoint below
    • type: String | the item variant. Email in practice; the mail server declares others but never writes them
    • status: String | archived, or requestRestore once a restore has been queued for it. The mail server omits the field while it holds its default, so it is filled in as archived
    • subject: String | null
    • from: String | null
    • size: Integer | null — bytes
    • received_at: String | null — ISO 8601, when the message originally arrived
    • archived_at: String | null — ISO 8601, when it was deleted into the archive
    • archived_until: String | null — ISO 8601, the permanent-deletion deadline. Server-wide retention, not per item
    • mailbox_email: String | the address the message was deleted from
    • mailbox_id: String | that mailbox's GUID

The item's mail-server blob and account handles are deliberately not emitted: both are global, unscoped handles, and the message itself comes back from Download an Archived Message.

Errors
  • 503 archived_items_unavailable | the archive query could not be performed. Not a client error, so it is retriable — see Read failures. An archive that is unavailable on the deployment still answers the empty 200 described above
  • plus the shared guards

View an Archived Item

GET /api/mailspace/:mailspace_id/archived_items/:stalwart_id

Scope mailspace:read. One item, in the same field set as the list, under an archived_item object.

The message body is not returned here — use Download an Archived Message for the original message.

Errors
  • 404 unknown_archived_item | no such item, or it does not belong to this mailspace
  • 503 archived_item_lookup_unavailable | the ownership lookup could not be performed, so the item is neither confirmed nor denied. Retriable, and not a sign the item is gone
  • plus the shared guards

Restore an Archived Item

POST /api/mailspace/:mailspace_id/archived_items/:stalwart_id/restore

Scope mailspace:write.

This reports a request, not a finished restore

The response says restore_queued and never restored; there is no completion signal to poll. To confirm, re-read the archive: a restored item is no longer listed, and the message returns to the mailbox under a new id.

Returned Params
  • status: String | always "restore_queued"
  • archived_item: Object | the item's fields, exactly as in the list

Two different status fields

The top-level status describes your request (restore_queued). The status inside archived_item is the item's own field, as it stood when the item was looked up — so a first restore shows archived here even though the request was accepted, and a second one on the same item shows requestRestore. Re-read the item rather than reading this field as the outcome.

Errors
  • 404 unknown_archived_item | no such item, or it does not belong to this mailspace. Also what you get if the item disappears between the lookup and the restore itself
  • 422 restore_failed | the mail server answered and refused the restore. Nothing was queued
  • 503 archived_item_lookup_unavailable | the ownership lookup could not be performed, so nothing was sent to the mail server. The item is untouched
  • 503 restore_unconfirmed | indeterminate. The restore instruction went out and its fate is unknown, so the restore may already be queued
  • plus the shared guards, including 403 not_authorized and 403 pending_delete

Two 503s that mean opposite things

archived_item_lookup_unavailable means nothing was attempted. restore_unconfirmed means the instruction went out and the outcome is unknown, so re-read the item or the archive before retrying. A vanished item answers 404 unknown_archived_item; restore_failed is only for a genuine refusal from the mail server.

Download an Archived Message

GET /api/mailspace/:mailspace_id/archived_items/:stalwart_id/download

Scope mailspace:read.

This endpoint does not return JSON on success

A successful download is the original RFC822 message as raw bytes (Content-Type: message/rfc822, attachment disposition). Failures are still JSON in the usual error envelope, so check the status before treating the body as a message.

The attachment filename comes from the message's stored subject, with characters other than letters, digits, underscores, spaces, hyphens and dots replaced by _, trimmed to 80 characters, plus .eml. A message with no usable subject is named after the item id.

curl -o message.eml \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/archived_items/$ITEM_ID/download
Errors
  • 404 unknown_archived_item | no such item, or it does not belong to this mailspace
  • 404 / 503 download_unavailable | the message could not be delivered, and the status is the difference: 404 when the mail server answered that the stored message is gone (terminal — stop), 503 for any other read failure (the message may still be there — retry). One code, because it is one fact about one resource; the status carries what to do next
  • 503 archived_item_lookup_unavailable | the ownership lookup could not be performed
  • plus the shared guards

Delete an Archived Item

DELETE /api/mailspace/:mailspace_id/archived_items/:stalwart_id

Scope mailspace:write.

Irreversible

This erases the archived message ahead of its retention deadline. Nothing is recoverable afterwards, and there is no confirmation parameter.

An item that is already gone answers 404 unknown_archived_item, so a repeated DELETE is not idempotent.

Returned Params
  • deleted: Boolean | always true
  • id: String | the item that was erased
  • subject: String | null — captured before the erase
Errors
  • 404 unknown_archived_item | no such item, or it does not belong to this mailspace. Also what you get if the item disappears between the lookup and the erase itself — see the note above
  • 422 delete_failed | the mail server answered and refused the erase. Nothing was destroyed
  • 503 archived_item_lookup_unavailable | the ownership lookup could not be performed, so nothing was sent. The item is untouched
  • 503 delete_unconfirmed | indeterminate, and this erase is irreversible: the item may already be gone
  • plus the shared guards

On delete_unconfirmed, read the item back first

The erase may already have happened and cannot be undone. GET the item: a 404 means it went through. Do not treat this as "the delete failed".


Purged Mailboxes

Mailboxes that were permanently deleted but whose mail the mail server is still holding until its retention window ends. Until then the mailbox can be brought back with its original id. They are not part of the mailspace's mailbox list, so they have their own endpoint.

List Recoverable Mailboxes

GET /api/mailspace/:mailspace_id/purged_mailboxes

Scope mailspace:read.

The purged mailboxes that can still be restored, ordered by recoverable_until so the one about to be lost comes first. Unpaginated. A record the mail server no longer holds is omitted.

A listed mailbox is real; an empty list is not proof the mail is gone

A mail server that cannot be asked answers 503 purged_mailboxes_unavailable, not an empty 200. But the list can still silently omit a recoverable mailbox on a busy server. Treat an empty list as "nothing found", and never drop your own last record of a mailbox because of it; keep it until the record's recoverable_until has passed.

Returned Params
  • purged_mailboxes: Array
    • id: String | the record's GUID — this is the :guid segment Restore a Purged Mailbox takes
    • email: String | the address that would come back
    • display_name: String | null
    • purged_at: DateTime | when CloudPress permanently deleted the mailbox
    • recoverable_until: DateTime | the mail server's own erase deadline, mirrored at delete time — never a locally computed window
    • days_remaining: Integer | whole days left, floored at 0

The stored quota, aliases, memberships and mail-server account id are deliberately not emitted: they are restore input, not a description of the deleted mailbox.

Errors
  • 503 purged_mailboxes_unavailable | the mail server could not be asked which accounts it is still holding, so the list cannot be answered. Retriable, and deliberately not an empty 200 — a client would read that as "nothing to recover"
  • plus the shared guards

Restore a Purged Mailbox

PATCH /api/mailspace/:mailspace_id/purged_mailboxes/:guid

Scope mailspace:write.

Cancels the pending erase and rebuilds the mailbox with its display name, stored quota and aliases. The quota is clamped down if the plan no longer has room, so the mailbox may come back slightly smaller.

password is required

A recovered mailbox comes back with no credentials, so you must set one. A missing or blank password is refused with 400 password_blank before anything is touched.

Params
  • password: String (required) | the password the restored mailbox comes back with. A blank or absent value is 400 password_blank

A 200 does not prove everything came back. Group and mailing-list memberships are re-applied where the group or list still exists, and some aliases may be dropped, so read the mailbox back and re-add what is missing. The record is consumed on success, so a second PATCH of the same :guid answers 404 unknown_purged_mailbox.

Returned Params
  • mailbox: Object | the same shape the mailbox delete and restore endpoints return
    • id: String | the restored mailbox's GUID
    • email: String
    • status: String | active
    • scheduled_deletion_at: DateTime | null
    • days_until_deletion: Integer | null

A mailbox can stop being recoverable while it is still listed

Branch on the status:

  • 409 not_recoverable — terminal, do not retry. The recovery window has closed, or the mail server confirmed it no longer holds the account (the record is then discarded, so a retry answers 404 unknown_purged_mailbox).
  • 422 restore_failed — the mail server refused, or a later step failed. A retry may work. Causes include the address being in use again by a new mailbox (delete or rename that one first) and the plan's mailbox limit being full (delete another mailbox or upgrade first).
  • 503 restore_unavailable — the check could not be made and nothing was attempted. Retry.

Restore in list order, soonest-to-expire first.

curl -X PATCH \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"password": "a-strong-password"}' \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/purged_mailboxes/$PURGED_ID
Errors
  • 404 unknown_purged_mailbox | no such record in this mailspace, or it has already been consumed
  • 409 not_recoverable | terminal — do not retry. Either the recovery window has closed, or the pre-flight read succeeded and reported that the mail server is no longer holding the account. On the second path the record is consumed on the way out, so a retry answers 404
  • 400 password_blank | no password supplied
  • 422 restore_failed | the mail server answered and refused, or a later step failed. Retriable
  • 503 restore_unavailable | the pre-flight read of the mail server's pending-erase list could not be performed, so nothing was attempted. The record is untouched — retry
  • plus the shared guards

Error Codes

All errors except the OAuth scope failure use the standard {"errors": [...], "code": "..."} envelope described in Error Responses. An unknown or out-of-scope :mailspace_id is the exception in the other direction: 404 with an empty body and no envelope at all. On Download an Archived Message the errors are JSON even though a success is not.

Shared by every endpoint on this page — see Request Guards:

Code Status Raised on
stalwart_unavailable 503 all requests
not_authorized 403 POST, PATCH, DELETE
mailspace_suspended 403 all requests
mailspace_server_mismatch 503 all requests
pending_delete 403 POST, PATCH, DELETE
not_provisioned 409 all requests

Per endpoint:

Code Status Raised by
archived_items_unavailable 503 list archived mail
purged_mailboxes_unavailable 503 list recoverable mailboxes
unknown_archived_item 404 view, restore, download, delete an archived item; also a restore or delete whose item vanishes between the two id lookups
archived_item_lookup_unavailable 503 view, restore, download, delete an archived item — the ownership lookup could not be performed, so nothing was sent
restore_failed 422 restore an archived item; restore a purged mailbox
restore_unconfirmed 503 restore an archived item — the instruction went out and its fate is unknown
restore_unavailable 503 restore a purged mailbox — nothing was attempted
download_unavailable 404 / 503 download an archived message — 404 the message is gone (terminal), 503 any other read failure (retriable)
delete_failed 422 delete an archived item
delete_unconfirmed 503 delete an archived item — the erase went out and may already have happened. Irreversible
unknown_purged_mailbox 404 restore a purged mailbox
not_recoverable 409 restore a purged mailbox
password_blank 400 restore a purged mailbox

The delivery-log endpoint has no failure codes of its own — only the shared guards.