Ga naar inhoud

Mailspace-adressen

Deze endpoints beheren waaraan mail geadresseerd kan worden binnen één mailomgeving: aliassen, distributiegroepen, mailinglijsten en verhulde (wegwerp-)doorstuuradressen. Het aanschaffen, bekijken, resizen en verwijderen van de mailomgeving zelf valt onder de endpoints op planniveau op Mailspace.

Elk pad op deze pagina begint met /api/mailspace/:mailspace_id/…, waarbij :mailspace_id de GUID van de mailomgeving is uit GET /api/mailspace.

OAuth-scopes: reads vereisen mailspace:read, writes vereisen mailspace:write. Sessie- en API-sleutel-credentials slaan de scopecontroles volledig over (zie OAuth). Een OAuth-token zonder de vereiste scope wordt geweigerd met 403 {"error":"insufficient_scope", ...} — let op: dat is de OAuth-foutenvelop, niet de envelop {"errors":[...],"code":"..."} die elke andere fout op deze pagina gebruikt. Zie Scope-handhavingsfouten.

Alles op deze pagina wordt bij elk verzoek live van de mailserver gelezen, niet uit een lokale spiegel. Alle indexendpoints hier zijn niet gepagineerd — page en per_page hebben geen effect — maar ze zijn niet onbegrensd; zie hieronder.

Een index is begrensd, en een lege lijst bewijst niet dat er niets is

Een principal-read is begrensd op 500 rijen en verhulde adressen op 2000; alles voorbij die grens valt weg, zonder dat er iets in de reactie op wijst. Geen van beide grenzen is begrensd zoals hij lijkt — lees verder, en zie Verhulde adressen voor de 2000, die serverbreed wordt toegepast in plaats van op deze mailomgeving.

De 500 is geen grens per principal-type. Mailboxen en groepen zijn op de mailserver hetzelfde soort object, onderscheiden door een typemarkering, en één begrensde query haalt ze allebei op — de splitsing in mailboxen en groepen gebeurt nadat de 500 rijen al gekozen zijn. Een mailomgeving met 500 of meer mailboxen kan dus 200 antwoorden met nul groepen, en met geen enkel groepsalias in de aliasinventaris, terwijl haar groepen bestaan en prima werken. member_count wordt om dezelfde reden te laag gerapporteerd: dat wordt geteld uit datzelfde begrensde stel principals, dus leden buiten dat venster worden niet meegeteld. Mailinglijsten zijn een apart object met hun eigen grens en hebben dus geen last van het aantal mailboxen.

De grens is de enige manier waarop deze lijsten nog stil te kort zijn. Een read die niet kón worden uitgevoerd wordt gemeld en niet verborgen: GET .../aliases, GET .../groups en GET .../mailing_lists zijn strikt en antwoorden 503 met een code die de mislukte read benoemt — aliases_unavailable, groups_unavailable, mailing_lists_unavailable — in plaats van 200 zonder rijen. Een lege collectie op die drie is dus gezaghebbend, en je kunt je administratie ermee verzoenen. GET .../masked_emails is de uitzondering en antwoordt nog steeds 200 met nul rijen als die read mislukt.

Groepen opvragen heeft een tweede code, group_members_unavailable, voor het geval dat de groepen wél terugkwamen maar de ledenaantallen niet — het endpoint weigert member_count: 0 te melden voor elke groep wanneer het er niet naar kon vragen. Zie Leesfouten.

Eén groep of mailinglijst op id lezen werkt precies andersom. Een mislukte read is niet te onderscheiden van "die principal bestaat niet", en een zachter antwoord zou een id bevestigen dat bij een andere tenant kan horen, dus valt die dicht terug op 404 — nooit een object met lege velden. Eén 404 daar is dus geen bewijs dat de groep of lijst weg is; de index is de gezaghebbende controle.

Eén platte adresnaamruimte per mailomgeving

Mailboxadressen, aliasadressen, groepsadressen en mailinglijstadressen delen dezelfde naamruimte binnen de hele mailomgeving, en die naamruimte omvat de aliassen van elke principal. Geen twee ervan kunnen hetzelfde adres zijn: een adres dat slechts een alias van een mailinglijst is, is niet beschikbaar voor een nieuwe mailbox, groep of alias.

Een alias aanmaken op een adres dat al bezet is, wordt vóór er iets wordt geschreven geweigerd, met 422 invalid_alias en een melding die noemt wat het adres bezet houdt (een mailbox, een groep of een mailinglijst). Een groep of mailinglijst aanmaken op een bezet adres wordt door de mailserver zelf geweigerd, wat naar buiten komt als 422 group_create_failed / mailing_list_create_failed.

Gedeelde controles

Elk endpoint op deze pagina erft dezelfde keten van controles, in deze volgorde toegepast voordat de actie draait. De eerste controle die faalt, beantwoordt het verzoek. De OAuth-scopecontrole loopt vóór al deze controles, dus een token met te weinig scope komt hier helemaal niet aan.

Geldt voor Voorwaarde Reactie
alle mailhosting is niet geconfigureerd op het platform 503 stalwart_unavailable
alle :mailspace_id is onbekend, of niet zichtbaar voor je credential 404, lege body
writes de gebruiker heeft geen bewerkrecht op de eigen workspace van de mailomgeving 403 not_authorized
alle de mailomgeving is geblokkeerd (door support of wegens een onbetaalde factuur) 403 mailspace_suspended
writes de mailomgeving is met soft delete verwijderd (wacht op verwijdering) 403 pending_delete
alle de mailomgeving is nog niet voorzien 409 not_provisioned

Een write wordt bepaald door de HTTP-methode, niet door het endpoint

De twee write-controles beslissen op basis van de request-methode: GET en HEAD gaan er zo door, al het andere wordt gecontroleerd. Een lid met alleen leesrecht dat een mailspace:write-token heeft, kan dus prima aliassen, groepen, mailinglijsten en verhulde adressen opvragen, en krijgt 403 not_authorized op elke POST, PATCH en DELETE — aan de scope van het token is voldaan, aan het recht van het lid niet.

HEAD wordt precies als GET behandeld, dus een read-endpoint aftasten met HEAD geeft dezelfde status als de GET zou geven.

Reads overleven de bewaartermijn, writes niet

Een met soft delete verwijderde mailomgeving (die op verwijderen wacht) blijft zijn hele bewaartermijn reads beantwoorden — je kunt zijn aliassen, groepen, lijsten en verhulde adressen nog opvragen. Elke mutatie wordt geweigerd met 403 pending_delete totdat de mailomgeving is hersteld. Zie Een mailomgeving verwijderen.

Een geblokkeerde mailomgeving gedraagt zich anders: mailspace_suspended blokkeert reads net zo goed als writes. Een mailomgeving die op verwijderen wacht, is van die controle uitgezonderd, dus de twee codes gelden nooit samen.

Een onbekende of buiten je bereik vallende :mailspace_id antwoordt 404 met een lege body, niet met de gebruikelijke foutenvelop — een GUID van een andere workspace moet niet te onderscheiden zijn van een die niet bestaat.

Aliassen

Een alias is een extra adres dat aflevert bij een bestaande mailbox, groep of mailinglijst. Het is geen object op de mailserver — het is een vermelding in het veld aliases van de principal waar het naar wijst — dus er is geen id om het mee te benaderen, en de aliasinventaris is een afgeleide join over alle drie de principal-types.

Een alias mag alleen naar een primair adres wijzen, nooit naar een andere alias, dus aliasketens zijn altijd precies één niveau diep.

Aliassen opvragen

GET /api/mailspace/:mailspace_id/aliases

Elke alias in de mailomgeving, samengevoegd over mailboxen, groepen en mailinglijsten en gesorteerd op aliasadres. Het primaire adres van een principal komt hier nooit in terug — alleen zijn aliassen.

Params
  • q: String (optional) | hoofdletterongevoelig filter op deelstring, gematcht tegen óf het aliasadres óf het doeladres
Teruggegeven params
  • aliases: Array
    • address: String | de alias zelf, in kleine letters
    • target_email: String | het primaire adres waar hij bij aflevert
    • target_name: String | de omschrijving van het doel, met terugval op het local part dat de mailserver bewaart; null als het geen van beide heeft
    • target_type: String | mailbox, group, of list
    • target_id: String | het principal-id van het doel op de mailserver

Elke key is altijd aanwezig; een waarde die onbekend is, is null.

Fouten
  • 503 aliases_unavailable | de mailserver kon niet worden gelezen. De drie reads achter deze lijst delen één lot, dus een leeg aliases-array is gezaghebbend — zie Leesfouten
  • plus de gedeelde controles

Een alias aanmaken

POST /api/mailspace/:mailspace_id/aliases

Laat een nieuwe alias naar een bestaande mailbox, groep of mailinglijst wijzen. Geeft 201 Created terug.

De write is een read-modify-write van de hele aliasset van het doel, dus de bestaande aliassen van het doel blijven bewaard.

Params
  • address: String (required) | het aliasadres. Een los local part wordt voor je gekwalificeerd — zie domain hieronder.
  • domain: String (optional) | wordt alleen gebruikt wanneer address geen @ bevat. Wordt volledig genegeerd bij een volledig gekwalificeerde address. Als address geen @ heeft en er geen domain is meegegeven, wordt het primaire domein van de mailomgeving gebruikt.
  • target_email: String (required) | het primaire adres van de mailbox, groep of mailinglijst waar de alias bij moet afleveren. Een alias wordt niet als doel geaccepteerd.
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address": "hello@example.com", "target_email": "ann@example.com"}' \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/aliases
Teruggegeven params (201 Created)

De service geeft geen object terug — de write past de aliasset van de doelprincipal aan — dus de reactie echoot het paar dat is vastgelegd:

  • alias: Object
    • address: String | de alias, in kleine letters
    • target_email: String | het primaire doeladres, in kleine letters
Fouten
  • 400 address_blank | geen aliasadres meegegeven
  • 400 target_blank | geen doeladres meegegeven
  • 422 invalid_alias | een echte weigering: het aliasdomein is geen domein van deze mailomgeving, het adres is al ergens in de mailomgeving in gebruik, het adres is geen geldig e-mailadres, of target_email is hier geen mailbox, groep of mailinglijst
  • 503 aliases_unavailable | een van die controles kon niet worden gedaan, of de write zelf kreeg geen antwoord. Het opnieuw proberen waard, en onbepaald op de write — de alias is mogelijk aangemaakt
  • plus de gedeelde controles

invalid_alias betekent dat de mailserver heeft geantwoord en heeft geweigerd

Alle vier de controles zijn live reads, en een read die niet kon worden uitgevoerd antwoordt in plaats daarvan 503 aliases_unavailable — deze code staat dus nooit voor "we konden het niet vragen". Dat is vooral belangrijk bij de domeincontrole, die vooraan staat: bij een onbereikbare mailserver meldde die dat het domein "geen domein van deze mailomgeving" is, een stellige en handelbaar lijkende bewering over je eigen configuratie die CloudPress niet kon doen.

errors[0] is samengestelde tekst en niet de eigen string van de mailserver, er valt dus niets in te ontleden. Vertak op code.

Omdat de 503 ook de write dekt, lees Aliassen opvragen opnieuw in plaats van een fout aan een gebruiker te melden. De write vervangt de hele aliasverzameling van het doel, dus herhalen is veilig.

Een alias verwijderen

DELETE /api/mailspace/:mailspace_id/aliases/:address

Verwijdert één alias. De principal waar hij naar wees, en elke andere alias op die principal, blijven ongemoeid. Geeft 200 terug.

Het adres zelf is de sleutel — er is geen alias-id om te gebruiken. De match is hoofdletterongevoelig, en een :address die het primaire adres van een principal is, geeft 404 unknown_alias en nooit een verwijdering — een primair adres is geen alias, en het weghalen zou de mailbox, groep of mailinglijst zonder eigen adres achterlaten. Verwijder in dat geval het object zelf.

De URL opbouwen voor een adres met punten

Het segment :address is beperkt tot "een of meer tekens die geen / zijn", en dat is precies wat een volledig e-mailadres erdoor laat. Twee gevolgen voor een client:

  • @ en . hoeven niet te worden geëscaped, en de match is greedy — een .com aan het einde wordt dus niet opgevat als formaatextensie, zoals een standaard padsegment dat wel zou doen. DELETE /api/mailspace/$ID/aliases/sales@example.com is het juiste verzoek.
  • Een adres dat een / bevat, is helemaal niet bereikbaar; het segment stopt bij de eerste slash.
curl -X DELETE \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/aliases/sales@example.com
Teruggegeven params
  • deleted: Boolean | altijd true
  • address: String | de alias die is verwijderd, in kleine letters
  • target_email: String | het primaire adres van de principal die hem had
Fouten
  • 404 unknown_alias | de mailserver is gevraagd en geen enkele principal in deze mailomgeving heeft die alias. Gezaghebbend
  • 422 alias_remove_failed | de alias is gevonden maar de write is geweigerd. errors[0] is samengestelde tekst, niet de eigen string van de mailserver
  • 503 aliases_unavailable | de eigenaarslookup kon niet worden uitgevoerd, of de write kreeg geen antwoord. Op het lookup-pad wordt geen write geprobeerd; op het write-pad kan de verwijdering wél zijn doorgekomen. Een alias verwijderen die al weg is verandert niets, dus opnieuw proberen is veilig
  • plus de gedeelde controles

De 404 is gezaghebbend, en dat is een bewuste vormverandering

De eigenaarslookup loopt vóór elke write en is strikt, dus unknown_alias betekent dat de mailserver is gevraagd. Een lookup die niet kon worden uitgevoerd antwoordt in plaats daarvan 503: een 404 is een definitief antwoord, en dat mag niet worden gegeven op een vraag die nooit is gesteld.

Groepen

Een distributiegroep is een principal op de mailserver met zijn eigen adres; mail die ernaartoe wordt gestuurd, wordt aan elk lid afgeleverd. Een groep heeft geen lokale databaserij, dus hij wordt benaderd via zijn principal-id op de mailserver — het segment :stalwart_id, dat het veld id is van elk groepsobject hieronder.

Een groep mag alleen mailboxen bevatten die in deze mailomgeving worden gehost

Groepslidmaatschap gaat per principal, dus een adres dat de mailserver hier niet kan oplossen, zou stil worden weggelaten. In plaats daarvan wordt de hele write geweigerd, met 422 group_create_failed / group_update_failed. Wil je een adres van buiten opnemen, gebruik dan een mailinglijst.

:stalwart_id wordt tegen je tenant gecontroleerd

De op-id-aanroepen van de mailserver hebben geen tenantfilter, dus show, update en destroy bevestigen dat de principal bij de tenant van deze mailomgeving hoort voordat ze eraan raken, en antwoorden anders 404 unknown_group. Een id dat de mailserver niet kent en een id van een andere workspace geven dezelfde 404 — en een id waarover de mailserver helemaal niet bevraagd kon worden ook. De controle valt dicht terug: een principal die niet gelezen kan worden, is geen bewijs van eigendom, en een zachter antwoord zou het id van een andere tenant bevestigen.

Groepen opvragen

GET /api/mailspace/:mailspace_id/groups

Params
  • q: String (optional) | hoofdletterongevoelig filter op deelstring, gematcht tegen het primaire adres of de omschrijving van de groep. Aliassen en het bewaarde local part worden niet doorzocht.
Teruggegeven params
  • groups: Array
    • id: String | principal-id op de mailserver — dit is de :stalwart_id waarmee je de groep benadert
    • name: String | het local part dat de mailserver bewaart. Dit is niet de weergavenaam en kan niet worden gewijzigd.
    • email: String | primair adres
    • aliases: Array | Array<String> met de aliasadressen van de groep
    • description: String | de weergavenaam, null als die niet is ingesteld
    • member_count: Integer | het aantal lidmailboxen, nooit null. De aantallen worden strikt gelezen, dus een aantal dat niet gelezen kan worden levert 503 op in plaats van een valse nul — maar het aantal wordt geteld uit hetzelfde venster van 500 rijen als de lijst zelf, dus op een mailomgeving op of voorbij die grens kan het lager zijn dan het werkelijke aantal leden. Lees de groep zelf voor een ledenlijst waar je iets mee gaat doen.

De leden zelf staan hier niet bij — vraag één groep op om die te krijgen.

Fouten
  • 503 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
  • 503 group_members_unavailable | de groepen kwamen terug maar de ledenaantallen niet. Met de groepen zelf is niets mis — probeer het opnieuw
  • plus de gedeelde controles

Twee codes, en welke je krijgt zegt welke read mislukte

Geen van beide is een leeg array: dit endpoint zakt niet terug naar een lege 200. De splitsing bestaat zodat "we weten niets over je groepen" en "we weten je groepen wel, maar niet hoeveel leden ze hebben" nooit als hetzelfde worden gemeld. Zie Leesfouten.

Een groep bekijken

GET /api/mailspace/:mailspace_id/groups/:stalwart_id

Teruggegeven params
  • group: Object
    • alle velden uit Groepen opvragen behalve member_count, plus:
    • members: Array | Array<String> met de mailboxadressen van de leden
    • member_count: Integer | de grootte van members in deze reactie
Fouten
  • 404 unknown_group | die groep bestaat niet in de tenant van deze mailomgeving. Ook het antwoord wanneer de lookup op id niet kon worden gelezen — anders dan de index is die ene read tolerant en valt hij dicht, dus één 404 hier is geen bewijs dat de groep weg is
  • 503 group_members_unavailable | de mailserver kon niet naar de leden worden gevraagd. De groep bestaat en de rest ervan was leesbaar — probeer het opnieuw. Zie Leesfouten.
  • plus de gedeelde controles

Een groep aanmaken

POST /api/mailspace/:mailspace_id/groups

Geeft 201 Created terug met dezelfde body als Een groep bekijken.

Params
  • name: String (required) | weergavenaam. Wordt als description van de groep bewaard wanneer er geen aparte description is meegegeven.
  • email: String (required) | het adres van de groep. Een los local part wordt gekwalificeerd — zie domain.
  • domain: String (optional) | wordt alleen gebruikt wanneer email geen @ bevat; wordt genegeerd bij een volledig gekwalificeerde email. Standaard het primaire domein van de mailomgeving.
  • description: String (optional) | weergavenaam. Wordt voor dit veld in plaats van name gebruikt als het een waarde heeft — maar een expliciete "" wordt bij het aanmaken niet gehonoreerd: die valt terug op name, dus een lege description levert hier geen lege weergavenaam op. Leegmaken doe je met een PATCH (zie hieronder), waar "" het veld werkelijk leegmaakt
  • aliases: Array (optional) | Array<String> met extra adressen voor de groep
  • members: Array (optional) | Array<String> met mailboxadressen die in deze mailomgeving worden gehost
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales", "email": "sales", "members": ["ann@example.com"]}' \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/groups

Het id van de nieuwe groep komt uit een terugleesactie, en kan null zijn

De create-aanroep van de mailserver geeft geen id terug, dus de net aangemaakte groep wordt teruggelezen uit de principal-lijst van de tenant om je de :stalwart_id te geven die je nodig hebt om hem te benaderen.

Als die terugleesactie hem niet vindt, is de reactie nog steeds 201 — de groep is aangemaakt — maar meldt hij wat er is ingestuurd in plaats van wat er is opgeslagen: id is null, aliases is leeg en members is leeg, wat je ook hebt meegestuurd. Beschouw een id van null als "aangemaakt, id onbekend" en roep Groepen opvragen aan om hem te vinden. Zie het niet als een mislukking en probeer de create niet opnieuw — het adres is nu bezet.

Dit verschilt bewust van Een groep bijwerken. Een update valt terug op de groep zoals die vóór de write was, plus de waarden die net zijn geschreven, en meldt dus altijd een echt id. Een create heeft geen principal van vóór de write om op terug te vallen — er was daarvoor niets — dus is een id van null het eerlijke antwoord voor een resource die nu wel bestaat, en beter dan een fout voor een groep die wel degelijk is aangemaakt.

Een alias met een onbekend domein wordt bij aanmaken weggelaten, niet geweigerd

Het eigen adres van de groep moet op een domein van deze mailomgeving liggen — is dat niet zo, dan mislukt de create met 422 group_create_failed. Met een meegestuurde aliases-vermelding gaat het anders: een vermelding waarvan het domein niet in deze mailomgeving zit, wordt stil overgeslagen en de groep wordt alsnog aangemaakt. Vergelijk de aliases-array in de 201-body met wat je hebt gestuurd in plaats van ervan uit te gaan dat elke alias is geland. (Bij Een groep bijwerken wordt dezelfde situatie juist regelrecht geweigerd, omdat een aliaswrite de hele set vervangt.)

Fouten
  • 400 email_blank | geen adres meegegeven (Email can't be blank.)
  • 400 name_blank | geen naam meegegeven (Name can't be blank.)
  • 422 group_create_failed | het domein is geen domein van deze mailomgeving, het adres is al in gebruik, een meegestuurd lid is geen mailbox in deze mailomgeving, of de leden konden niet tegen de mailserver worden gecontroleerd
  • plus de gedeelde controles

Een groep bijwerken

PATCH /api/mailspace/:mailspace_id/groups/:stalwart_id

Geeft 200 terug met dezelfde body als Een groep bekijken, na de write opnieuw gelezen van de mailserver. Een geslaagde PATCH meldt altijd wat er is opgeslagen. Kan dat teruglezen niet worden uitgevoerd, dan is de reactie nog steeds 200 en beschrijft hij nog steeds de groep: de principal van vóór de write wordt samengevoegd met de waarden die net zijn geschreven, dus

  • id, name en email komen gevuld terug,
  • description komt terug als de waarde die je net hebt geschreven — ook "" als je hem hebt gewist,
  • een weggelaten aliases komt terug als de aliassen die er daadwerkelijk nog zijn.

Het is nooit een object vol null, en nooit een lege array voor een veld dat de write niet heeft geleegd. Dat is van belang omdat dit endpoint uitnodigt tot lezen-wijzigen-schrijven: een client die zo'n body onveranderd terug zou PATCHen, stuurt daarmee een expliciete lege lijst, en die honoreert de mailserver echt.

De envelop valt terug, members niet — en dat is met opzet

Het lijkt een inconsistentie en dat is het niet. De velden hierboven hebben een terugval die aantoonbaar waar is: de write is geslaagd, dus de geschreven waarden zijn de huidige staat van de groep. Voor het lidmaatschap bestaat zo'n terugval niet, en een lege array is daar een legitiem antwoord — een groep die gezaghebbend leeg is — dus moet die onderscheidbaar blijven van een mislukking. De leden worden daarom strikt gelezen, en een mislukte read antwoordt 503 group_members_unavailable (zie Leesfouten) in plaats van een 200 die beweert dat de groep geen leden heeft. De write is hoe dan ook al doorgevoerd: probeer de read opnieuw, nooit de write.

PATCH is een merge — een weggelaten key houdt zijn huidige waarde

Een weggelaten aliases of members laat de aliassen en het lidmaatschap van de groep precies zoals ze waren. Stuur een expliciete lege array om een van beide te wissen: "aliases": [] verwijdert elke alias, "members": [] verwijdert elk lid.

Voor members is dat een eigenschap van het mechanisme, geen afspraak: een weggelaten members wordt helemaal niet naar de mailserver gestuurd, dus het verschil in lidmaatschap wordt volledig overgeslagen — geen read, geen write. Dat is de veiligheidsgarantie. De vorige implementatie las het huidige lidmaatschap terug en gaf dat door, en omdat die read tolerant was, gaf één storing de write een leeg lidmaatschap en werd elk lid verwijderd terwijl de API 200 antwoordde.

Een meegestuurde members-array is het volledige nieuwe lidmaatschap — het verschil met het huidige lidmaatschap wordt toegepast, dus alles wat niet in de lijst staat, wordt verwijderd.

Params

Allemaal optioneel; elke weggelaten key houdt zijn huidige waarde.

  • description: String | de weergavenaam die de mailserver toont. Een expliciete "" wist hem — de mailserver weigert een lege string voor dit veld, dus stuurt CloudPress de expliciete null die hij nodig heeft.
  • aliases: Array | Array<String>, de volledige nieuwe aliasset
  • members: Array | Array<String>, het volledige nieuwe lidmaatschap (alleen mailboxen in deze mailomgeving)
  • name: String | wordt geaccepteerd en genegeerd. Het is het local part van het adres, en het adres ligt vast. description is de weergavenaam — name komt daar nooit terecht.
  • email: String | wordt genegeerd. Het adres van een groep kan niet worden gewijzigd; maak een nieuwe groep aan, of voeg het adres toe als alias.
Fouten
  • 404 unknown_group | die groep bestaat niet in de tenant van deze mailomgeving. Er wordt niets geschreven.
  • 422 group_update_failed | een meegestuurd lid is geen mailbox in deze mailomgeving, een aliasdomein is geen domein van deze mailomgeving, de leden konden niet worden gecontroleerd, of de mailserver weigerde de write
  • 503 group_members_unavailable | de write is doorgevoerd en de leden konden niet worden teruggelezen. Stuur de wijziging niet opnieuw — lees de groep opnieuw. Zie Leesfouten.
  • plus de gedeelde controles

Een groep verwijderen

DELETE /api/mailspace/:mailspace_id/groups/:stalwart_id

Verwijdert de groepsprincipal. De mailboxen van de leden blijven ongemoeid — alleen de groep en zijn adressering verdwijnen. Geeft 200 terug.

Teruggegeven params
  • deleted: Boolean | altijd true
  • id: String | het principal-id van de groep op de mailserver
  • email: String | het primaire adres van de groep
Fouten
  • 404 unknown_group | die groep bestaat niet in de tenant van deze mailomgeving. Er wordt niets verwijderd.
  • 422 group_delete_failed | de mailserver weigerde de verwijdering
  • plus de gedeelde controles

Mailinglijsten

Een mailinglijst is een apart principal-type waarvan de ontvangers een gewone adresmap zijn in plaats van een verzameling principals. Dat is het praktische verschil met een groep: een mailinglijst mag adressen bevatten die deze mailomgeving niet host.

Net als groepen heeft een lijst geen lokale databaserij en wordt hij benaderd via zijn principal-id op de mailserver (:stalwart_id), met dezelfde controle op tenanteigendom en hetzelfde 404-gedrag voor een id dat onbekend of onleesbaar is of bij een andere workspace hoort — hier gemeld als unknown_mailing_list. Ook die controle valt dicht terug: een read die de mailserver niet kon beantwoorden, is geen bewijs van eigendom.

Mailinglijsten opvragen

GET /api/mailspace/:mailspace_id/mailing_lists

Params
  • q: String (optional) | hoofdletterongevoelig filter op deelstring, gematcht tegen het primaire adres of de omschrijving van de lijst. Dezelfde twee velden als het groepsfilter, met dezelfde matching.
Teruggegeven params
  • mailing_lists: Array
    • id: String | principal-id op de mailserver — de :stalwart_id waarmee je de lijst benadert
    • name: String | het local part dat de mailserver bewaart; niet de weergavenaam, en niet wijzigbaar
    • email: String | primair adres
    • aliases: Array | Array<String> met de aliasadressen van de lijst
    • description: String | de weergavenaam, null als die niet is ingesteld
    • members: Array | Array<String> met ontvangeradressen, die ook adressen buiten deze mailomgeving mogen bevatten
    • member_count: Integer | de grootte van members
Fouten
  • 503 mailing_lists_unavailable | de lijstread kon niet worden uitgevoerd. De read is strikt, dus een leeg mailing_lists-array is gezaghebbend — zie Leesfouten
  • plus de gedeelde controles

Een mailinglijst bekijken

GET /api/mailspace/:mailspace_id/mailing_lists/:stalwart_id

Geeft precies de velden van een rij uit Mailinglijsten opvragen terug — de ontvangers zitten daar al bij, dus er is niets extra op te halen.

Teruggegeven params
Fouten
  • 404 unknown_mailing_list | die lijst bestaat niet in de tenant van deze mailomgeving. Net als bij één groep is de lookup op id tolerant en valt hij dicht naar deze 404 — de index is de gezaghebbende controle
  • plus de gedeelde controles

Een mailinglijst aanmaken

POST /api/mailspace/:mailspace_id/mailing_lists

Geeft 201 Created terug met dezelfde body als Een mailinglijst bekijken.

Params
  • name: String (required) | weergavenaam. Wordt als description van de lijst bewaard wanneer er geen aparte description is meegegeven.
  • email: String (required) | het adres van de lijst. Een los local part wordt gekwalificeerd — zie domain.
  • domain: String (optional) | wordt alleen gebruikt wanneer email geen @ bevat; wordt genegeerd bij een volledig gekwalificeerde email. Standaard het primaire domein van de mailomgeving.
  • description: String (optional) | weergavenaam. Wordt voor dit veld in plaats van name gebruikt als het een waarde heeft — maar een expliciete "" wordt bij het aanmaken niet gehonoreerd: die valt terug op name, dus een lege description levert hier geen lege weergavenaam op. Leegmaken doe je met een PATCH (zie hieronder), waar "" het veld werkelijk leegmaakt
  • aliases: Array (optional) | Array<String> met extra adressen voor de lijst
  • members: Array (optional) | Array<String> met ontvangeradressen. Adressen van buiten zijn toegestaan.

Het id van de nieuwe lijst komt uit een terugleesactie, en kan null zijn

Net als bij groepen geeft de create van de mailserver geen id terug, dus de nieuwe lijst wordt teruggelezen om de :stalwart_id te leveren. Mislukt die terugleesactie, dan is de reactie nog steeds 201, maar is id null en is aliases leeg — members echoot wat je hebt ingestuurd. Roep Mailinglijsten opvragen aan om het id te vinden in plaats van de create opnieuw te proberen.

Net als bij groepen verschilt dit bewust van Een mailinglijst bijwerken: een update kan terugvallen op de lijst zoals die vóór de write was, maar een create heeft zo'n eerdere staat niet, dus is een id van null het eerlijke antwoord voor een lijst die nu wel bestaat.

Een alias met een onbekend domein wordt bij aanmaken weggelaten, niet geweigerd

Precies zoals bij Een groep aanmaken: het eigen adres van de lijst moet op een domein van deze mailomgeving liggen, maar een meegestuurde alias waarvan het domein dat niet is, wordt stil overgeslagen en de lijst wordt alsnog aangemaakt. Controleer de aliases-array in de 201-body.

Fouten
  • 400 email_blank | geen adres meegegeven (Email can't be blank.)
  • 400 name_blank | geen naam meegegeven (Name can't be blank.)
  • 422 mailing_list_create_failed | het domein is geen domein van deze mailomgeving, het adres is al in gebruik, of de mailserver weigerde de create
  • plus de gedeelde controles

Een mailinglijst bijwerken

PATCH /api/mailspace/:mailspace_id/mailing_lists/:stalwart_id

Geeft 200 terug met dezelfde body als Een mailinglijst bekijken, na de write opnieuw gelezen. Een geslaagde PATCH meldt altijd wat er is opgeslagen. Kan dat teruglezen niet worden uitgevoerd, dan is de reactie nog steeds 200 en beschrijft hij nog steeds de lijst: de principal van vóór de write wordt samengevoegd met de waarden die net zijn geschreven, dus

  • id, name en email komen gevuld terug,
  • description komt terug als de waarde die je net hebt geschreven — ook "" als je hem hebt gewist,
  • een weggelaten aliases komt terug als de aliassen die er daadwerkelijk nog zijn,
  • een weggelaten members komt terug als de ontvangers die er daadwerkelijk nog zijn. Een weggelaten members slaat het synchroniseren van de ontvangers volledig over, dus zijn ze per definitie ongewijzigd.

Het is nooit een object vol null, en nooit een lege array voor een veld dat de write niet heeft geleegd. Hier weegt dat het zwaarst: een client die zo'n body onveranderd terug zou PATCHen, stuurt daarmee een expliciete lege ontvangerslijst, en die honoreert de mailserver door de lijst echt te legen — en de ontvangers van een lijst mogen adressen zijn die deze mailomgeving niet host, wat ze moeilijker te reconstrueren maakt dan die van een groep, niet makkelijker.

PATCH is een merge — een weggelaten key houdt zijn huidige waarde

Een weggelaten aliases laat de aliasset ongemoeid; een weggelaten members slaat het synchroniseren van de ontvangers volledig over. Stuur een expliciete lege array om een van beide te wissen. Een meegestuurde members-array is de volledige nieuwe ontvangerslijst — het verschil wordt toegepast, dus alles wat niet in de lijst staat, wordt afgemeld.

Params

Allemaal optioneel; elke weggelaten key houdt zijn huidige waarde.

  • description: String | de weergavenaam die de mailserver toont. Een expliciete "" wist hem — de mailserver weigert een lege string voor dit veld, dus stuurt CloudPress de expliciete null die hij nodig heeft.
  • aliases: Array | Array<String>, de volledige nieuwe aliasset
  • members: Array | Array<String>, de volledige nieuwe ontvangerslijst
  • name: String | wordt geaccepteerd en genegeerd. Het is het local part van het adres, en het adres ligt vast. description is de weergavenaam — name komt daar nooit terecht.
  • email: String | wordt genegeerd. Het adres van een lijst kan niet worden gewijzigd.
Fouten
  • 404 unknown_mailing_list | die lijst bestaat niet in de tenant van deze mailomgeving. Er wordt niets geschreven.
  • 422 mailing_list_update_failed | een aliasdomein is geen domein van deze mailomgeving, of de mailserver weigerde de write
  • plus de gedeelde controles

Een mailinglijst verwijderen

DELETE /api/mailspace/:mailspace_id/mailing_lists/:stalwart_id

Verwijdert de lijstprincipal. De eigen mailboxen van de ontvangers blijven ongemoeid — alleen de lijst verdwijnt. Geeft 200 terug.

Teruggegeven params
  • deleted: Boolean | altijd true
  • id: String | het principal-id van de lijst op de mailserver
  • email: String | het primaire adres van de lijst
Fouten
  • 404 unknown_mailing_list | die lijst bestaat niet in de tenant van deze mailomgeving. Er wordt niets verwijderd.
  • 422 mailing_list_delete_failed | de mailserver weigerde de verwijdering
  • plus de gedeelde controles

Verhulde adressen

Een verhuld adres is een wegwerp-doorstuuradres: de mailserver bedenkt het adres, en mail die ernaartoe wordt gestuurd, wordt doorgestuurd naar een mailbox die jij aanwijst. Elk verhuld adres is een object op de mailserver met een lokale rij ernaast, en het is de GUID van die lokale rij die het benadert — het segment :guid, teruggegeven als id.

Vereist een Enterprise-mailserver, en dat kun je niet via de API vaststellen

Verhulde adressen zijn een Enterprise-functie van de mailserver. Er is geen manier om de mogelijkheden af te tasten, dus de API kan je niet vertellen of de functie in licentie is:

  • Op een build zonder deze functie antwoordt GET …/masked_emails met 200 en een lege masked_emails-array — niet te onderscheiden van een mailomgeving die er simpelweg geen heeft.
  • POST …/masked_emails mislukt met 422 masked_email_create_failed, wat dezelfde code is als bij een gewone weigering.

Blijven creates mislukken met masked_email_create_failed terwijl de doelmailbox echt in deze mailomgeving bestaat, vraag dan bij support na of de functie voor jou beschikbaar is, in plaats van het als een clientbug te behandelen.

:guid is de tenantcontrole — en de grens van 2000 is niet die van deze mailomgeving

De query van de mailserver voor verhulde adressen is serverbreed — hij filtert op account, nooit op tenant — dus het eigendom wordt in plaats daarvan vanuit de lokale rijen bepaald. Elk pad op id lost :guid binnen deze mailomgeving op, en een GUID die bij een andere workspace hoort, geeft 404 unknown_masked_email en niet 403: een 403 zou bevestigen dat de rij bestaat.

Daarom is de grens van 2000 rijen ook geen plafond voor deze mailomgeving. Hij wordt toegepast op de serverbrede query, voordat de rijen van deze mailomgeving eruit worden gehaald, dus op een drukke mailserver kunnen de adressen van deze mailomgeving buiten dat venster vallen en simpelweg niet verschijnen — zonder dat iets in de reactie dat zegt, en hoe weinig het er ook zijn.

Verhulde adressen opvragen

GET /api/mailspace/:mailspace_id/masked_emails

De live lijst, samengevoegd met de lokale rijen van deze mailomgeving. Een adres dat op de mailserver bestaat maar hier geen lokale rij heeft, wordt weggelaten (het is niet van ons), en een lokale rij waarvan het object op de mailserver weg is, wordt ook weggelaten.

Teruggegeven params
  • masked_emails: Array
    • id: String | de GUID van de lokale rij — dit is de :guid waarmee je het adres benadert
    • stalwart_id: String | het eigen opake id van de mailserver, alleen om te correleren
    • email: String | het verhulde adres zelf
    • description: String | null als het niet is ingesteld
    • enabled: Boolean | altijd een boolean; een adres zonder opgeslagen waarde leest als true
    • for_domain: String | de site waarvoor het adres is bedacht, null als dat niet is ingesteld
    • url: String | null als het niet is ingesteld
    • created_by: String | vrije tekst over de herkomst, null als het niet is ingesteld
    • created_at: String | ISO 8601, door de server gezet, null als de server het niet heeft geleverd
    • expires_at: String | ISO 8601, door de server gezet en alleen-lezen; meestal null

Elke key is altijd aanwezig — een onbekende waarde is null, nooit weggelaten.

Een verhuld adres aanmaken

POST /api/mailspace/:mailspace_id/masked_emails

Bedenkt een nieuw verhuld adres. De mailserver kent het adres zelf toe — je wijst de mailbox aan waarnaar het doorstuurt, niet het adres dat het krijgt. Geeft 201 Created terug.

Params
  • target_mailbox_email: String (required) | een mailbox in deze mailomgeving waar het verhulde adres naartoe doorstuurt. Wordt opgelost via de eigen domeinmap van de tenant, dus een adres buiten deze mailomgeving wordt geweigerd.
  • description: String (optional)
  • enabled: Boolean (optional) | standaard true wanneer de key wordt weggelaten
  • for_domain: String (optional) | de site waarop het adres wordt gebruikt
  • url: String (optional)
  • created_by: String (optional) | vrije tekst over de herkomst
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_mailbox_email": "ann@example.com", "description": "shop signup"}' \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/masked_emails
Teruggegeven params (201 Created)

Het object wordt van de mailserver teruggelezen, zodat de door de server gezette velden (created_at, expires_at) gevuld zijn. Mislukt die terugleesactie, dan is de reactie nog steeds 201 en meldt hij wat er is ingestuurd, met created_at en expires_at als null.

Fouten
  • 400 target_mailbox_email_blank | geen doel meegegeven (Target mailbox email can't be blank.)
  • 422 masked_email_create_failed | die mailbox bestaat niet in deze mailomgeving, of de mailserver weigerde — waaronder een build waarvoor de functie niet in licentie is
  • plus de gedeelde controles

Een verhuld adres verwijderen

DELETE /api/mailspace/:mailspace_id/masked_emails/:guid

Verwijdert het object op de mailserver en de lokale rij, zodat het adres stopt met doorsturen. Mail die er al via is afgeleverd, blijft ongemoeid. Geeft 200 terug.

Teruggegeven params
  • deleted: Boolean | altijd true
  • id: String | de GUID die is verwijderd
  • email: String | het adres dat is verwijderd
Fouten
  • 404 unknown_masked_email | die rij bestaat niet in deze mailomgeving
  • 422 masked_email_delete_failed | de mailserver weigerde de verwijdering; de lokale rij blijft staan
  • plus de gedeelde controles

Foutcodes

Alle fouten behalve de OAuth-scopefout gebruiken de standaardenvelop {"errors": [...], "code": "..."} die is beschreven in Foutreacties. Een onbekende of buiten je bereik vallende :mailspace_id is de uitzondering in de andere richting: 404 met een lege body en helemaal geen envelop.

Gedeeld door elk endpoint op deze pagina — zie Gedeelde controles:

Code Status Geretourneerd bij
stalwart_unavailable 503 alle verzoeken
not_authorized 403 POST, PATCH, DELETE
mailspace_suspended 403 alle verzoeken
pending_delete 403 POST, PATCH, DELETE
not_provisioned 409 alle verzoeken

Per endpoint:

Code Status Geretourneerd door
address_blank 400 een alias aanmaken
target_blank 400 een alias aanmaken
invalid_alias 422 een alias aanmaken
aliases_unavailable 503 aliassen opvragen, een alias aanmaken, een alias verwijderen
unknown_alias 404 een alias verwijderen
alias_remove_failed 422 een alias verwijderen
email_blank 400 een groep aanmaken, een mailinglijst aanmaken
name_blank 400 een groep aanmaken, een mailinglijst aanmaken
unknown_group 404 een groep bekijken, bijwerken, verwijderen
group_create_failed 422 een groep aanmaken
group_update_failed 422 een groep bijwerken
group_delete_failed 422 een groep verwijderen
groups_unavailable 503 groepen opvragen
group_members_unavailable 503 groepen opvragen, een groep bekijken, een groep bijwerken
mailing_lists_unavailable 503 mailinglijsten opvragen
unknown_mailing_list 404 een mailinglijst bekijken, bijwerken, verwijderen
mailing_list_create_failed 422 een mailinglijst aanmaken
mailing_list_update_failed 422 een mailinglijst bijwerken
mailing_list_delete_failed 422 een mailinglijst verwijderen
target_mailbox_email_blank 400 een verhuld adres aanmaken
masked_email_create_failed 422 een verhuld adres aanmaken
unknown_masked_email 404 een verhuld adres verwijderen
masked_email_delete_failed 422 een verhuld adres verwijderen