Transactionele e-mail van een site

Transactionele e-mail is de uitgaande mail die een WordPress-site namens zichzelf verstuurt — wachtwoordherstel, orderbevestigingen, meldingen van contactformulieren. Deze endpoints staan allemaal genest onder een site, op /api/sites/{site-id}/mail, en dekken de bezorgstatus, de afzenderidentiteit, het zelf opheffen van een blokkade, een DNS-hercontrole, de verzendlog en het verbruik per periode.

Voor de uitleg van dezelfde functie in het dashboard, zie Transactionele e-mail.

Zoals alle endpoints per site erven deze de bewakingen op siteniveau: een onbekend site-ID geeft 404 terug zonder body, een dunning-suspended site geeft 402 service_suspended terug, en een site die in verwijdering staat geeft 403 pending_delete terug. Zie Sites.

Statussen van de inrichting

Drie afzonderlijke situaties worden gemeld met drie afzonderlijke codes, en ze gelden niet overal op deze pagina hetzelfde. Ga na welke van toepassing is voordat je een 4xx als clientfout behandelt.

Het uitlezen van de status is bewust de uitzondering: een site waarvoor mail simpelweg nooit is ingericht, is een normale toestand en geen ontbrekend record, dus antwoordt GET /api/sites/{site-id}/mail met 200 en "mail": null in plaats van met een fout. Een 404 zou daar niet te onderscheiden zijn van een onbekend site-ID. Elk ander endpoint weigert diezelfde site met 422 mail_not_provisioned.

mail_not_active is nog specifieker: de verzendlog en het metrics-endpoint lezen beide bij de provider met de eigen credential van de site, en die bestaat pas zodra de inrichting is afgerond. De write van de afzenderidentiteit, het opheffen van de blokkade en de DNS-hercontrole werken op een account met status pending of failed en geven deze fout niet.

Status van transactionele e-mail

GET /api/sites/{site-id}/mail

Scope sites:read. De volledige bezorgstatus van de transactionele e-mail van de site: de status van het account, of de site momenteel een bezorgconfiguratie heeft, de DNS-verificatie, de effectieve afzenderidentiteit en een eventuele verzendblokkade.

Antwoordt met 200 en "mail": null wanneer de site geen account voor transactionele e-mail heeft. Hetzelfde mail-object wordt teruggegeven door het bijwerken van de afzenderidentiteit en door het endpoint dat een verzendblokkade opheft.

curl -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/sites/$SITE_ID/mail

Er worden drie DNS-records gecontroleerd, elk met zijn eigen boolean: SPF, DKIM en domeinvergrendeling. De SPF-waarde en de host van het DKIM-record zijn voor elke site op het platform hetzelfde; de waarde van het DKIM-record (die bevat een publieke sleutel die voor die site is aangemaakt) en de waarde van het domeinvergrendelingsrecord (die bevat de eigen afzenderidentificatie van de site) zijn per site verschillend. Deze API geeft geen van de records zelf terug, alleen hun verificatiestatus — die lees je af op het DNS-scherm van het dashboard.

De afzenderidentiteit bijwerken

PATCH /api/sites/{site-id}/mail/settings

Scope sites:write, plus de rol can_modify (bewerken). Stelt het deel vóór de @ en de weergavenaam in waarmee de mail van de site wordt verstuurd. De domeinhelft is hier niet in te stellen — die volgt het DKIM-domein van de site.

De params zijn plat (geen wrapper-sleutel). Al het andere dat je meestuurt wordt genegeerd: alleen deze twee sleutels worden gelezen.

Geeft 200 terug met hetzelfde mail-object als het uitlezen van de status, dus de effectieve sender_identity staat in de reactie.

curl -X PATCH \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"mail_from_local_part": "orders", "mail_from_name": "Example Store"}' \
  https://my.cloudpress.com/api/sites/$SITE_ID/mail/settings

Een verzendblokkade opheffen

DELETE /api/sites/{site-id}/mail/suspension

Scope sites:write. Dit verwijdert een verzendblokkade, niet de site, dus het is afgeschermd met de rol can_modify (bewerken) — hetzelfde recht als de write van de afzenderidentiteit, en bewust niet het strengere can_destroy. Een lid dat de site kan bewerken, kan de blokkade opheffen.

Uitgaande mail wordt automatisch gepauzeerd wanneer het verzendgedrag van de site een spamklacht oplevert, en wanneer harde bounces en geweigerde berichten niet langer op ongelukjes lijken maar op een lijstkwaliteitsprobleem. De API laat de resulterende toestand zien, niet de machinerie erachter: lees suspension.suspended, suspension.abuse, suspension.system, suspension.reason en suspension.suspended_at op het statusendpoint.

Controleer eerst suspension.can_self_unsuspend. Dit endpoint heft alleen een misbruikblokkade op die de klant zelf mag opheffen. Het geeft 403 unsuspend_not_allowed terug wanneer:

• het account helemaal niet geblokkeerd is;
• de blokkade een facturatie- of lifecycleblokkade is (suspension.system is true) — die worden opgeheven via het pad dat ze heeft opgelegd, niet hiervandaan;
• een misbruikbeoordeling achter een systeemblokkade geparkeerd staat en wacht tot die blokkade wordt opgeheven; of
• de zelfservicelimiet is opgebruikt (suspension.remaining_self_unsuspends is 0). De limiet is twee keer zelf opheffen per venster van 30 dagen.

Bij succes is de reactie 200 met het vernieuwde mail-object — dezelfde vorm als bij het uitlezen van de status — en wordt er een reconcile in de wachtrij gezet, zodat de bezorgconfiguratie van de site opnieuw wordt beoordeeld in plaats van te wachten op de volgende geplande ronde.

curl -X DELETE \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/sites/$SITE_ID/mail/suspension

De DNS voor mail opnieuw controleren

POST /api/sites/{site-id}/mail/dns_check

Scope sites:write, plus de rol can_modify (bewerken). Zet buiten de reguliere ronde een DNS-hercontrole van de mail-DNS van de site in de wachtrij, in plaats van op de geplande ronde te wachten — de aanroep die je doet direct nadat je de records hebt gepubliceerd. Hij geeft meteen 202 Accepted terug; poll GET /api/sites/{site-id}/mail voor de resulterende uitkomst.

curl -X POST \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  https://my.cloudpress.com/api/sites/$SITE_ID/mail/dns_check

Verzendlogs doorzoeken

GET /api/sites/{site-id}/mail/logs

Scope sites:read. De log met uitgaande berichten van de site, upstream doorzocht. Vereist een actief account: een account dat bestaat maar nog niet klaar is met inrichten geeft 422 mail_not_active terug.

Elk zoekveld is een eigen benoemde parameter. Ze zijn allemaal optioneel; laat ze allemaal weg voor de meest recente berichten.

Dit endpoint pagineert met een cursor, niet met paginanummers: het leest page en per_page niet, en de paginagrootte staat vast. Pagineer met start_at en volg next_start_at en prev_start_at.

Verbruikscijfers

GET /api/sites/{site-id}/mail/metrics

Scope sites:read. Dagelijks verzendvolume, aantallen openingen en kliks, en het verbruik van de site ten opzichte van het tegoed van zijn pakket in de huidige facturatieperiode. Vereist een actief account (anders 422 mail_not_active).

De facturatieperiode is verankerd op de dag waarop het account voor transactionele e-mail van de site is aangemaakt en schuift van dat ankerpunt met een maand per keer op — hij is niet gekoppeld aan je factuurdatum.

Foutcodes

Alle fouten gebruiken de standaardenvelop {"errors": [...], "code": "..."} die is beschreven in Foutreacties. De rechtenfout is de uitzondering — die bevat wel errors, maar geen code.