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
GETorHEAD. So Restore an Archived Item is a write, and Download an Archived Message is a read. A view-only member holding amailspace:writetoken can read everything here but gets403not_authorizedon every restore and delete. - A mailspace pending deletion still answers reads for its retention window;
every write is refused with
403pending_deleteuntil 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_idanswers404with 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/outgoingcome from delivery tracing, which is not available on every deployment. Where it is unavailable, both arrays are always empty, however much mail flowed.queueis available everywhere.issuescombines 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 asnull. Do not key or de-duplicate the trace arrays on it unguarded — the non-null guarantee onqueueandissuesbelow 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 |
nullif the mail server recorded none - size: Integer |
null— bytes - direction: String |
incomingoroutgoing - internal: Boolean |
truefor mailbox-to-mailbox mail inside this mailspace (see above) - status: String | derived from the SMTP log:
delivered,bounced,failed,retrying, orsending - 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
- name: String | the mail-server event name, e.g.
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. Nevernullon these two arrays (unlike a trace's ownid). - source: String |
queueortrace— which dataset the entry came out of. Present on every entry ofqueueandissues; 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.dsnSentonce a bounce notification has been sent - recipients:
Array<Object>- address: String
- status: String |
Completed,TemporaryFailureorPermanentFailure;nullwhile 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 |
nullwhen 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
- type: String |
- 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:
- any recipient
PermanentFailure→bouncedifflagsincludesdsnSent, otherwisefailed; - else any recipient
TemporaryFailure→retrying; - else all recipients
Completed→delivered; - 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 inevents. Itsidis a stable synthetictrace-<…>value you may key on.recipientsholds one entry whoseaddressis the trace's whole comma-separated recipient string, withstatusPermanentFailure,retry_due,retry_countanderror.typenull.flagsis["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 underqueue).eventsis 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
idfrom the list as the:stalwart_idsegment; an id that does not belong to this mailspace answers404unknown_archived_item. - Branch on
code, never onerrors[0]. Archive failures carry an English sentence whateverAccept-Languageyou 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_idsegment for every by-id endpoint below - type: String | the item variant.
Emailin practice; the mail server declares others but never writes them - status: String |
archived, orrequestRestoreonce a restore has been queued for it. The mail server omits the field while it holds its default, so it is filled in asarchived - 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
- id: String | the opaque item id — this is the
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 empty200described 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
403not_authorizedand403pending_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:404when the mail server answered that the stored message is gone (terminal — stop),503for 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
:guidsegment 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
- id: String | the record's GUID — this is the
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 empty200— 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
400password_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:
409not_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 answers404unknown_purged_mailbox).422restore_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).503restore_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 answers404 - 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.