Ga naar inhoud

Mailspace

Mailspace is mailboxhosting op workspace-niveau: je schaft het aan voor een domein en het levert de mailboxen, aliassen en groepen voor dat domein. Deze endpoints gaan over de mailomgeving zelf — aanschaffen, bekijken, resizen, verwijderen en definitief verwijderen.

Alles binnen een mailomgeving heeft zijn eigen referentiepagina:

OAuth-scopes: reads vereisen mailspace:read, writes vereisen mailspace:write. Sessie- en API-sleutel-credentials slaan de scopecontroles volledig over (zie OAuth).

Mailspace-ID's zijn GUID's. Een mailomgeving die niet zichtbaar is voor je credential geeft 404 terug; een credential zonder bewerkrecht op het eigenaarsaccount geeft 403 {"errors":["Not Authorized"]} terug.

Mailspace wordt alleen op jaarbasis verkocht — er is geen maandprijs, dus nergens op deze pagina wordt een term-parameter geaccepteerd.

Een 202 Accepted betekent niet dat de belasting is geslaagd

POST /api/mailspace en PATCH /api/mailspace/:id zijn asynchroon: ze bouwen een cart, belasten het facturatieaccount off-session, en geven 202 terug met de gedeelde cart-envelop.

Een geweigerde off-session-belasting is óók een 202. De envelop meldt dan payment.status als "awaiting_authentication" en bevat een payment.hosted_invoice_url waarmee de klant kan betalen (dit dekt ook 3DS/SCA). Vertak op payment.status, nooit alleen op de HTTP-status — een client die elke 202 als succes behandelt, meldt een mailomgeving als besteld terwijl er nooit iets is betaald of voorzien.

Het facturatieplan bepaalt het belastingpad

Op een Stripe-facturatieplan wordt de cart off-session belast en wordt er asynchroon afgewikkeld — dat is de stroom die de envelop hierboven beschrijft, en het is de enige stroom die een opgeslagen standaard betaalmethode vereist (400 no_default_payment_method).

Op een niet-Stripe-facturatieplan (betaalmethode "none") wordt het account extern gefactureerd, wordt er geen Stripe-belasting geprobeerd, en wordt de no_default_payment_method-bewaking volledig overgeslagen. De reactie is nog steeds dezelfde 202-envelop. Dit spiegelt de splitsing bij planwijzigingen van sites.

Leesfouten

Elke lijst binnen een mailomgeving leest de mailserver live uit, en die reads zijn strikt: een read die niet kón worden uitgevoerd antwoordt 503 met een code die benoemt wélke read is mislukt, nooit 200 met een lege payload. Het nuttige gevolg is dit — op die endpoints betekent een lege lijst dat de mailserver is gevraagd, dus een 200 verbergt geen mislukte read meer en je kunt je eigen administratie ermee verzoenen.

Wat je daarmee niet krijgt is volledigheid. Al deze lijsten zijn upstream begrensd en kappen stil af, zonder totaal en zonder vlag; de grenzen staan hieronder, en de lijst met definitief verwijderde mailboxen heeft een ergere dan de rest. Dus: een 200 bewijst dat de read is gebeurd, niet dat de lijst compleet is.

Endpoint Code
GET /api/mailspace/:mailspace_id/mailboxes mailboxes_unavailable
GET /api/mailspace/:mailspace_id/domains domains_unavailable
GET /api/mailspace/:mailspace_id/aliases aliases_unavailable
GET /api/mailspace/:mailspace_id/groups groups_unavailable
GET /api/mailspace/:mailspace_id/mailing_lists mailing_lists_unavailable
GET /api/mailspace/:mailspace_id/archived_items archived_items_unavailable
GET /api/mailspace/:mailspace_id/purged_mailboxes purged_mailboxes_unavailable

Ze zijn allemaal tijdelijk — probeer het opnieuw. Geen ervan is een clientfout, en geen ervan betekent dat de resource leeg is.

Bij de lijst met definitief verwijderde mailboxen kan een lege 200 nog steeds gegevens kosten

De kruiscontrole daarvan leest de openstaande wistaken van de mailserver 500 rijen per keer over de hele mailserver, en filtert ze daarna terug naar deze mailomgeving. Er is geen totaal en geen signaal dat er is afgekapt, dus op een drukke server kan de wistaak van een herstelbare mailbox buiten dat venster vallen en wordt de momentopname stil weggelaten uit een verder gezonde 200. Behandel een vermelde momentopname als echt; behandel een lege lijst als "niets gevonden", nooit als "de mail is weg". Gooi je eigen laatste registratie van een mailbox er niet op weg.

Elke code dekt één read en niets anders. Een fout in het q-filter, in een reactietemplate of ergens anders in het endpoint is een echte 500, niet een van deze codes.

Groepen opvragen heeft twee codes, en het verschil is welke read mislukte

GET .../groups doet twee reads — de groepenlijst, en daarna een ledentelling per groep — en elk heeft zijn eigen code:

  • groups_unavailable — de groepenlijst kon niet worden gelezen, dus er is niets bekend over de groepen van deze mailomgeving. Dit is wat een volledige storing van de mailserver antwoordt.
  • group_members_unavailable — de groepen kwamen terug maar de ledenaantallen niet. Het endpoint weigert member_count: 0 te melden voor elke groep wanneer het er niet naar kon vragen.

group_members_unavailable komt ook voor op GET .../groups/:stalwart_id (de adressen van de leden konden niet worden gelezen) en op PATCH .../groups/:stalwart_id, waar de wijziging al is doorgevoerd en alleen het teruglezen is mislukt — verstuur de wijziging niet opnieuw, lees de groep opnieuw.

stalwart_unavailable (503) is een ander soort code. Hij is niet beperkt tot de bewaking op mailomgevingsniveau, en geen van zijn betekenissen is "de mailomgeving kon niet worden opgezocht" — een onbekende of buiten je bereik vallende :mailspace_id antwoordt altijd 404 met een lege body:

  • mailhosting is niet geconfigureerd op het platform, wat elk verzoek in de Mailspace-familie weigert voordat er iets wordt opgezocht;
  • één afzonderlijke read is mislukt. GET, PATCH en DELETE op /api/mailspace/:mailspace_id/domains/:name delen een lookup die de mailserver naar het domein vraagt, en die antwoordt stalwart_unavailable als die read mislukt en de naam ook geen lokaal wachtend domein is. Zie Mailspace-domeinen.

Lees stalwart_unavailable dus niet als een code die niets over het afzonderlijke verzoek zegt: op de domeinpaden zegt hij precies dat, en daar is hij het opnieuw proberen waard.

Waar een leeg of hol resultaat nog steeds geen bewijs is

De tabel hierboven is de strikte verzameling. Een aantal reads is nog steeds tolerant — die antwoorden 200 met een lege of gedeeltelijke payload als de mailserver niet bereikbaar is, en niets in de reactie onderscheidt dat van een werkelijk leeg resultaat:

  • Bezorglogs — inkomende en uitgaande traces, de uitgaande wachtrij en de daaruit afgeleide bezorgproblemen vallen elk terug op een lege lijst. Zie Mailspace-logs en herstel.
  • Mailboxdetails — groepslidmaatschappen, mailinglijstlidmaatschappen, app-wachtwoorden en de TOTP-vlag hebben elk hun eigen lege foutwaarde, dus een mailbox kan terugkomen alsof hij tot geen enkele groep behoort, geen app-wachtwoorden heeft en TOTP uit heeft staan. De mailboxindex is strikt; het detailoverzicht niet.
  • De lijst met app-wachtwoorden — GET .../app_passwords antwoordt 200 met een lege array wanneer die read mislukt. Dit is bewust zo en verandert niet: een app-wachtwoord intrekken vereist het id ervan, dus een lege lijst valt hier niet vernietigend te gebruiken.
  • Verhulde adressen — GET .../masked_emails antwoordt 200 met nul rijen wanneer die read mislukt.
  • Eén groep of mailinglijst op id opzoeken — GET .../groups/:stalwart_id en GET .../mailing_lists/:stalwart_id lopen dicht naar 404: van een onleesbare principal valt niet te bewijzen dat hij van jou is, dus wordt hij geweigerd in plaats van hol teruggegeven. Eén 404 daar is dus geen bewijs dat de groep of lijst weg is — de index is de gezaghebbende controle.
  • Limieten op de indexen — een principal-read is begrensd op 500 rijen en verhulde adressen op 2000. Het afkappen gebeurt stil: er is geen totaal, geen "meer"-vlag en geen foutcode die het meldt. De 500 geldt niet per principal-type: mailboxen en groepen zijn op de mailserver hetzelfde soort object en worden pas op type gesplitst nadat de begrensde query is beantwoord, dus een mailomgeving met 500 of meer mailboxen kan nul groepen teruggeven met een 200. De 2000 voor verhulde adressen wordt serverbreed toegepast, vóór de rijen van deze mailomgeving eruit worden gehaald.

Je eigen administratie verzoenen met een van deze lijsten — verwijderen wat de reactie weglaat — vernietigt gegevens bij een tijdelijke storing van de mailserver.

Verwijderde mail: onbereikbaar en niet-gelicentieerd zijn verschillend, en maar één ervan is zichtbaar

Het archief met verwijderde mail is een gelicentieerde functie van de mailserver. Op een installatie zonder die licentie antwoordt GET .../archived_items met 200 en een lege lijst, en antwoordt elke route op id 404 — dus "niets gearchiveerd" en "niet gelicentieerd" zijn niet van elkaar te onderscheiden, en dat is bewust, omdat er niets valt af te tasten.

Dat is geen gat in de strikte read hierboven. De mailserver antwoordt op een verzoek om een gelicentieerd object, en een antwoord is precies waar de strikte read op controleert; een server die geen antwoord geeft levert de 503. Een onbereikbare mailserver is dus wél te onderscheiden van een leeg archief. Een niet-gelicentieerde niet.

Bij een write antwoordt 503 op een van twee tegengestelde vragen — kijk welke

Sommige van deze codes betekenen er is niets geprobeerd. Andere betekenen er is iets geprobeerd en de uitkomst is onbekend. De status is dezelfde; de code vertelt het je, en het valt niet af te leiden uit het woord "unavailable".

Er is niets geprobeerd — de resource is onaangeroerd, probeer het opnieuw:

  • PATCH .../purged_mailboxes/:guid → 503 restore_unavailable. Het herstel vraagt de mailserver eerst of die het account nog vasthoudt voordat het de momentopname verbruikt, dus een read die niet kan worden uitgevoerd breekt het herstel af in plaats van de laatste registratie van een levende mailbox te vernietigen.
  • POST, DELETE, GET en de download op .../archived_items/:stalwart_id → 503 archived_item_lookup_unavailable. De eigendomscontrole die het id oplost kon niet worden uitgevoerd, dus er is niets naar de mailserver gestuurd.

Er is iets geprobeerd en de uitkomst is onbekend — lees opnieuw voordat je het opnieuw probeert:

  • POST .../archived_items/:stalwart_id/restore → 503 restore_unconfirmed. De herstelopdracht is verstuurd en staat mogelijk al in de wachtrij.
  • DELETE .../archived_items/:stalwart_id → 503 delete_unconfirmed. De wissing is verstuurd en kan al zijn uitgevoerd, en dat is onomkeerbaar. Lees het item terug — een 404 betekent dat het is gelukt. Dit behandelen als "het verwijderen is mislukt" is de slechtste van de mogelijke aannames.
  • POST .../aliases en DELETE .../aliases/:address → 503 aliases_unavailable. Bij een write dekt deze code ook de write zelf, dus de alias is mogelijk aangemaakt of verwijderd. Beide writes zijn veilig te herhalen, maar lees Aliassen opvragen opnieuw in plaats van een fout aan een gebruiker te melden.
  • DELETE .../mailboxes/:id/force_delete → 503 delete_unavailable. Opnieuw een derde geval: de mailbox is al weg bij de mailserver, en wat niet kon worden vastgesteld is of de mail nog herstelbaar is. De lokale registratie blijft staan, de mailbox staat nog in de lijst en de opruimtaak probeert het opnieuw.

Een 422 is het enige antwoord dat betekent dat de mailserver heeft geantwoord en heeft geweigerd. Bij het herstel van een definitief verwijderde mailbox is die driedeling het leren waard als patroon: 409 not_recoverable betekent dat er niets meer aan te doen is, 422 restore_failed dat de server heeft geweigerd en opnieuw proberen kan helpen, 503 restore_unavailable dat de controle niet kon worden gedaan.

Twee endpoints antwoorden iets anders dan 503

Dit is het huidige gedrag, geen regel om uit te generaliseren:

  • De endpoints voor mailregels en afwezigheidsberichten antwoorden 422 mail_rules_unavailable wanneer het filterscript van een mailbox niet kan worden teruggelezen — bij een gewone GET net zo goed als bij een write, waar het bovendien betekent dat er niets is opgeslagen. Zie Mailspace-mailboxen.
  • Het downloaden van een gearchiveerd bericht antwoordt download_unavailable onder twee statussen, en de status is het verschil: 404 wanneer de mailserver heeft geantwoord dat het bericht weg is (definitief — stop), 503 bij elke andere leesfout (het bericht kan er nog zijn — probeer het opnieuw). Zie Mailspace-logs en herstel.

Mailomgevingen opvragen

GET /api/mailspace

Geeft de mailomgevingen terug, nieuwste eerst. Met soft delete verwijderde mailomgevingen (die op verwijderen wachten) zijn inbegrepen — ze blijven vermeld gedurende hun bewaartermijn; definitief verwijderde records zijn weg. Dit endpoint is niet gepagineerd.

Met de header X-Auth-Account is de lijst die van dat account; zonder die header valt een credential zonder account terug op elke mailomgeving die de gebruiker van het token kan bereiken.

Teruggegeven params
  • mailspaces: Array
    • id: String | GUID
    • domain: String | het maildomein, bijv. example.com
    • account_name: String | de mailaccountnaam die op het record staat
    • package: String | mail-Product short_name, bijv. mail_5
    • package_name: String | weergavenaam, bijv. Mailspace 5GB
    • status: String | pending, active, suspended, of inactive
    • storage_gb: Integer | opslag die bij het pakket hoort
    • max_mailboxes: Integer | mailboxlimiet van het pakket
    • used_mb: Integer | laatst gemeten opslaggebruik, in MB
    • mailbox_count: Integer | momenteel gedefinieerde mailboxen
    • provisioned: Boolean | de mailtenant bestaat en is klaar voor gebruik
    • verified: Boolean | domeineigendom is bevestigd
    • needs_domain_verification: Boolean | er moet nog een DNS-TXT-record worden gepubliceerd — zie Een mailomgeving bekijken
    • pending_deletion: Boolean | met soft delete verwijderd; alleen herstellen of definitief verwijderen
    • delete_scheduled_at: DateTime | vastgelegde datum van definitieve verwijdering, null zolang de mailomgeving actief is
    • created_at: DateTime
    • updated_at: DateTime
    • account: Object
      • id: String
      • name: String

Een mailomgeving bekijken

GET /api/mailspace/:id

Geserialiseerd uit de lokale status — geen live aanroep naar de mailserver, dus used_mb en mailbox_count zijn de laatst gemeten waarden, geen live cijfers.

synced_at is geen tijdstempel voor de gebruikscijfers

synced_at wordt gezet wanneer iemand de mailomgeving in het dashboard opent — en wordt ook gezet als het uitlezen van het gebruik op die pagina is mislukt. used_mb en mailbox_count hebben intern hun eigen meetmoment, dat deze API niet blootgeeft. Een workspace die uitsluitend de API gebruikt, kan dus synced_at: null zien naast volledig actuele gebruikscijfers (een resize meet het gebruik opnieuw zonder synced_at aan te raken), of een synced_at die nieuwer is dan de cijfers ernaast. Beschouw de twee als los van elkaar.

Teruggegeven params
  • mailspace: Object
    • alle velden uit Mailomgevingen opvragen, plus:
    • synced_at: DateTime | wanneer de mailomgeving voor het laatst in het dashboard is geopend, null als dat nooit is gebeurd. Geen tijdstempel voor used_mb / mailbox_count — zie hierboven
    • webmail_url: String | toegangspunt voor webmail voor het domein
    • verification: Object | alleen aanwezig zolang needs_domain_verification waar is
      • txt_prefix: String | _mailspace-verify
      • txt_host: String | de recordhost, bijv. _mailspace-verify.example.com
      • txt_value: String | het token dat je als TXT-waarde publiceert
    • subscription: Object | alleen aanwezig wanneer er een facturatieabonnement is gekoppeld
      • id: String
      • status: String
      • created_at: DateTime
      • updated_at: DateTime
      • price: Object
        • amount_cents: Integer
        • term: String
    • account: Object
      • id: String
      • name: String

Het verification-blok is de to-do na aanschaf

Voor een domein dat de workspace nog niet in eigendom heeft, wordt de mailomgeving na afwikkeling van de betaling aangemaakt met de status Wacht op verificatie. Poll dit endpoint, publiceer het TXT-record uit het verification-blok, en de mailomgeving wordt bij de volgende controleronde zelf voorzien. Het blok hangt af van needs_domain_verification en verdwijnt dus zodra het eigendom is vastgesteld — nog vóór provisioned op true staat. Zie het verdwijnen van het blok niet als "de mailomgeving is klaar"; controleer provisioned. Voor een domein dat de workspace al in eigendom heeft, wordt verificatie overgeslagen en verschijnt het blok helemaal niet.

Een mailomgeving aanschaffen

POST /api/mailspace

Bouwt een losstaande cart voor de mailomgeving en verstuurt die. Geeft 202 Accepted terug met de cart-envelop — lees de waarschuwing bovenaan deze pagina opnieuw voordat je de reactie verwerkt.

Een accountcontext is vereist, omdat de aanschaf moet weten wat er gefactureerd wordt: geef de header X-Auth-Account mee of gebruik een credential met accountscope.

De mailomgeving zelf bestaat nog niet wanneer de 202 wordt teruggegeven — die wordt pas aangemaakt nadat de betaling is afgewikkeld, dus staat er geen mailspace-ID in de reactie. Poll cart.poll_url totdat de cart klaar is, en zoek de nieuwe mailomgeving vervolgens op met GET /api/mailspace.

Params
  • domain: String (required) | het maildomein; wordt voor je omgezet naar kleine letters en getrimd. Moet op een echte hostname lijken en moet een domein zijn dat daadwerkelijk bestaat (bij ons of elders geregistreerd).
  • package: String (optional) | mail-Product short_name — mail_5, mail_20, mail_50, mail_200, mail_500. Standaard het basispakket (de kleinste tier).
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "package": "mail_50"}' \
  https://my.cloudpress.com/api/mailspace
Teruggegeven params (altijd 202 Accepted)

De gedeelde cart-envelop, identiek aan POST /api/orders:

  • status: String | "accepted"
  • cart: Object | { token, status, rollup_status, poll_url }
  • payment: Object | { status, method_type, hosted_invoice_url }
  • orders: Array | [{ id, status, poll_url }] (leeg tijdens het asynchrone venster)
Fouten
  • 503 stalwart_unavailable | mailhosting is momenteel niet beschikbaar
  • 400 account_required | geen accountcontext — geef X-Auth-Account mee of gebruik een credential met accountscope
  • 400 invalid_domain | domain ontbreekt of is geen plausibele hostname
  • 400 unknown_product | package is geen van de mailpakketten
  • 422 domain_not_registered | het domein is nergens geregistreerd, dus mail ervoor zou nooit kunnen werken. Wordt na unknown_product gecontroleerd, dus een verzoek dat op beide punten fout is, antwoordt nog steeds unknown_product.
  • 422 mailspace_exists | het domein heeft al een mailomgeving. Dat geldt ook voor je eigen mailomgeving die op verwijderen wacht — het domein blijft de hele bewaartermijn geclaimd, dus herstel die in plaats van opnieuw aan te schaffen.
  • 400 no_default_payment_method | alleen bij Stripe-facturatieplannen: het facturatieaccount heeft geen Stripe-customer, geen opgeslagen standaard betaalmethode, of een onvolledig facturatiecontact. De body bevat naast errors en code ook een remediation-string.
  • 422 cart_item_rejected | de cart weigerde het mail-item — meestal omdat de mailprijzen voor het gevraagde pakket nog niet zijn geconfigureerd
  • 422 cart_pay_failed | de cart was geldig maar de belasting kon niet worden gestart (een weigering die wel is gestart, is een 202 en niet dit)

Er is geen WordPress-site nodig

De regel binnen de cart dat mail alleen bovenop WordPress- of cPanel-hosting kan worden toegevoegd, geldt hier niet: dit endpoint bouwt een eigen cart voor de mailomgeving, die per constructie aan die regel voldoet. Een mailomgeving kan via de API los worden aangeschaft, voor elk bestaand domein.

Een mailomgeving resizen

PATCH /api/mailspace/:id

Zet de mailomgeving over naar een ander pakket. Net als de aanschaf is dit cart-gemedieerd en asynchroon — 202 Accepted met dezelfde envelop, en hetzelfde voorbehoud rond payment.status.

Op een Stripe-facturatieplan wordt de wijziging naar rato verrekend met het bestaande abonnement van de mailomgeving. Op een extern gefactureerd plan is er geen Stripe-belasting; het nieuwe pakket wordt toegepast en buiten het platform gefactureerd.

Het huidige opslaggebruik wordt bij elke resize opnieuw gemeten tegen de mailserver — ook bij upgrades, ook al kan alleen een downgrade erdoor worden geblokkeerd — dus een resize-verzoek is niet direct klaar, zelfs niet vóór de belasting.

Params
  • package: String (required) | de mail-Product short_name van het doelpakket. Moet verschillen van het huidige pakket.
Teruggegeven params (altijd 202 Accepted)

De gedeelde cart-envelop — zie Een mailomgeving aanschaffen.

Fouten

Worden in deze volgorde geëvalueerd:

  • 503 stalwart_unavailable | mailhosting is momenteel niet beschikbaar
  • 403 mailspace_suspended | de mailomgeving is geblokkeerd (door support of wegens een onbetaalde factuur) en kan niet worden gewijzigd
  • 422 pending_delete | de mailomgeving staat gepland voor verwijdering — herstel die eerst
  • 400 unknown_product | package is geen van de mailpakketten
  • 422 package_unchanged | zit al op dat pakket
  • 422 not_provisioned | de mailomgeving is nog niet klaar met inrichten
  • 422 resize_unavailable | alleen bij Stripe-facturatieplannen: de mailomgeving heeft geen actief facturatieabonnement om naar rato tegen te verrekenen
  • 422 downgrade_blocked | het doelpakket is kleiner dan het huidige aantal mailboxen of de opgeslagen mail van de mailomgeving. Verwijder eerst mailboxen of maak opslag vrij.
  • 400 no_default_payment_method | alleen bij Stripe-facturatieplannen, zoals bij aanschaf
  • 422 cart_item_rejected | de cart kon de wijziging niet opbouwen
  • 422 cart_pay_failed | de naar rato verrekende belasting kon niet worden gestart

Een mailomgeving verwijderen

DELETE /api/mailspace/:id

Wat dit doet, hangt ervan af of de mailomgeving ooit is voorzien — de twee uitkomsten verschillen wezenlijk, en het endpoint biedt geen manier om er een van te kiezen. Beide geven 200 terug met een lege body, dus controleer provisioned op de mailomgeving voordat je dit aanroept als het verschil uitmaakt.

Soft delete. De mailomgeving stopt met het verwerken van mail en gaat een bewaartermijn in; pending_deletion wordt true en delete_scheduled_at is de vastgelegde datum van definitieve verwijdering. De mailomgeving blijft zichtbaar in GET /api/mailspace. De facturatie wordt beëindigd met een naar rato verrekend tegoed voor de vroegtijdige opzegging. Eerder definitief verwijderen dan de bewaartermijn toestaat, kan met Een mailomgeving definitief verwijderen hieronder; herstellen hoort niet bij deze API — gebruik daarvoor het dashboard.

Idempotent: een mailomgeving verwijderen die al op verwijderen wacht, lukt en verandert niets.

Harde verwijdering, en de volledige eerste termijn wordt teruggegeven. Een mailomgeving die nog op domeinverificatie wacht, heeft geen mailtenant om te blokkeren en heeft niets van haar vooruitbetaalde termijn gebruikt, dus wordt de aanschaf hiermee volledig teruggedraaid: het record wordt vernietigd (het verdwijnt uit GET /api/mailspace; pending_deletion wordt nooit gezet en delete_scheduled_at wordt nooit toegekend), de oorspronkelijke bestelling wordt volledig terugbetaald en gemarkeerd als cancelled, en de abonnementsregel wordt verwijderd.

Omdat het record weg is, komt het domein direct vrij — een nieuwe aanschaf voor hetzelfde domein slaagt in plaats van te stuiten op mailspace_exists.

Draait in beide gevallen synchroon.

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

Een met soft delete verwijderde mailomgeving houdt zijn domein geclaimd

Een voorziene mailomgeving houdt zijn maildomein de hele bewaartermijn. Een nieuwe mailomgeving aanschaffen voor dat domein mislukt in de tussentijd met 422 mailspace_exists — herstel in plaats daarvan de bestaande. Dit geldt niet voor het nooit-voorziene geval hierboven, waar het record wordt vernietigd en het domein meteen vrijkomt.

Fouten
  • 503 stalwart_unavailable | mailhosting is momenteel niet beschikbaar
  • 403 mailspace_suspended | de mailomgeving is geblokkeerd (door support of wegens een onbetaalde factuur) en kan niet worden verwijderd
  • 422 delete_failed | de verwijdering kon niet worden afgerond. Op het nooit-voorziene pad dekt dit ook een mislukte creditering — de terugbetaling kon niet worden verwerkt, dus wordt de mailomgeving bewust intact gelaten in plaats van onbetaald verwijderd. Probeer het opnieuw.

Een mailomgeving definitief verwijderen

POST /api/mailspace/:mailspace_id/purge

Vernietigt een mailomgeving die al met soft delete is verwijderd, in plaats van de bewaartermijn af te wachten. Geeft 200 terug.

Onomkeerbaar, en de mail gaat mee

De tenant op de mailserver — elk domein, elke mailbox en alle opgeslagen berichten — en het lokale record worden vernietigd, en de mailrecords die CloudPress in de door ons gehoste DNS-zone van de klant heeft gezet, worden verwijderd. Niets hiervan is te herstellen, en er volgt geen taak: het werk is klaar op het moment dat je het antwoord krijgt.

Er is geen bevestigingsparameter. De enige voorwaarde is dat de mailomgeving al op verwijderen wacht.

De facturatie blijft ongemoeid — die is al beëindigd bij de soft delete, dus eerder definitief verwijderen levert geen terugbetaling en geen extra kosten op.

Elke definitieve verwijdering wordt met de gebruikte credential vastgelegd in het auditlog van het platform.

Teruggegeven params
  • purged: Boolean | altijd true; een verwijdering die niets opruimde geeft in plaats daarvan een 409
  • domain: String | het maildomein dat is vrijgekomen, vastgelegd voordat het record werd vernietigd
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/purge

Een actieve mailomgeving definitief verwijderen geeft een 409

409 not_pending_deletion betekent dat er niets is verwijderd en dat de mailomgeving er nog is. Het dekt zowel een mailomgeving die nooit is verwijderd — roep eerst DELETE /api/mailspace/:id aan — als de race waarin er tussen de controle en de vernietiging een herstel plaatsvindt.

Fouten
  • 404 | de mailomgeving is niet zichtbaar voor je credential
  • 503 stalwart_unavailable | mailhosting is momenteel niet beschikbaar
  • 403 not_authorized | de credential heeft geen bewerkrecht op de eigenaars-workspace
  • 403 mailspace_suspended | de mailomgeving is actief en geblokkeerd (door support of wegens een onbetaalde factuur)
  • 409 not_provisioned | de mailomgeving heeft geen tenant op de mailserver om te vernietigen
  • 409 not_pending_deletion | de mailomgeving is niet ingepland voor verwijdering — zie hierboven
  • 422 purge_failed | de definitieve verwijdering kon niet worden afgerond; er is niets vernietigd

Foutcodes

Alle fouten gebruiken de standaardenvelop {"errors": [...], "code": "..."} die is beschreven in Foutreacties.

Dezelfde codenaam, een andere status, binnen een mailomgeving

De endpoints op deze pagina geven pending_delete en not_provisioned zelf terug, als 422. De geneste endpoints — mailboxen, adressen, domeinen, logs — erven ze van een gedeelde gate, die 403 teruggeeft voor pending_delete en 409 voor not_provisioned. Een client die op de status vertakt in plaats van op de code, leest een van de twee families verkeerd.

De 403 op deze pagina bevat bovendien helemaal geen code-veld ({"errors":["Not Authorized"]}); de geneste gate geeft daar not_authorized bij.

Code Status Geretourneerd door
stalwart_unavailable 503 create, update, destroy, purge
account_required 400 create
invalid_domain 400 create
domain_not_registered 422 create
unknown_product 400 create, update
mailspace_exists 422 create
no_default_payment_method 400 create, update
cart_item_rejected 422 create, update
cart_pay_failed 422 create, update
mailspace_suspended 403 update, destroy, purge
pending_delete 422 update
package_unchanged 422 update
not_provisioned 422 update
resize_unavailable 422 update
downgrade_blocked 422 update
delete_failed 422 destroy
not_authorized 403 purge
not_provisioned 409 purge
not_pending_deletion 409 purge
purge_failed 422 purge