Ga naar inhoud

Mailspace-mailboxen

Mailspace is het plan: je schaft het aan voor een domein en je resizet of zegt het op. Deze pagina gaat over alles binnen één mailomgeving — de mailboxen, de app-wachtwoorden en filterregels van elke mailbox, en het afwezigheidsbericht en doorsturen.

Elke route is genest onder één mailomgeving, dus de mailspace-GUID is altijd het eerste padsegment. Haal die op met GET /api/mailspace. Mailboxen worden geadresseerd met hun GUID (.../mailboxes/9f3c…), nooit met een e-mailadres. Dezelfde GUID is het mailbox_id-segment voor app-wachtwoorden, mailregels, afwezigheidsberichten en doorsturen. App-wachtwoorden zijn de uitzondering: hun :id is het credential-ID (een String).

OAuth-scopes: reads vereisen mailspace:read, writes vereisen mailspace:write — dezelfde scopes als de endpoints op planniveau. Sessie- en API-sleutel-credentials slaan de scopecontroles over (zie OAuth).

Er is geen step-up-authenticatie op deze API, en geen enkel endpoint op deze pagina accepteert het eigen wachtwoord van de aanroeper in de request body.


Gedeelde controles

Elk endpoint op deze pagina doorloopt deze controles, in deze volgorde. De eerste die faalt, antwoordt het verzoek.

Van toepassing op Voorwaarde Reactie
alle de mailserver is niet geconfigureerd op het platform 503 stalwart_unavailable
alle mailspace-GUID onbekend, of niet zichtbaar voor je credential 404, lege body
alleen writes je gebruiker heeft geen bewerkrecht op de workspace die de mailomgeving bezit 403 not_authorized
alle, inclusief reads de mailomgeving is gekoppeld aan een andere mailserver dan de nu geconfigureerde 503 mailspace_server_mismatch
alle, inclusief reads de mailomgeving is geblokkeerd door support of wegens een onbetaalde factuur 403 mailspace_suspended
alleen writes de mailomgeving staat ingepland voor verwijdering 403 pending_delete
alle de mailomgeving heeft nog geen tenant op de mailserver 409 not_provisioned

Naast de tabel:

  • Onbekende mailbox. Elk endpoint dat een mailbox noemt, antwoordt 404 unknown_mailbox als die niet in deze mailomgeving zit, dus een GUID van een andere workspace is een 404, geen 403. De endpoints voor app-wachtwoorden, mailregels, afwezigheidsberichten en doorsturen geven dezelfde 404 voor een mailbox die ingepland staat voor verwijdering. Herstel die eerst.
  • Writes worden bepaald door de HTTP-verb. Alles behalve GET en HEAD is een write, inclusief restore, force_delete, toggle, move en adopt. Een lid met alleen leesrechten en een mailspace:write-token krijgt op al deze 403 not_authorized. Een HEAD-verzoek geeft dezelfde status als de bijbehorende GET. Het recht wordt gecontroleerd op de workspace die de mailomgeving bezit, niet op die in X-Auth-Account.
  • Bewaartermijn. Nadat je een mailomgeving hebt verwijderd, blijven reads de hele bewaartermijn werken en antwoordt elke write 403 pending_delete. Herstel de mailomgeving om weer te kunnen schrijven. Een mailomgeving die zowel geblokkeerd is als ingepland staat voor verwijdering antwoordt een write met pending_delete en een read met 200.
  • Verschillen met de endpoints op planniveau. pending_delete is hier 403 (422 op Mailspace) en not_provisioned is 409 (422 daar). Een geweigerd recht is hier {"errors":["Not Authorized"],"code":"not_authorized"}; de endpoints op planniveau sturen geen code. Vertak op de code, niet op de status alleen.

Leesacties die leeg kunnen terugkomen


Mailboxen opvragen

GET /api/mailspace/:mailspace_id/mailboxes

Scope: mailspace:read.

Geeft de actieve mailboxen van de mailomgeving terug en, apart, die binnen hun soft-delete-respijtperiode. Een mailbox die ingepland staat voor verwijdering verschijnt alleen in pending, nooit in mailboxes.

Dit is een live read op de mailserver en dus traag. Er is geen paginering, het resultaat is begrensd op 500 mailboxen, en q filtert binnen die grens. De standaard rate limit geldt.

Een lege mailboxes-array is gezaghebbend: de mailserver is gevraagd en heeft er geen. Als de read faalt, is het hele antwoord de 503-fout, dus pending wordt er niet naast teruggegeven. Probeer opnieuw.

Params
  • q: String (optional) | niet-hoofdlettergevoelige substringmatch op het primaire adres van de mailbox. Geldt alleen voor mailboxes — pending wordt nooit gefilterd.
Teruggegeven params
  • mailboxes: Array | actieve mailboxen
    • id: String | de mailbox-GUID — de sleutel voor elk ander endpoint op deze pagina
    • email: String | het primaire adres
    • display_name: String
    • status: String | active of suspended
    • quota_mb: Integer | 0 betekent geen limiet per mailbox; de mailbox blijft begrensd door de opslagpool van het pakket
    • used_mb: Integer | naar boven afgerond op hele megabytes
    • aliases: Array | Array<String>, de adressen na het primaire adres
    • stalwart_id: String | het ID van de mailbox op de mailserver
    • scheduled_deletion_at: DateTime | null op een actieve mailbox
  • pending: Array | mailboxen binnen hun soft-delete-respijtperiode, oudste verwijderdatum eerst
    • id: String | de mailbox-GUID
    • email: String
    • status: String | in dit bakje altijd pending_deletion
    • scheduled_deletion_at: DateTime
    • days_until_deletion: Integer | nooit negatief; null als er geen datum is ingesteld

Verwijderde (purged) mailboxen worden hier niet vermeld. Gebruik GET /purged_mailboxes.

Fouten
  • 503 mailboxes_unavailable | de live mailboxread kon niet worden uitgevoerd. Opnieuw te proberen, en geen lege mailomgeving

Een adres controleren

GET /api/mailspace/:mailspace_id/mailboxes/check

Scope: mailspace:read. Alleen-lezen — er wordt niets gereserveerd of aangemaakt.

Vraagt of een adres vrij is voordat je er een mailbox op aanmaakt. Adressen zijn uniek over mailboxen, groepen en mailinglijsten, inclusief hun aliassen.

Params
  • username: String (required) | alleen het lokale deel — sales, niet sales@example.com
  • domain: String (optional) | standaard het eigen maildomein van de mailomgeving
Teruggegeven params
  • available: Boolean | true, false of null — zie de waarschuwing hieronder
  • used_by: String | "mailbox", "group" of "mailing list", of null als het adres vrij is

available: null betekent niet te verifiëren

Als de mailserver onbereikbaar is, antwoordt het endpoint toch 200, met available en used_by allebei null. Vertak op available === false voor bezet, nooit op !available, en behandel null als "vraag opnieuw". Zelfs true is adviserend: het adres kan bezet raken voordat je aanmaakverzoek binnenkomt.

Fouten
  • 400 invalid_address | username is leeg

Een mailbox bekijken

GET /api/mailspace/:mailspace_id/mailboxes/:id

Scope: mailspace:read. :id is de mailbox-GUID.

De volledige detailpayload.

Teruggegeven params
  • mailbox: Object
    • alle velden uit de mailboxes-items van Mailboxen opvragen, plus:
    • status: String | hier ook pending_deletion — dit endpoint leest ook een soft-deleted mailbox, en scheduled_deletion_at is dan gezet
    • allowed_ips: Array | Array<String>, de adressen en CIDR-bereiken die mogen inloggen met het eigen wachtwoord van de mailbox. [] betekent elk adres. App-wachtwoorden hebben eigen lijsten
    • groups: Array | Array<String>, groepsadressen waar deze mailbox bij hoort
    • lists: Array | Array<String>, mailinglijstadressen waarop deze mailbox is geabonneerd
    • two_factor: Object
      • enabled: Boolean
    • app_passwords: Array | dezelfde objecten die App-wachtwoorden opvragen teruggeeft
    • created_at: DateTime
    • updated_at: DateTime

Onleesbare velden zien er leeg uit

Als de mailserver onbereikbaar is, komen allowed_ips, groups, lists, app_passwords en aliases terug als [], two_factor.enabled als false, display_name als "" en quota_mb / used_mb als 0, en het antwoord is nog steeds 200. Een lege allowed_ips zegt dus niet of elk adres mag inloggen. Hetzelfde geldt voor de mailbox die aanmaken en bijwerken teruggeven. Baseer geen beveiligingsbeslissing of verwijdering op deze velden alleen.

two_factor.enabled is alleen een vlag: het secret wordt nooit teruggegeven en inschrijven hoort niet bij deze API. Ook secrets van app-wachtwoorden worden nooit teruggegeven (zie Een app-wachtwoord aanmaken).


Een mailbox aanmaken

POST /api/mailspace/:mailspace_id/mailboxes

Scope: mailspace:write. Geeft 201 Created terug.

Params
  • username: String (required) | het lokale deel. Samen met domain vormt het het adres
  • domain: String (optional) | standaard het eigen maildomein van de mailomgeving
  • password: String (required) | het inlogwachtwoord van de mailbox
  • display_name: String (optional)
  • quota_mb: Integer (optional) | limiet per mailbox in megabytes. 0 (de standaard) betekent geen limiet — de mailbox blijft begrensd door de opslagpool van het pakket. Een waarde groter dan het hele pakket wordt geweigerd
  • aliases: Array (optional) | Array<String> met extra adressen
  • groups: Array (optional) | Array<String> met groepsadressen in deze mailomgeving. Een vreemd adres wordt geweigerd
  • lists: Array (optional) | Array<String> met mailinglijstadressen in deze mailomgeving. Een vreemd adres wordt geweigerd

totp_secret en allowed_ips worden bij aanmaken niet geaccepteerd. Stel allowed_ips in met een daaropvolgende update.

Teruggegeven params (201 Created)
  • mailbox: Object
    • de mailboxes-velden uit Mailboxen opvragen, plus
    • created_at: DateTime
    • updated_at: DateTime

Dit is niet de volledige payload van Een mailbox bekijken: lees de mailbox terug voor allowed_ips, groups, lists, two_factor en 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}'
Fouten
  • 400 username_blank | username ontbreekt of is leeg
  • 400 password_blank | password ontbreekt of is leeg. Gecontroleerd na username_blank
  • 422 create_failed | de mailbox kon niet worden aangemaakt. De errors-melding zegt waarom: de mailboxlimiet van het pakket is bereikt, quota_mb is groter dan het pakket, het adres is al in gebruik door een mailbox, groep of mailinglijst in deze mailomgeving, een groups- of lists-item hoort niet bij deze mailomgeving, of de mailserver weigerde het aanmaken

Als een latere stap (aliassen, groepen of lijsten) faalt, bestaat de mailbox nog steeds en krijg je 422 create_failed. Lees de mailbox terug voordat je opnieuw probeert, en herstel hem dan met een update.


Een mailbox bijwerken

PATCH /api/mailspace/:mailspace_id/mailboxes/:id

Scope: mailspace:write.

Elk veld is optioneel, en een weggelaten veld blijft ongemoeid. Een lege waarde wist een veld: een lege aliases-array verwijdert alle aliassen, een lege allowed_ips wist de inlogbeperking.

Params
  • display_name: String (optional)
  • quota_mb: Integer (optional) | een lege string wordt behandeld als weggelaten, niet als 0. Stuur het getal 0 om de limiet per mailbox te verwijderen
  • status: String (optional) | active of suspended. pending_deletion wordt geweigerd op een mailbox die nog niet is ingepland voor verwijdering — gebruik DELETE. Het sturen voor een al ingeplande mailbox verandert niets
  • password: String (optional) | leeg of weggelaten behoudt het huidige wachtwoord
  • aliases: Array (optional) | Array<String>. Vervangt de hele lijst
  • groups: Array (optional) | Array<String>. Vervangt de hele lijst. Elk adres moet al bestaan in deze mailomgeving
  • lists: Array (optional) | Array<String>. Vervangt de hele lijst. Elk adres moet al bestaan in deze mailomgeving
  • allowed_ips: Array or String (optional) | Array<String>, of één String gescheiden door komma's, puntkomma's of witruimte. Vervangt de hele lijst; maximaal 20 items

Twee controles lopen voordat er iets wordt weggeschreven, en als een van beide faalt, wordt er helemaal niets weggeschreven:

  • Een groups- of lists-adres dat niet bij deze mailomgeving hoort, of niet geverifieerd kan worden, wordt geweigerd met 422 update_failed. Lees de mailbox terug voordat je opnieuw probeert.
  • Een foute allowed_ips-lijst wordt geweigerd met 400 invalid_allowed_ips, met het betreffende item erbij. Items worden genormaliseerd en ontdubbeld, en een bereik met masker wordt opgeslagen in gemaskeerde vorm (10.0.0.5/8 wordt 10.0.0.0/8). Een beperking die niet bij de client past, sluit die credential buiten van webmail en elk apparaat.

Als je status terugzet naar active, wordt de mailboxlimiet van het pakket opnieuw gecontroleerd, net als bij Een mailbox herstellen, wat de voorkeursmanier is.

Teruggegeven params

allowed_ips zit niet in dit antwoord, ook niet als je het hebt gezet. Lees de mailbox terug om de genormaliseerde lijst te zien.

Fouten
  • 400 invalid_allowed_ips | een item is geen geldig adres of bereik, of er zijn er meer dan 20
  • 422 update_failed | de mailserver weigerde de wijziging, een groups/lists-adres hoort niet bij deze mailomgeving of kon niet worden geverifieerd, status: "pending_deletion" is gevraagd op een mailbox die nog niet was ingepland, quota_mb is groter dan het pakket, of een heractivering zou de mailboxlimiet van het pakket overschrijden

Een mailbox verwijderen

DELETE /api/mailspace/:mailspace_id/mailboxes/:id

Scope: mailspace:write.

Soft delete. De mailbox wordt direct geblokkeerd, dus er komt geen mail meer door, en 7 dagen later definitief gewist. Tot dan brengt herstellen hem terug met zijn mail intact. Een mailbox verwijderen die al is ingepland, slaagt en schuift de datum niet op.

Teruggegeven params
  • mailbox: Object | dezelfde vorm als de pending-items in Mailboxen opvragen
    • id: String
    • email: String
    • status: String
    • scheduled_deletion_at: DateTime
    • days_until_deletion: Integer
Fouten
  • 422 delete_failed | de mailserver weigerde de blokkade

Een mailbox herstellen

POST /api/mailspace/:mailspace_id/mailboxes/:id/restore

Scope: mailspace:write.

Heractiveert de mailbox en wist de verwijderdatum. Een actieve mailbox herstellen slaagt en verandert niets.

De mailboxlimiet van het pakket wordt opnieuw gecontroleerd, dus na een downgrade antwoordt een herstel zonder ruimte 422 restore_failed. Resize de mailomgeving omhoog eerst.

Teruggegeven params
  • mailbox: Object | dezelfde vorm als Een mailbox verwijderen; scheduled_deletion_at en days_until_deletion zijn null na een geslaagd herstel
Fouten
  • 422 restore_failed | de mailboxlimiet van het pakket heeft geen ruimte voor hem, of de mailserver weigerde de heractivering

Een mailbox definitief verwijderen

DELETE /api/mailspace/:mailspace_id/mailboxes/:id/force_delete

Scope: mailspace:write.

Onomkeerbaar. Wist de mail van de mailbox nu in plaats van haar herstelbaar te laten voor de rest van de respijtperiode. De mailbox moet al zijn ingepland voor verwijdering met DELETE .../mailboxes/:id; een actieve mailbox wordt geweigerd met 409 not_pending_deletion.

Een 200 bewijst niet dat de mail weg is

Als de mailserver de mail niet nu kan wissen, antwoordt de aanroep toch 200. De mail blijft dan de rest van de bewaartermijn op de server staan en verschijnt in Herstelbare mailboxen opvragen. Vertrouw er niet op dat deze aanroep opslag vrijmaakt vóór een downgrade; controleer de herstelbare lijst.

Teruggegeven params
  • status: String | "deleted"
  • email: String | het adres dat is verwijderd
Fouten
  • 409 not_pending_deletion | de mailbox is niet ingepland voor verwijdering
  • 422 delete_failed | het wissen is niet voltooid. Probeer opnieuw
  • 503 delete_unavailable | het account is verwijderd en mail naar het adres is gestopt, maar CloudPress kon niet bevestigen of de mail nog herstelbaar is. De mailbox blijft ingepland voor verwijdering, en opnieuw proberen is veilig

App-wachtwoorden

Een app-wachtwoord is een zelfstandige IMAP/SMTP/JMAP-credential voor één mailbox. Het blijft werken nadat het eigen wachtwoord van de mailbox verandert, dus het past bij een apparaat of script. Het :id-segment op deze endpoints is het credential-ID (een String), geen GUID.

App-wachtwoorden opvragen

GET /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords

Scope: mailspace:read.

Teruggegeven params
  • app_passwords: Array
    • id: String | het credential-ID, gebruikt bij bijwerken en intrekken
    • description: String | null voor een credential die zonder is aangemaakt
    • allowed_ips: Array | Array<String>; [] betekent dat elk adres met deze credential mag authenticeren
    • created_at: DateTime | kan null zijn

Er is geen tijdstempel van laatste gebruik. Het antwoord bevat nooit secret.

Een app-wachtwoord aanmaken

POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords

Scope: mailspace:write. Geeft 201 Created terug.

Params
  • description: String (required) | waar de credential voor is. Het is de enige manier om er twee van elkaar te onderscheiden bij het intrekken

Het secret wordt exact één keer teruggegeven, hier

secret verschijnt in dit antwoord en nergens anders. Sla het op zodra je het ontvangt; een verloren secret kan alleen worden ingetrokken en vervangen.

Teruggegeven params (201 Created)
  • app_password: Object
    • id: String | het nieuwe credential-ID
    • description: String | zoals ingestuurd, getrimd
    • allowed_ips: Array | bij aanmaken altijd [] — de credential is onbeperkt. Zet die vast met Een app-wachtwoord beperken tot IP-adressen
    • created_at: DateTime | in de aanmaakreactie altijd null
    • secret: String | de enige keer dat dit wordt teruggegeven
Fouten
  • 400 description_blank | description ontbreekt of is leeg
  • 422 app_password_create_failed | de mailserver weigerde het aanmaken

Een app-wachtwoord beperken tot IP-adressen

PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords/:id

Scope: mailspace:write. :id is het credential-ID.

Zet één credential vast op een set adressen. Het raakt nooit het eigen inlogwachtwoord van de mailbox.

Params
  • allowed_ips: Array or String (required) | Array<String>, of één String gescheiden door komma's, puntkomma's of witruimte. Maximaal 20 items. Stuur een lege waarde om de beperking te wissen

allowed_ips is verplicht. Een verzoek zonder de sleutel wordt geweigerd met 400 allowed_ips_missing en schrijft niets weg, omdat een lege lijst onbeperkt betekent en "niet meegestuurd" een credential niet stilletjes mag losmaken. Stuur [], "", null of allowed_ips[]= om de beperking te wissen. De lijst vervangt, ze voegt niet toe. Een fout item is een 400 invalid_allowed_ips zonder dat er iets wordt weggeschreven, en items worden genormaliseerd zoals bij de mailbox.

Teruggegeven params
  • app_password: Object
    • id: String
    • allowed_ips: Array | Array<String> — een genormaliseerde echo van wat is weggeschreven, geen read-back

description en created_at zitten er niet in.

Fouten
  • 400 allowed_ips_missing | de sleutel allowed_ips ontbrak. Er is niets weggeschreven
  • 400 invalid_allowed_ips | een item is geen geldig adres of bereik, of er zijn er meer dan 20. Er is niets weggeschreven
  • 422 app_password_update_failed | de mailserver weigerde de wijziging. Een onbekend credential-ID komt hier terecht, niet als 404

Een app-wachtwoord intrekken

DELETE /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/app_passwords/:id

Scope: mailspace:write.

De credential stopt direct met authenticeren. Het eigen wachtwoord van de mailbox en alle andere app-wachtwoorden blijven ongemoeid.

Teruggegeven params
  • status: String | "revoked"
  • id: String | het credential-ID dat is ingetrokken
Fouten
  • 422 app_password_delete_failed | de mailserver weigerde het intrekken. Een onbekend credential-ID komt hier terecht, niet als 404

Mailregels

De filterregels van een mailbox draaien van boven naar beneden, dus de volgorde van de lijst is de uitvoervolgorde, en stop_processing slaat elke regel eronder over. Verplaatsen verandert het gedrag.

Regels, het afwezigheidsbericht en doorsturen leven allemaal in één filterscript per mailbox. Dat heeft drie gevolgen voor elke write op een van deze drie:

  • Elke muterende reactie geeft de hele regellijst terug. Werk vanuit die lijst; een client die vanuit een verouderde lijst schrijft, verwijdert wat hij vergat. Gelijktijdige writes op één mailbox worden voor je geserialiseerd.
  • Een script dat buiten CloudPress is geschreven, wordt nooit impliciet overschreven. unmanaged: true betekent dat het script met de hand is bewerkt of door een andere mailclient is geschreven. Elke write wordt geweigerd met 409 script_unmanaged tot je Een eigen filterscript overnemen aanroept. Controleer de vlag uit Mailregels opvragen voordat je schrijft. Hij kan ook verschijnen tussen je read en je write.
  • Scriptfouten. Elk regel- en afwezigheidsendpoint behalve de afwezigheidslijst kan 422 mail_rules_unavailable antwoorden (het script kon niet worden gelezen), en elke write kan 422 save_failed antwoorden (het script kon niet worden weggeschreven). Een mislukte write verandert niets.

Een niet-herkende match_type wordt all

match_type accepteert all en any, in kleine letters. Alles anders wordt niet geweigerd: het wordt vervangen door all en de write slaagt, dus een regel die op een willekeurige voorwaarde moest matchen, heeft er nu elke nodig. Lees match_type terug uit het antwoord. Een verkeerd voorwaardeveld field of actietype type wordt geweigerd met 400 invalid_rule.

Regelvocabulaire

Een regel is match_type over een lijst voorwaarden, plus een lijst acties. Meerdere values in één voorwaarde worden met OR gecombineerd, wat match_type ook zegt.

Voorwaardevelden en de comparators die elk daarvan accepteert:

veld comparators opmerkingen
from, to, cc, subject contains, not_contains, is, not_is, starts_with, ends_with, matches
body contains, is
header zoals from hierboven heeft ook header_name nodig
size greater_than, less_than values moeten hele getallen bytes zijn
attachment has_any, has_type has_any heeft geen values nodig

Actietypes: move, copy, forward, mark_read, star, add_label, discard, reject, keep, stop. move, copy, forward, add_label en reject hebben elk een value nodig — een map, een adres, een label of een weigerbericht. Een forward-waarde moet een geldig e-mailadres zijn. Een regel mag hooguit één forward-actie hebben, en niet samen met discard. Zolang doorsturen van de mailbox aanstaat, heeft de forward-actie van een regel geen effect.

Niet alles wat leesbaar is, is ook schrijfbaar. Deze API schrijft alleen de velden from, to, cc, subject, body en de acties move, forward, mark_read, star, discard. Een regel buiten die subset wordt nog steeds vermeld en draait nog steeds, met editable: false. Hij kan aan- of uitgezet, verplaatst of verwijderd worden, maar niet herschreven; zo een regel insturen bij aanmaken of bijwerken wordt geweigerd met 422 unsupported_rule.

Regelnamen zijn verplicht en zijn begrensd op 200 tekens.

Mailregels opvragen

GET /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules

Scope: mailspace:read.

Teruggegeven params
  • mailbox: Object
    • id: String | de mailbox-GUID
    • email: String
  • mail_rules: Array | in uitvoervolgorde
    • id: String | de eigen uuid van de regel
    • name: String | kan leeg zijn bij een elders geschreven regel
    • display_name: String | name, of "Untitled rule" als die leeg is — wat een UI zou moeten tonen
    • enabled: Boolean
    • match_type: String | all (elke voorwaarde moet matchen) of any
    • stop_processing: Boolean
    • editable: Boolean | false als de regel Sieve gebruikt dat deze API niet schrijft. Hij kan nog steeds aan- of uitgezet, verplaatst of verwijderd worden
    • conditions: Array
      • field: String
      • comparator: String
      • values: Array | Array<String>, met OR gecombineerd
      • header_name: String | null tenzij field header is
    • actions: Array
      • type: String
      • value: String | null voor de acties die geen waarde nemen
  • unmanaged: Boolean | true betekent dat het script buiten CloudPress is geschreven en elke write wordt geweigerd tot het is overgenomen

Een mailregel aanmaken

POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules

Scope: mailspace:write. Geeft 201 Created terug.

De nieuwe regel wordt achteraan de lijst toegevoegd. Wil je hem elders hebben, verplaats hem dan.

Params
  • name: String (required) | maximaal 200 tekens
  • enabled: Boolean (optional) | standaard true
  • match_type: String (optional) | all (standaard) of any. Elke andere waarde wordt stil omgezet in all
  • stop_processing: Boolean (optional) | standaard false
  • conditions: Array (optional) | objecten met field, comparator, values (Array<String>) en header_name. Een enkele waarde mag als value in plaats van values worden gestuurd — die wordt als geheel genomen, niet op komma's gesplitst
  • actions: Array (optional) | objecten met type en value

Andere sleutels worden weggelaten. Een regel heeft minstens één voorwaarde en één actie nodig.

Teruggegeven params (201 Created)
  • mail_rule: Object | de aangemaakte regel, in de vorm van Mailregels opvragen
  • mail_rules: Array | de hele nieuwe lijst, in uitvoervolgorde
  • unmanaged: Boolean | altijd false na een geslaagde write
Fouten
  • 400 invalid_rule | een voorwaardeveld field of een actietype type staat niet in het vocabulaire
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over
  • 422 invalid_rule | de regel zou niets matchen: een lege of te lange naam, geen voorwaarden, geen acties, een voorwaarde zonder waarde, een comparator die niet bij het veld past, een header-voorwaarde zonder header_name, een niet-numerieke size, of een forward naar een misvormd adres
  • 422 unsupported_rule | de combinatie kan hier niet worden geschreven — het antwoord noemt de ondersteunde velden en acties
  • 422 forwarding_loop | een forward-actie wijst terug naar deze mailbox (haar adres, een alias, of een +tag van beide), of naar een mailbox in deze mailomgeving die hierheen terugstuurt

Een mailregel bijwerken

PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id

Scope: mailspace:write. Let op: het segment is rule_id, niet id.

Herschrijft één regel op zijn plek, met behoud van zijn ID en positie. Een weggelaten veld behoudt zijn opgeslagen waarde, maar het sturen van conditions of actions vervangt die hele array.

Params
Teruggegeven params
  • mail_rule: Object | de bijgewerkte regel
  • mail_rules: Array | de hele lijst
  • unmanaged: Boolean | false
Fouten
  • De aanmaakfouten, plus:
  • 404 unknown_rule | geen regel met dat ID in het script van deze mailbox
  • 409 rule_not_editable | de opgeslagen regel gebruikt Sieve dat deze API niet kan herschrijven. Aan-/uitzetten, verplaatsen en verwijderen werken er nog wel op
  • 422 invalid_rule | wordt ook gegeven als de opgeslagen regel meer dan één forward-actie heeft, of forward met discard, zelfs als je alleen name stuurde. Verwijder de extra actie

Een mailregel verwijderen

DELETE /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id

Scope: mailspace:write.

Verwijdert één regel. Werkt op een regel die niet editable is.

Teruggegeven params
  • deleted_rule_id: String
  • mail_rules: Array | de resterende lijst
  • unmanaged: Boolean | false
Fouten
  • 404 unknown_rule | geen regel met dat ID in het script van deze mailbox
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over

Een mailregel aan- of uitzetten

PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id/toggle

Scope: mailspace:write.

Een uitgezette regel behoudt zijn plek en instellingen maar heeft geen effect. Werkt op een regel die niet editable is.

Params
  • enabled: Boolean (optional) | zet de status expliciet

Als je enabled weglaat, wisselt de regel om

Zonder enabled schakelt het endpoint de huidige status om, dus een opnieuw verstuurd verzoek zet de regel terug. Stuur enabled altijd expliciet mee.

Teruggegeven params
  • mail_rule: Object | de omgezette regel
  • mail_rules: Array | de hele lijst
  • unmanaged: Boolean | false
Fouten
  • Identiek aan Een mailregel verwijderen, plus:
  • 422 forwarding_loop | het aanzetten van een regel waarvan de forward-actie terugwijst naar deze mailbox

Een mailregel verplaatsen

PATCH /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/:rule_id/move

Scope: mailspace:write.

Verplaatst één regel één plek omhoog of omlaag. Wil je verder, herhaal dan de aanroep. Werkt op een regel die niet editable is.

Params
  • direction: String (required) | up of down
Teruggegeven params
  • mail_rule: Object | de verplaatste regel
  • mail_rules: Array | de hele lijst, in zijn nieuwe uitvoervolgorde
  • unmanaged: Boolean | false
Fouten
  • 400 invalid_direction | direction ontbreekt of is niet up of down. Gecontroleerd voordat het script wordt gelezen
  • 404 unknown_rule | geen regel met dat ID in het script van deze mailbox
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over
  • 422 invalid_move | de regel is al de eerste en werd omhoog verplaatst, of al de laatste en werd omlaag verplaatst

Een eigen filterscript overnemen

POST /api/mailspace/:mailspace_id/mailboxes/:mailbox_id/mail_rules/adopt

Scope: mailspace:write. Dit is een collectieroute — er is geen rule_id.

Neemt een filterscript over dat deze API niet heeft geschreven, en vervangt het door de regels die eruit geparsed konden worden. Dit geeft ook de writes voor het afwezigheidsbericht en doorsturen vrij.

Overnemen is destructief en kan niet worden teruggedraaid

Alles in het eigen script van de klant dat het regelmodel niet kan weergeven, is daarna weg. Roep eerst Mailregels opvragen aan en laat een mens zien wat er op het punt staat te worden vervangen. Op een script dat al beheerd wordt, is het een onschuldige no-op en antwoordt het 200.

Teruggegeven params
  • adopted: Boolean | true
  • mail_rules: Array | wat het script nu bevat
  • unmanaged: Boolean | vanaf hier false

Dit endpoint antwoordt nooit script_unmanaged.


Afwezigheidsberichten

Eén bericht per mailbox, opgeslagen in hetzelfde script als de filterregels, dus de scriptregels hierboven (inclusief script_unmanaged en één overname) gelden hier. Er is geen POST-route: Een afwezigheidsbericht instellen maakt aan en wijzigt. Het routesegment mailbox_id is de mailbox-GUID.

Afwezigheidsstatus opvragen

GET /api/mailspace/:mailspace_id/vacation_responses

Scope: mailspace:read.

Eén rij per mailbox, op adres gesorteerd. Mailboxen die ingepland staan voor verwijdering worden weggelaten. Antwoordt uit een gecachte samenvatting die wordt ververst zodra het script via CloudPress wordt gelezen of geschreven, dus een elders gewijzigd script is hier verouderd. Gebruik voor de live status Een afwezigheidsbericht bekijken.

Teruggegeven params
  • vacation_responses: Array
    • mailbox_id: String | de mailbox-GUID
    • email: String
    • synced: Boolean | false betekent dat deze mailbox helemaal geen gecachte samenvatting heeft
    • configured: Boolean | er bestaat een bericht
    • enabled: Boolean | het staat aan
    • from_date: String | YYYY-MM-DD, of null voor geen ondergrens
    • to_date: String | YYYY-MM-DD, of null voor geen bovengrens

Controleer synced voordat je de rij gelooft

Bij synced: false zijn configured en enabled false en de datums null — precies zoals bij een mailbox zonder bericht. Behandel het als "onbekend" en lees het eigen bericht van die mailbox. Deze lijst heeft geen unmanaged-vlag; de read per mailbox wel.

Een afwezigheidsbericht bekijken

GET /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id

Scope: mailspace:read. Live gelezen uit het script van de mailbox.

Teruggegeven params
  • vacation_response: Object
    • mailbox_id: String | de mailbox-GUID
    • email: String
    • configured: Boolean | er bestaat een bericht
    • enabled: Boolean | het staat aan
    • subject: String | null zodra het leeg is
    • text_body: String | null als het niet is ingesteld
    • html_body: String | null als het niet is ingesteld. Clients die HTML renderen, geven dit de voorkeur boven text_body
    • from_date: String | YYYY-MM-DD, of null
    • to_date: String | YYYY-MM-DD, of null
  • unmanaged: Boolean | true betekent dat het script buiten CloudPress is geschreven en writes worden geweigerd tot het is overgenomen

Een bericht kan geschreven zijn en uit staan, dus configured en enabled zijn aparte vlaggen. configured: false met lege velden betekent dat er geen bericht is.

Een afwezigheidsbericht instellen

PATCH /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id

Scope: mailspace:write. Een upsert — dezelfde aanroep maakt aan en wijzigt.

Elk veld is optioneel. Een veld weglaten houdt zijn opgeslagen waarde; stuur een lege string om er een te wissen. {"enabled": false} zet het bericht uit en laat de tekst ongemoeid.

Params
  • enabled: Boolean (optional) | of het bericht uitgaat. Standaard true voor een mailbox die nog geen bericht heeft
  • subject: String (optional)
  • text_body: String (optional)
  • html_body: String (optional) | stuur "" om geen HTML-versie meer te sturen
  • from_date: String (optional) | YYYY-MM-DD. Het bericht antwoordt alleen binnen dat venster
  • to_date: String (optional) | YYYY-MM-DD

Datums zijn hele dagen in ISO 8601; een datumtijd wordt teruggebracht tot de datum. Alles anders is een 400 invalid_date. Een bericht aanzetten zonder onderwerp en zonder body wordt geweigerd met 422 vacation_body_required. Gebruik DELETE om een bericht te verwijderen.

Teruggegeven params
Fouten
  • 400 invalid_date | from_date of to_date is geen geldige datum. Er is niets weggeschreven
  • 409 script_unmanaged | het script is buiten CloudPress geschreven. Neem het eerst over; er is geen apart overnamepad voor het bericht
  • 422 vacation_body_required | een aangezet bericht zonder onderwerp en zonder body

Een afwezigheidsbericht verwijderen

DELETE /api/mailspace/:mailspace_id/vacation_responses/:mailbox_id

Scope: mailspace:write.

Verwijdert het bericht en laat de filterregels zoals ze waren. Een bericht verwijderen dat niet bestaat, antwoordt 200.

Teruggegeven params
Fouten
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over

Doorsturen

Stuur elk bericht dat een mailbox ontvangt door naar één ander adres. Doorsturen wordt opgeslagen in hetzelfde script als de filterregels en het afwezigheidsbericht, dus script_unmanaged en een script overnemen gelden hier ook. Er is geen POST-route: Doorsturen instellen maakt aan en wijzigt. Het segment mailbox_id is de mailbox-GUID.

Zolang doorsturen aanstaat, heeft de forward-actie van een regel op dezelfde mailbox geen effect. rule_forward_addresses noemt die bestemmingen.

Elk doorstuurendpoint behalve de lijst kan ook 409 mailbox_not_provisioned antwoorden (de mailbox heeft nog geen account op de mailserver; probeer niet opnieuw) en 503 forwarding_unavailable (het script kon niet worden gelezen).

Doorsturen opvragen

GET /api/mailspace/:mailspace_id/forwardings

Scope: mailspace:read.

Eén rij per mailbox, op adres gesorteerd. Mailboxen die ingepland staan voor verwijdering worden weggelaten. De lijst is gecachet, dus een script dat buiten CloudPress is gewijzigd, is hier verouderd. Gebruik voor de live status Doorsturen bekijken.

Teruggegeven params
  • forwardings: Array
    • mailbox_id: String | de mailbox-GUID
    • email: String
    • synced: Boolean | false betekent dat deze mailbox helemaal geen gecachte samenvatting heeft
    • configured: Boolean | er is een doorstuuradres ingesteld
    • enabled: Boolean | doorsturen staat aan
    • address: String | de bestemming, of null
    • keep_copy: Boolean | of het bericht ook in deze mailbox blijft

Bij synced: false zijn de andere velden null, wat "onbekend" betekent, niet "geen doorsturen". Lees in plaats daarvan het doorsturen van die mailbox.

Doorsturen bekijken

GET /api/mailspace/:mailspace_id/forwardings/:mailbox_id

Scope: mailspace:read. Live gelezen uit het script van de mailbox.

Teruggegeven params
  • forwarding: Object
    • mailbox_id: String | de mailbox-GUID
    • email: String
    • configured: Boolean | er is een doorstuuradres ingesteld
    • enabled: Boolean | doorsturen staat aan
    • address: String | de bestemming. null als configured false is
    • keep_copy: Boolean | false betekent dat er niets in de mailbox wordt bewaard en de filterregels ervan niet draaien
  • rule_forward_addresses: Array | Array<String>: adressen waarnaar de ingeschakelde regels van deze mailbox doorsturen
  • unmanaged: Boolean | true betekent dat writes worden geweigerd tot het script is overgenomen

Een adres kan zijn opgeslagen (configured: true) terwijl doorsturen uit staat (enabled: false).

Doorsturen instellen

PATCH /api/mailspace/:mailspace_id/forwardings/:mailbox_id

Scope: mailspace:write. Maakt doorsturen aan of wijzigt het. Elk veld is optioneel; een weggelaten veld behoudt zijn opgeslagen waarde, dus {"enabled": false} zet doorsturen uit en bewaart het adres.

Params
  • enabled: Boolean (optional) | of mail wordt doorgestuurd. Standaard true voor een mailbox zonder doorsturen
  • address: String (optional) | het e-mailadres van de bestemming. "" verwijdert doorsturen, net als DELETE
  • keep_copy: Boolean (optional) | of het bericht ook in deze mailbox blijft. Standaard true
Teruggegeven params
Fouten
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over
  • 422 invalid_address | address is geen geldig e-mailadres
  • 422 forwarding_loop | het adres is deze mailbox, een van haar aliassen of een +tag van beide, of een ingeschakelde doorstuurregel zou via een andere mailbox in deze mailomgeving terugkomen
  • 422 save_failed | het script kon niet worden weggeschreven

Doorsturen verwijderen

DELETE /api/mailspace/:mailspace_id/forwardings/:mailbox_id

Scope: mailspace:write.

Verwijdert alleen doorsturen; filterregels en het afwezigheidsbericht blijven ongemoeid. Doorsturen verwijderen dat niet is ingesteld, antwoordt 200.

Teruggegeven params
  • Dezelfde vorm als Doorsturen bekijken, met doorsturen nu gewist — configured, enabled en keep_copy false, address null
Fouten
  • 409 script_unmanaged | het script is buiten CloudPress geschreven — neem het eerst over
  • 422 save_failed | het script kon niet worden weggeschreven

Foutcodes

Alle fouten gebruiken de envelop {"errors": [...], "code": "..."} uit Foutreacties, behalve een onbekende of niet-zichtbare mailspace-GUID, die een kale 404 met een lege body teruggeeft. De codes die elk endpoint deelt, staan in Gedeelde controles.

Code Status Geretourneerd door
unknown_mailbox 404 elk endpoint dat een mailbox noemt
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 — de sleutel is helemaal niet meegestuurd
create_failed 422 mailbox create
update_failed 422 mailbox update
delete_failed 422 mailbox delete, mailbox force_delete
delete_unavailable 503 mailbox force_delete — het verwijderen ging door, de registratie van de herstelbaarheid niet
mailboxes_unavailable 503 mailboxen opvragen — de live read kon niet worden uitgevoerd. Geen lege mailomgeving
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 bij een onbekend veld of een onbekende actie, 422 bij een regel die niets zou matchen
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 elke mail-rule write behalve adopt; out-of-office- en forwarding-update, delete
mail_rules_unavailable 422 elk mail-rule- en out-of-office-endpoint behalve de out-of-office-lijst
save_failed 422 elke mail-rule-, out-of-office- en forwarding-write
forwarding_loop 422 forwarding update; mail-rule create, update, toggle
forwarding_unavailable 503 elk forwarding-endpoint behalve de lijst
mailbox_not_provisioned 409 elk forwarding-endpoint behalve de lijst
invalid_date 400 out-of-office update
vacation_body_required 422 out-of-office update

Foutmeldingen zijn altijd Engels, ook met een Accept-Language-header — vertak op code, niet op de melding.