Ga naar inhoud

Mailspace-domeinen

Een mailomgeving verwerkt mail voor haar hoofddomein — het domein waarvoor ze is aangeschaft — plus een willekeurig aantal extra domeinen die je eraan toevoegt. Deze endpoints gaan over die domeinlijst, over het DNS-TXT-eigendomsbewijs dat een domein nodig heeft voordat het wordt verwerkt, en over de DNS-records voor mail (MX, SPF, DKIM, DMARC en de hosts voor automatische clientconfiguratie) die elk domein gepubliceerd moet hebben.

De endpoints op planniveau — aanschaffen, resizen, verwijderen — staan op Mailspace.

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

Elk endpoint op deze pagina is genest onder één mailomgeving en erft dezelfde keten van controles. Die zijn één keer gedocumenteerd, in Foutcodes — lees die sectie voordat je deze pagina doorneemt. Een mailomgeving die niet zichtbaar is voor je credential geeft 404 terug met een lege body.

Het hoofddomein wordt eerst geverifieerd, en tot die tijd werkt er niets anders

Een mailomgeving die is aangeschaft voor een domein waarvan de workspace niet de registrar is, wordt onvoorzien aangemaakt: er zit nog geen tenant op de mailserver achter. In die staat antwoordt elk endpoint op deze pagina 409 not_provisioned, behalve de drie endpoints voor verificatie van het hoofddomein.

De volgorde staat vast:

  1. GET /api/mailspace/:mailspace_id/domain_verification voor het TXT-record dat je moet publiceren, en publiceer het dan.
  2. POST naar hetzelfde pad. Het eigendom wordt live gecontroleerd en het inrichten begint.
  3. Poll totdat state op provisioned staat.
  4. Al het andere op deze pagina wordt bruikbaar.

Die drie endpoints zijn de enige die de controle op het inrichten overslaan — het is juist die controle die je ernaartoe stuurt.

Domeinen opvragen

GET /api/mailspace/:mailspace_id/domains

Vereist mailspace:read.

Elk domein op de mailomgeving, in twee lijsten: domains — live uitgelezen van de mailserver — is het hoofddomein plus elk geverifieerd extra domein dat de tenant daadwerkelijk verwerkt, en pending_domains zijn de lokale records die nog op een DNS-TXT-eigendomsbewijs wachten. Een domein staat in precies één van de twee; state onderscheidt de drie soorten. Dit endpoint is niet gepagineerd.

Params (allemaal optioneel)
  • q: String | hoofdletterongevoelige deelstring van de domeinnaam. Filtert beide lijsten

Een lege domains-lijst is gezaghebbend

Het uitlezen van de mailserver is strikt: een read die niet kon worden uitgevoerd antwoordt 503 domains_unavailable in plaats van een lege lijst, dus domains valt te verzoenen met je eigen administratie. De variant met de lege lijst was juist zo moeilijk te zien, omdat primary_domain uit lokale records komt en gevuld bleef — een storing zag er precies uit als een mailomgeving die niets verwerkt.

De code dekt die ene read en niets anders. De hele reactie is de foutenvelop, dus pending_domains en primary_domain worden er niet naast teruggegeven, ook al zijn ze beide lokaal. Zie Leesfouten.

Teruggegeven params
  • primary_domain: String | het eigen maildomein van de mailomgeving
  • domains: Array | live van de mailserver
    • name: String
    • description: String | null als er geen is ingesteld
    • state: String | primary voor het eigen domein van de mailomgeving, served voor een geverifieerd extra domein
    • verified: Boolean | in deze lijst altijd true
    • dns_state: String | managed (de DNS-zone van het domein wordt bij CloudPress gehost), setup_needed (externe DNS, en bij de laatste controle ontbraken er records) of manual (externe DNS, voor zover wij weten niets openstaand)
  • pending_domains: Array | lokale records die op hun TXT-bewijs wachten; deze accepteren geen mail
    • name: String
    • description: String | null als er geen is ingesteld
    • state: String | altijd pending_verification
    • verified: Boolean | true zodra het eigendom is aangetoond maar het domein nog niet op de mailserver is aangemaakt
    • verification: Object
      • txt_host: String | de recordhost, _mailspace-verify. gevolgd door het domein
      • txt_value: String | het hexadecimale token van 32 tekens dat je als TXT-waarde publiceert, per domein aangemaakt
      • txt_type: String | altijd TXT
    • last_checked_at: DateTime | wanneer het TXT-record voor het laatst is opgezocht, null tot de eerste controle
    • created_at: DateTime
    • updated_at: DateTime
Fouten
  • 503 domains_unavailable | de live domeinread kon niet worden uitgevoerd. Het opnieuw proberen waard, en geen lege mailomgeving — zie Leesfouten
  • plus de gedeelde controles
curl -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domains

Een domein bekijken

GET /api/mailspace/:mailspace_id/domains/:name

Vereist mailspace:read.

Het domein wordt aangesproken op naam, niet op een ID — .../domains/example.com. Het padsegment accepteert punten, en de naam wordt op dezelfde manier genormaliseerd als bij Een domein toevoegen.

Een extra domein in afwachting is hier ook te lezen, en dat is het enige wat je er op dit pad mee kunt: PATCH en DELETE weigeren het met 409 domain_pending_verification. state vertelt je welke vorm je hebt gekregen.

Is de mailserver niet bereikbaar, dan antwoorden de lokale gegevens eerst

De opzoeking achter dit pad — gedeeld door GET, PATCH en DELETE op /domains/:name — vraagt het domein op bij de mailserver. Mislukt die read, in plaats van te antwoorden dat het domein niet bestaat, dan raadpleegt CloudPress eerst zijn eigen tabel met domeinen in afwachting voordat het opgeeft. Die volgorde is van belang: een domein dat nog op zijn TXT-bewijs wacht, staat helemaal niet op de mailserver, dus een client die tijdens een openstaande verificatie blijft pollen, krijgt gewoon 200 uit de lokale gegevens in plaats van vast te lopen op een storing die er niets mee te maken heeft. Een record in afwachting dat zo wordt gevonden, gedraagt zich precies zoals altijd — hier leesbaar, 409 domain_pending_verification voor PATCH en DELETE.

503 stalwart_unavailable is er alleen voor het geval dat noch de mailserver noch een lokaal record in afwachting de naam kan oplossen. Een mislukte read wordt nooit gemeld als 404 unknown_domain: die code betekent dat de mailserver antwoord gaf en het domein niet op deze mailomgeving staat.

Teruggegeven params
  • domain: Object | de verwerkte vorm (state primary of served) of de vorm in afwachting (state pending_verification), veld voor veld zoals bij Domeinen opvragen

Een domein toevoegen

POST /api/mailspace/:mailspace_id/domains

Vereist mailspace:write. Geeft 201 terug.

Voegt een extra domein toe. Welke van twee dingen er gebeurt, hangt ervan af of het eigendom al is aangetoond:

Het domein wordt direct op de mailserver aangemaakt en komt terug met state served. Geen TXT-record, geen wachten.

Aangetoond betekent dat de facturatiefamilie het domein bij CloudPress heeft geregistreerd. Dat is hier het enige signaal dat meetelt — alleen de DNS-zone van het domein bij ons hosten is niet genoeg, want voor het aanmaken van een zone is niets meer nodig dan bewerkrecht.

Een verlopen registratie telt nog steeds mee. De controle faalt pas als de registratie is opgeruimd; een domein in zijn redemption-periode, of dat alleen als risicovol is gemarkeerd omdat een verlenging te laat is, geldt nog als eigendomsbewijs en gaat nog steeds via het directe pad.

Het domein wordt geparkeerd als record in afwachting en de reactie bevat het verification-TXT-record dat je moet publiceren. Het wordt niet op de mailserver aangemaakt en accepteert geen mail totdat je dat record publiceert en Een domein verifiëren aanroept.

Params
  • name: String | vereist. Wordt voor gebruik genormaliseerd: een http:// of https:// aan het begin, een www. aan het begin, alles vanaf de eerste / en een punt aan het eind worden verwijderd, en het resultaat wordt omgezet naar kleine letters. www.example.com wordt dus opgeslagen — en moet worden aangesproken — als example.com. Een naam die daarna geen geldige hostname is, geeft 400 invalid_domain
  • description: String | optioneel vrij label. Leeg wordt opgeslagen als geen beschrijving
Teruggegeven params
  • domain: Object | zoals bij Een domein bekijken — state served op het aangetoonde pad, anders pending_verification
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"second.example.com","description":"Second brand"}' \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domains
Fouten
  • 400 invalid_domain | name ontbreekt, of is na normalisatie geen geldige hostname
  • 409 domain_exists | het domein wordt al door deze mailomgeving verwerkt
  • 409 domain_pending_verification | het domein staat al geparkeerd in afwachting van zijn TXT-bewijs — gebruik Status van de domeinverificatie
  • 422 domain_create_failed | de mailserver weigerde het aanmaken, of het record in afwachting kon niet worden opgeslagen. Een naam die op de mailserver al onder een andere tenant is geregistreerd, komt hier terecht

Een domein bijwerken

PATCH /api/mailspace/:mailspace_id/domains/:name

Vereist mailspace:write. Geeft 200 terug met het domeinobject.

Dit wijzigt alleen de beschrijving. Een domein kan niet worden hernoemd — de naam in het pad identificeert het domein, en een name in de body wordt genegeerd.

description kent drie gevallen, en die zijn allemaal verschillend

  • De key weglaten — de beschrijving blijft precies zoals hij is. Er wordt niets over het veld naar de mailserver gestuurd.
  • "" meesturen — de beschrijving wordt gewist. Hij komt terug als null en niet als "", omdat de mailserver een lege tekenreeks voor dit veld weigert en CloudPress de vereiste null voor je meestuurt.
  • Een waarde meesturen — ingesteld op die waarde.

Als je de beschrijving wiste door de key weg te laten, stuur nu "" mee.

Params
  • description: String | de nieuwe beschrijving. Laat de key weg om hem ongemoeid te laten; stuur "" om hem te wissen
Fouten
  • 404 unknown_domain | dat domein bestaat niet op deze mailomgeving
  • 409 domain_pending_verification | het domein wacht nog op zijn TXT-bewijs, dus er staat niets op de mailserver om te wijzigen
  • 422 domain_update_failed | het domein staat niet meer op deze mailomgeving, of de mailserver weigerde de wijziging
  • 503 stalwart_unavailable | de mailserver was niet bereikbaar en de naam is ook geen domein in afwachting — zie Een domein bekijken

De 200-body is betrouwbaar, ook als het teruglezen mislukt

De write wordt bevestigd door het domein opnieuw te lezen, en die read kan mislukken terwijl de write wél is gelukt. In dat geval valt de reactie terug op wat zeker waar is: de beschrijving die je net hebt meegestuurd, of de beschrijving van vóór de write als je de key hebt weggelaten. Elk ander veld wordt afgeleid in plaats van teruggelezen, dus niets hier zakt terug naar een tijdelijke waarde.

Een domein verwijderen

DELETE /api/mailspace/:mailspace_id/domains/:name

Vereist mailspace:write. Geeft 200 terug met een lege body.

Verwijdert een extra domein van de mailserver, verwijdert het lokale record dat CloudPress ervan bijhoudt, en verwijdert de mailrecords die CloudPress ervoor in de eigen gehoste DNS-zone van de workspace heeft gezet — zonder die laatste stap zou de zone een mailhost blijven aankondigen die geen mail meer aanneemt voor het domein.

Een domein dat nog in gebruik is, wordt geweigerd en niet leeggemaakt

Een domein waarop nog mailboxen, groepen of mailinglijsten staan, wordt geweigerd met 422 domain_delete_failed, en het bericht noemt wat het blokkeert (bijvoorbeeld Can't delete example.com — it still has 3 mailboxes and 1 group. Delete those first, then remove the domain.). De geweigerde aanroep vernietigt niets.

Aliassen worden in dat overzicht niet meegeteld — ze horen bij de mailbox of de groep waaraan ze hangen, dus door de objecten te verwijderen die ze bevatten verdwijnen ze mee.

Het hoofddomein kan niet worden verwijderd: het is de identiteit van de mailomgeving en verdwijnt alleen samen met de mailomgeving zelf. Het antwoordt 409 primary_domain.

Wil je een domein opgeven dat nooit voorbij de verificatie is gekomen, gebruik dan Een domein in afwachting opgeven — dit pad antwoordt daarvoor 409 domain_pending_verification.

Fouten
  • 404 unknown_domain | dat domein bestaat niet op deze mailomgeving
  • 409 primary_domain | het eigen domein van de mailomgeving — zie hierboven
  • 409 domain_pending_verification | het domein wacht nog op zijn TXT-bewijs
  • 422 domain_delete_failed | er staan nog mailboxen, groepen of mailinglijsten op het domein; het domein staat niet meer op deze mailomgeving; of de mailserver weigerde de verwijdering
  • 503 stalwart_unavailable | de mailserver was niet bereikbaar en de naam is ook geen domein in afwachting — zie Een domein bekijken

De DNS-records voor mail bekijken

GET /api/mailspace/:mailspace_id/domains/dns

Vereist mailspace:read.

De DNS-records die één domein nodig heeft om mail te laten werken, plus — bij externe DNS — het resultaat per record van de laatste controle. Met de optionele domain kies je over welk domein op de mailomgeving wordt gerapporteerd; laat die weg voor het hoofddomein. Een domein dat deze mailomgeving niet heeft, antwoordt 404 unknown_domain.

Lees eerst de managed-vlag op het hoogste niveau, want die bepaalt de vorm van de rest van de reactie.

Params (allemaal optioneel)
  • domain: String | over welk domein op de mailomgeving wordt gerapporteerd. Standaard het hoofddomein als je het weglaat. Stuur de kale FQDN precies zo — zie de waarschuwing hieronder

domain wordt niet genormaliseerd zoals het :name-padsegment

Het :name-segment bij Een domein bekijken wordt voor gebruik opgeschoond: een http:// of https:// vooraan, een www. vooraan, alles vanaf de eerste / en een punt aan het eind worden allemaal verwijderd. Deze queryparameter krijgt daar niets van. Er worden alleen omringende spaties afgehaald en de waarde wordt in kleine letters omgezet, en daarna exact vergeleken met de domeinen van de mailomgeving.

Dus https://mail.example.com, www.example.com, example.com/ en example.com. antwoorden hier allemaal 404 unknown_domain, ook waar dezelfde waarde als padsegment wél zou werken. Stuur de kale, exacte FQDN — en normaliseer invoer van een gebruiker eerst zelf.

Hetzelfde geldt voor domain bij De DNS voor mail opnieuw controleren.

De DNS-zone van het domein wordt bij CloudPress gehost, en de mailrecords worden daar voor je onderhouden. De recordlijst is alleen ter referentie: geen enkele regel heeft een status- of found-veld, en de sleutels detected, total en caa worden helemaal weggelaten (niet null). checked_at en all_detected zijn null.

Een zone die wij hosten maar die niet naar de DNS-provider is gepubliceerd, heeft geen provider-id en wordt daarom bewust als managed: false gerapporteerd — er kunnen geen records in worden geschreven, dus melden dat de zone beheerd is en er niets te doen valt, zou de mailrecords eindeloos ongepubliceerd laten.

Externe DNS: je publiceert deze records zelf. Elke regel bevat de status en found van de laatste controle, en de reactie voegt detected, total en het caa-advies toe. Zolang er nooit een controle heeft gelopen, is checked_at null en staat elke regel op unchecked — dit endpoint doet zelf geen lookups. De DNS voor mail opnieuw controleren is wat ze vernieuwt.

De recordwaarden staan in de reactie, niet op deze pagina

Publiceer exact de value die elke regel bevat. De DKIM-waarde is de eigen signeersleutel van je mailomgeving en de SPF- en DMARC-regels worden opgebouwd uit het beleid dat op dat moment voor het domein geldt, dus dat zijn waarden per domein die deze pagina bewust niet herhaalt.

Teruggegeven params
  • domain: String | het domein waarover dit rapport gaat
  • managed: Boolean | zie de twee vormen hierboven
  • checked_at: String | ISO 8601-tijdstempel van de laatste controle, null als er nog geen heeft gelopen en altijd null bij managed
  • detected: Integer | vereiste regels die momenteel worden gedetecteerd. Wordt helemaal weggelaten bij managed
  • total: Integer | vereiste regels. Optionele regels tellen in beide aantallen niet mee. Wordt helemaal weggelaten bij managed
  • all_detected: Boolean | alleen true wanneer elke vereiste regel wordt gedetecteerd; null bij managed
  • records: Array
    • type: String | MX, A, AAAA, TXT of CNAME
    • name: String | de recordhost
    • value: String | de exacte waarde die je publiceert
    • priority: Integer | MX-prioriteit; null bij elk ander type
    • purpose: String | waar het record voor dient. De API geeft hier een Engelse waarde terug, bijv. Mail delivery (mailbezorging), SPF – authorised senders (toegestane verzenders) of DKIM – message signing (berichten signeren)
    • optional: Boolean | alleen true op de IPv6-AAAA-regel. Een optionele regel wordt net als elke andere gerapporteerd maar telt nooit mee voor detected / total / all_detected — mail die alleen IPv4 gebruikt, is volledig werkende mail
    • placeholder: Boolean | true wanneer de DKIM-waarde een tijdelijke waarde met instructies is omdat de echte signeersleutel niet kon worden uitgelezen. Publiceer een tijdelijke waarde niet — lees hem in plaats daarvan opnieuw uit
    • status: String | ok, mismatch, missing of unchecked. Wordt helemaal weggelaten bij managed
    • found: String | wat er daadwerkelijk is gepubliceerd, als dat afwijkt; anders null. Wordt helemaal weggelaten bij managed
  • caa: Object | alleen adviserend, en blokkeert niets. Wordt helemaal weggelaten bij managed
    • status: String | ok, mismatch (een CAA-beleid op de mailhost sluit de certificaatautoriteit uit waar onze mailcertificaten van komen — het mailcertificaat kan niet worden uitgegeven totdat dat beleid is verruimd), unknown of unchecked

In een gehoste zone wordt een eigen record nooit overschreven

In een zone die CloudPress host, blijft een naam die al een record bevat dat wij niet hebben geschreven precies zoals hij is — het mailrecord wordt daar niet gepubliceerd, en de mail-DNS van het domein blijft incompleet totdat je het bestaande record verwijdert. Dat is van belang bij een migratie, waar mail., webmail., autodiscover. en een DKIM-selector vaak al naar de oude provider wijzen.

Deze reacties melden dat niet. Een beheerd domein geeft helemaal geen status per record terug, dus vergelijk de lijst hierboven met de daadwerkelijke records van de zone via Alle records weergeven, of vraag support via https://cloudpress.com/contact/.

curl -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  "https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domains/dns?domain=second.example.com"

De DNS voor mail opnieuw controleren

POST /api/mailspace/:mailspace_id/domains/dns_check

Vereist mailspace:write. Geeft 200 terug met het verse resultaat.

Voert de DNS-lookups nu, synchroon uit — de reactie bevat de uitkomst. Er is geen taak om te pollen en geen 202. Het resultaat wordt opgeslagen, dus De DNS-records voor mail bekijken rapporteert daarna dezelfde cijfers zonder opnieuw iets op te zoeken.

Params (allemaal optioneel)
  • domain: String | welk domein op de mailomgeving wordt gecontroleerd. Standaard het hoofddomein als je het weglaat. Hij wordt niet genormaliseerd zoals het :name-padsegment — stuur de kale, exacte FQDN. Zie de waarschuwing bij de read

Een write, ook al verandert er geen configuratie

Dit is een POST, en de controles die om mutaties geven, kijken naar het HTTP-werkwoord en niet naar de naam van de actie. Het vereist dus mailspace:write en bewerkrecht op de eigen workspace, en het wordt geweigerd op een mailomgeving die gepland staat voor verwijdering — terwijl de GET ernaast dat niet is.

Gelimiteerd tot één keer per domein per 5 minuten

De limiet is gekoppeld aan de mailomgeving én het domein, dus het controleren van het ene domein blokkeert nooit het andere. Een aanroep binnen het venster wordt geweigerd met 429 rate_limited en doet geen lookups.

Twee dingen verbruiken het venster bewust niet: een domein waarvan CloudPress de DNS host (dat wordt vóór de limiter afgehandeld — zie hieronder), en een mislukte controle, waarvan het token wordt vrijgegeven zodat je direct opnieuw kunt proberen.

Bij een domein waarvan de DNS-zone bij CloudPress wordt gehost, is er niets voor je om te controleren, dus komt er 200 terug met managed: true, records: [], en checked_at en all_detected op null — er worden geen lookups uitgevoerd.

Teruggegeven params 
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domains/dns_check
Fouten
  • 404 unknown_domain | domain is geen domein op deze mailomgeving
  • 429 rate_limited | te recent gecontroleerd voor dit domein — zie hierboven
  • 422 dns_check_failed | de lookups konden niet worden afgerond; het token van de rate limit wordt vrijgegeven zodat je direct opnieuw kunt proberen

Status van de domeinverificatie

GET /api/mailspace/:mailspace_id/domains/:domain_name/verification

Vereist mailspace:read.

Eigendomsverificatie voor een extra domein: het TXT-record dat je moet publiceren en of het al is gezien.

Het padsegment is :domain_name, niet :name

Door de nesting krijgt het bovenliggende segment een andere naam: op dit pad heet het domein :domain_name en op de /domains/:name-paden hierboven :name. Het is dezelfde waarde.

Dit pad spreekt alleen domeinen in afwachting aan. Een domein dat de mailomgeving al verwerkt — en een domein dat ze nooit heeft gezien — antwoorden beide 404 unknown_domain; zodra de verificatie slaagt, verhuist het domein naar Een domein bekijken en antwoordt dit pad er niet meer voor.

Teruggegeven params
  • verification: Object
    • domain: String
    • state: String | awaiting_verification, of verified zodra het TXT-record is gezien maar het domein nog niet op de mailserver is aangemaakt
    • verified: Boolean
    • txt_type: String | altijd TXT
    • txt_host: String | de recordhost, _mailspace-verify. gevolgd door het domein
    • txt_value: String | het hexadecimale token van 32 tekens dat je publiceert, per domein aangemaakt
    • verified_at: DateTime | wanneer het eigendom is aangetoond, null tot dat moment
    • last_checked_at: DateTime | wanneer het record voor het laatst is opgezocht, null tot de eerste controle
    • create_attempts: Integer | hoe vaak de automatische controleronde heeft geprobeerd dit geverifieerde domein op de mailserver aan te maken
    • create_attempts_exhausted: Boolean | true zodra de controleronde het heeft opgegeven (na 10 pogingen). Geen doodlopende weg — een POST hieronder zet de teller terug en activeert de ronde opnieuw

Een domein verifiëren

POST /api/mailspace/:mailspace_id/domains/:domain_name/verification

Vereist mailspace:write. Geeft 200 terug.

Zoekt het TXT-record nu op. Wordt het token gevonden, dan wordt het domein in dezelfde aanroep op de mailserver aangemaakt en het record in afwachting verwijderd — de reactie is het verwerkte domein, en vanaf dan spreek je het aan op /api/mailspace/:mailspace_id/domains/:name.

Een geslaagde aanroep zet ook create_attempts terug, dus een domein dat de automatische controleronde heeft opgegeven, kun je hier opnieuw proberen. Een aanroep waarvan de TXT-lookup mislukt, geeft 422 verification_failed terug en laat de teller staan waar hij stond.

Het TXT-record wordt bij elke aanroep opnieuw uitgelezen, ook nadat het domein is geverifieerd

Anders dan bij de stroom voor het hoofddomein slaat dit endpoint de lookup niet over voor een record in afwachting dat al is geverifieerd. Is het TXT-record inmiddels verwijderd, dan blijft de aanroep mislukken met 422 verification_failed — wat ook betekent dat hij een uitgeputte create_attempts-teller niet kan wissen. Zet het record terug voordat je het opnieuw probeert.

Teruggegeven params
  • domain: Object
    • name: String
    • state: String | altijd served
    • verified: Boolean | altijd true
curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domains/second.example.com/verification
Fouten
  • 404 unknown_domain | er wacht op deze mailomgeving geen domein met die naam op verificatie
  • 422 verification_failed | het TXT-record is nog niet zichtbaar. DNS-wijzigingen hebben een paar minuten nodig om zich te verspreiden; er wordt niets gewijzigd, probeer dezelfde aanroep opnieuw
  • 422 domain_create_failed | het eigendom is aangetoond maar de mailserver weigerde het domein aan te maken — meestal omdat de naam op de mailserver al onder een andere tenant is geregistreerd. Het bewijs blijft staan en het record in afwachting blijft bestaan, dus dezelfde aanroep is de retry

Een domein in afwachting opgeven

DELETE /api/mailspace/:mailspace_id/domains/:domain_name/verification

Vereist mailspace:write. Geeft 200 terug met een lege body.

Geeft een extra domein op dat nooit is geverifieerd: het record in afwachting wordt verwijderd. Er bestaat op dit moment niets op de mailserver, dus er wordt geen mail geraakt en nergens worden records verwijderd. Voeg je het domein later opnieuw toe, dan wordt er simpelweg een nieuw token aangemaakt.

Fouten
  • 404 unknown_domain | er wacht op deze mailomgeving geen domein met die naam op verificatie

Status van de verificatie van het hoofddomein

GET /api/mailspace/:mailspace_id/domain_verification

Vereist mailspace:read.

De verificatie- en inrichtingsstatus van het hoofddomein. Dit is het pad vóór de start: het werkt al voordat de mailomgeving een tenant op de mailserver heeft, en het is de enige groep endpoints op deze pagina die de controle op het inrichten overslaat.

state beweegt maar één kant op:

state Betekenis Wat je moet doen
awaiting_verification het TXT-record is nog niet gezien publiceer txt_host / txt_value en doe daarna een POST naar dit pad
provisioning eigendom aangetoond, de tenant op de mailserver wordt gebouwd poll
provision_failed eigendom aangetoond, het inrichten liep op een fout doe een POST naar dit pad om het opnieuw te proberen
provisioned klaar de rest van deze pagina is nu bruikbaar
Teruggegeven params
  • verification: Object
    • domain: String | het hoofddomein van de mailomgeving
    • state: String | een van de vier hierboven
    • verified: Boolean | het eigendom is aangetoond
    • provisioned: Boolean | de tenant op de mailserver bestaat
    • verified_at: DateTime | null totdat het eigendom is aangetoond
    • txt_type: String | altijd TXT. Alleen aanwezig zolang er een record openstaat — wordt helemaal weggelaten (niet null) zodra het domein is geverifieerd, en is helemaal niet aanwezig bij een mailomgeving die is aangeschaft op een domein dat de workspace al in eigendom had
    • txt_host: String | de recordhost, _mailspace-verify. gevolgd door het hoofddomein. Zelfde voorwaarde als bij txt_type
    • txt_value: String | het hexadecimale token van 32 tekens dat je publiceert. Zelfde voorwaarde als bij txt_type
    • last_checked_at: DateTime | wanneer het record voor het laatst is opgezocht, null tot de eerste controle
    • provision_error: String | de laatste fout bij het inrichten, null als er geen is
    • provision_attempts: Integer | aantal pogingen tot inrichten tot nu toe

Het hoofddomein verifiëren

POST /api/mailspace/:mailspace_id/domain_verification

Vereist mailspace:write. Geeft 202 terug.

Twee taken in één aanroep, gekozen op basis van de status van de mailomgeving zelf:

  • Nog niet geverifieerd — het TXT-record wordt nu opgezocht. Wordt het token gevonden, dan wordt het eigendom vastgelegd en het inrichten in de wachtrij gezet.
  • Al geverifieerd (provision_failed, of een vastgelopen provisioning) — dit is de retry: er wordt geen TXT-lookup gedaan, de oude fout wordt gewist en het inrichten wordt opnieuw aangezwengeld. Dat activeert ook de automatische controleronde opnieuw als die het had opgegeven.

202 betekent in de wachtrij, niet klaar

De tenant op de mailserver wordt asynchroon gebouwd. De body is hetzelfde verification-object als bij de GET, met state provisioning. Poll dit pad — of provisioned op Een mailomgeving bekijken — totdat er provisioned staat. Niets anders op deze pagina werkt daarvoor.

curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/mailspace/$MAILSPACE_ID/domain_verification
Fouten
  • 409 already_provisioned | de mailomgeving is al ingericht, dus haar domein hoeft niet te worden geverifieerd
  • 422 verification_failed | het TXT-record is nog niet zichtbaar; probeer dezelfde aanroep opnieuw
  • 422 provisioning_failed | het inrichten kon niet opnieuw worden aangezwengeld

Een niet-geverifieerde mailomgeving annuleren

DELETE /api/mailspace/:mailspace_id/domain_verification

Vereist mailspace:write. Geeft 200 terug met een lege body.

Geeft de aanschaf op van een mailomgeving die nooit is voorzien.

Onomkeerbaar, en er gaat geld mee

Het record van de mailomgeving wordt vernietigd (het verdwijnt uit Mailomgevingen opvragen) en haar domein komt direct vrij, dus mail opnieuw aanschaffen voor dat domein slaagt meteen.

De geldkant is voorwaardelijk: als de oorspronkelijke bestelling daadwerkelijk is belast, wordt de volledige eerste termijn teruggegeven en komt de abonnementsplek vrij. Een niet-belaste bestelling — bijvoorbeeld een met een totaal van nul — wordt simpelweg verwijderd, zonder tegoed en zonder plek om vrij te geven.

Er is geen bevestigingsparameter en geen aanvullende authenticatie via de API — een bearertoken authenticeert bij elk verzoek opnieuw. Elke annulering wordt met de gebruikte credential vastgelegd in het auditlog van het platform.

Dit is dezelfde uitkomst als de nooit-voorziene tak van Een mailomgeving verwijderen.

Fouten
  • 409 already_provisioned | de mailomgeving is ingericht; annuleer die in plaats daarvan met Een mailomgeving verwijderen
  • 422 cancel_failed | het tegoed kon niet worden verstrekt. De mailomgeving wordt bewust intact gelaten in plaats van verwijderd zonder terugbetaling — probeer het opnieuw, en neem contact op met support als het blijft misgaan

Foutcodes

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

Gedeelde controles

Elk endpoint op deze pagina doorloopt vóór zijn eigen logica dezelfde keten van controles, in deze volgorde. De eerste die faalt, beantwoordt het verzoek.

Voorwaarde Reactie Geldt voor
mailhosting is niet geconfigureerd op het platform 503 stalwart_unavailable alle
de mailomgeving is niet zichtbaar voor je credential 404, lege body alle
de credential heeft geen bewerkrecht op de eigen workspace van de mailomgeving 403 not_authorized writes
de mailomgeving is geblokkeerd (door support of wegens een onbetaalde factuur) 403 mailspace_suspended alle, ook reads
de mailomgeving staat gepland voor verwijdering 403 pending_delete writes
de mailomgeving heeft nog geen tenant op de mailserver 409 not_provisioned alle behalve de drie domain_verification-endpoints

Een paar gevolgen die het waard zijn om te weten:

  • "Writes" gaat over het HTTP-werkwoord, niet over de actie. Alles wat geen GET of HEAD is, is een write, en daarom valt De DNS voor mail opnieuw controleren onder dezelfde controle als elke andere write, terwijl de DNS-read en de twee reads van de verificatiestatus dat niet doen.
  • Het recht wordt gecontroleerd op de workspace die de mailomgeving bezit, niet op de workspace in X-Auth-Account.
  • Een geblokkeerde mailomgeving weigert ook reads, anders dan een die gepland staat voor verwijdering: die blijft de hele bewaartermijn leesbaar.
  • Een mailomgeving buiten het bereik van je credential is een 404, nooit een 403 — de API bevestigt niet dat er elders op het platform een mailomgeving bestaat.
  • stalwart_unavailable heeft een tweede oorzaak. Naast de controle op platformniveau hierboven antwoordt de opzoeking per domein achter GET, PATCH en DELETE /domains/:name met 503 wanneer de mailserver niet bereikbaar is en de naam ook geen domein in afwachting is — zie Een domein bekijken.
  • De drie domain_verification-endpoints slaan alleen de controle op het inrichten over. Alles daarboven geldt nog steeds. Op een mailomgeving die wel is voorzien, antwoorden de POST en de DELETE 409 already_provisioned, terwijl de GET blijft antwoorden met 200 en state provisioned.

Codes per endpoint

Code Status Geretourneerd door
invalid_domain 400 create
domains_unavailable 503 list — de live domeinread kon niet worden uitgevoerd. Geen lege mailomgeving
unknown_domain 404 show, update, destroy, dns, dns_check, verification (alle drie de werkwoorden)
domain_exists 409 create
domain_pending_verification 409 create, update, destroy
primary_domain 409 destroy
already_provisioned 409 verificatie hoofddomein, annulering hoofddomein
rate_limited 429 dns_check
domain_create_failed 422 create, een domein verifiëren
domain_update_failed 422 update
domain_delete_failed 422 destroy
dns_check_failed 422 dns_check
verification_failed 422 een domein verifiëren, verificatie hoofddomein
provisioning_failed 422 verificatie hoofddomein
cancel_failed 422 annulering hoofddomein