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
404unknown_mailboxals die niet in deze mailomgeving zit, dus een GUID van een andere workspace is een404, geen403. De endpoints voor app-wachtwoorden, mailregels, afwezigheidsberichten en doorsturen geven dezelfde404voor een mailbox die ingepland staat voor verwijdering. Herstel die eerst. - Writes worden bepaald door de HTTP-verb. Alles behalve
GETenHEADis een write, inclusiefrestore,force_delete,toggle,moveenadopt. Een lid met alleen leesrechten en eenmailspace:write-token krijgt op al deze403not_authorized. EenHEAD-verzoek geeft dezelfde status als de bijbehorendeGET. Het recht wordt gecontroleerd op de workspace die de mailomgeving bezit, niet op die inX-Auth-Account. - Bewaartermijn. Nadat je een mailomgeving hebt verwijderd, blijven reads de hele
bewaartermijn werken en antwoordt elke write
403pending_delete. Herstel de mailomgeving om weer te kunnen schrijven. Een mailomgeving die zowel geblokkeerd is als ingepland staat voor verwijdering antwoordt een write metpending_deleteen een read met200. - Verschillen met de endpoints op planniveau.
pending_deleteis hier403(422op Mailspace) ennot_provisionedis409(422daar). Een geweigerd recht is hier{"errors":["Not Authorized"],"code":"not_authorized"}; de endpoints op planniveau sturen geencode. Vertak op de code, niet op de status alleen.
Leesacties die leeg kunnen terugkomen
- Mailboxen opvragen is strikt: als de mailboxen niet gelezen
kunnen worden, antwoordt het
503mailboxes_unavailable, nooit een lege lijst. Zie Leesfouten. - Een mailbox bekijken en
App-wachtwoorden opvragen zijn toegeeflijk: als de
mailserver onbereikbaar is, antwoorden ze
200met lege waarden. Zie een leeg resultaat niet als bewijs, en verwijder niets op basis daarvan alleen. - Afwezigheidsstatus opvragen en
Doorsturen opvragen antwoorden uit een gecachte samenvatting.
Controleer
synced, en lees de afzonderlijke mailbox voor de live status.
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—pendingwordt 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 |
activeofsuspended - quota_mb: Integer |
0betekent 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 |
nullop 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;
nullals 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, nietsales@example.com - domain: String (optional) | standaard het eigen maildomein van de mailomgeving
Teruggegeven params
- available: Boolean |
true,falseofnull— zie de waarschuwing hieronder - used_by: String |
"mailbox","group"of"mailing list", ofnullals 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|usernameis 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, enscheduled_deletion_atis 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
- alle velden uit de
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
domainvormt 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
- de
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|usernameontbreekt of is leeg - 400
password_blank|passwordontbreekt of is leeg. Gecontroleerd nausername_blank - 422
create_failed| de mailbox kon niet worden aangemaakt. Deerrors-melding zegt waarom: de mailboxlimiet van het pakket is bereikt,quota_mbis groter dan het pakket, het adres is al in gebruik door een mailbox, groep of mailinglijst in deze mailomgeving, eengroups- oflists-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 getal0om de limiet per mailbox te verwijderen - status: String (optional) |
activeofsuspended.pending_deletionwordt 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- oflists-adres dat niet bij deze mailomgeving hoort, of niet geverifieerd kan worden, wordt geweigerd met422update_failed. Lees de mailbox terug voordat je opnieuw probeert. - Een foute
allowed_ips-lijst wordt geweigerd met400invalid_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/8wordt10.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
- mailbox: Object | identiek aan Een mailbox aanmaken
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, eengroups/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_mbis 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_atendays_until_deletionzijnnullna 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 |
nullvoor een credential die zonder is aangemaakt - allowed_ips: Array |
Array<String>;[]betekent dat elk adres met deze credential mag authenticeren - created_at: DateTime | kan
nullzijn
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|descriptionontbreekt 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 sleutelallowed_ipsontbrak. 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 als404
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 als404
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: truebetekent dat het script met de hand is bewerkt of door een andere mailclient is geschreven. Elke write wordt geweigerd met409script_unmanagedtot 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
422mail_rules_unavailableantwoorden (het script kon niet worden gelezen), en elke write kan422save_failedantwoorden (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) ofany - stop_processing: Boolean
- editable: Boolean |
falseals 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 |
nulltenzijfieldheaderis
- actions: Array
- type: String
- value: String |
nullvoor de acties die geen waarde nemen
- unmanaged: Boolean |
truebetekent 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) ofany. Elke andere waarde wordt stil omgezet inall - stop_processing: Boolean (optional) | standaard
false - conditions: Array (optional) | objecten met
field,comparator,values(Array<String>) enheader_name. Een enkele waarde mag alsvaluein plaats vanvaluesworden gestuurd — die wordt als geheel genomen, niet op komma's gesplitst - actions: Array (optional) | objecten met
typeenvalue
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
falsena een geslaagde write
Fouten
- 400
invalid_rule| een voorwaardeveldfieldof een actietypetypestaat 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, eenheader-voorwaarde zonderheader_name, een niet-numeriekesize, of eenforwardnaar een misvormd adres - 422
unsupported_rule| de combinatie kan hier niet worden geschreven — het antwoord noemt de ondersteunde velden en acties - 422
forwarding_loop| eenforward-actie wijst terug naar deze mailbox (haar adres, een alias, of een+tagvan 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
- Dezelfde velden als Een mailregel aanmaken, allemaal optioneel
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 éénforward-actie heeft, offorwardmetdiscard, zelfs als je alleennamestuurde. 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 deforward-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) |
upofdown
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|directionontbreekt of is nietupofdown. 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 |
falsebetekent 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, ofnullvoor geen ondergrens - to_date: String |
YYYY-MM-DD, ofnullvoor 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 |
nullzodra het leeg is - text_body: String |
nullals het niet is ingesteld - html_body: String |
nullals het niet is ingesteld. Clients die HTML renderen, geven dit de voorkeur boventext_body - from_date: String |
YYYY-MM-DD, ofnull - to_date: String |
YYYY-MM-DD, ofnull
- unmanaged: Boolean |
truebetekent 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
truevoor 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
- Dezelfde vorm als Een afwezigheidsbericht bekijken, met
unmanagedaltijdfalsena een geslaagde write
Fouten
- 400
invalid_date|from_dateofto_dateis 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
- Dezelfde vorm als Een afwezigheidsbericht bekijken, met het bericht nu gewist —
configuredenenabledfalse, elk ander veldnull
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 |
falsebetekent 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.
nullalsconfiguredfalseis - keep_copy: Boolean |
falsebetekent 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 |
truebetekent 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
truevoor een mailbox zonder doorsturen - address: String (optional) | het e-mailadres van de bestemming.
""verwijdert doorsturen, net alsDELETE - keep_copy: Boolean (optional) | of het bericht ook in deze mailbox blijft. Standaard
true
Teruggegeven params
- Dezelfde vorm als Doorsturen bekijken, met
unmanagedaltijdfalsena een geslaagde write
Fouten
- 409
script_unmanaged| het script is buiten CloudPress geschreven — neem het eerst over - 422
invalid_address|addressis geen geldig e-mailadres - 422
forwarding_loop| het adres is deze mailbox, een van haar aliassen of een+tagvan 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,enabledenkeep_copyfalse,addressnull
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.