Site transactional email

Transactional email is the outbound mail a WordPress site sends on its own behalf — password resets, order confirmations, contact-form notifications. These endpoints are all nested under a site, at /api/sites/{site-id}/mail, and cover its delivery state, its sender identity, the self-service unblock, a DNS re-check, the send log and per-period usage.

For the dashboard walkthrough of the same feature, see Transactional email.

Like all per-site endpoints, these inherit the site-level guards: an unknown site ID returns 404 with no body, a dunning-suspended site returns 402 service_suspended, and a site pending deletion returns 403 pending_delete. See Sites.

Provisioning States

Three distinct conditions are reported with three distinct codes, and they do not apply uniformly across the page. Check which applies before treating a 4xx as a client error.

The status read is the exception on purpose: a site that simply never provisioned mail is a normal state, not a missing record, so GET /api/sites/{site-id}/mail answers 200 with "mail": null rather than an error. A 404 there would be indistinguishable from an unknown site ID. Every other endpoint rejects that same site with 422 mail_not_provisioned.

mail_not_active is narrower still: the send log and the metrics endpoint both read from the provider using the site's own credential, which only exists once provisioning has landed. The sender-identity write, the unblock and the DNS re-check work on a pending or failed account and do not raise it.

Transactional Email Status

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

Scope sites:read. The whole delivery state of the site's transactional email: account status, whether the site currently holds a delivery configuration, DNS verification, the effective sender identity, and any sending block.

Answers 200 with "mail": null when the site has no transactional-email account. The same mail object is returned by the sender-identity update and by the unblock endpoint.

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

Three DNS records are checked, and each has its own boolean: SPF, DKIM and domain lockdown. The SPF value and the DKIM record's host are the same for every site on the platform; the DKIM record's value (it carries a public key minted for that site) and the lockdown record's value (it carries the site's own sender identifier) are per site. This API does not return any of the records themselves, only their verification state — read them from the dashboard's DNS screen.

Update the Sender Identity

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

Scope sites:write, plus the can_modify (edit) role. Sets the part before the @ and the display name the site's mail is sent as. The domain half is not settable here — it follows the site's DKIM domain.

Params are flat (no wrapper key). Anything else you send is ignored: only these two keys are read.

Returns 200 with the same mail object as the status read, so the effective sender_identity is in the response.

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

Lift a Sending Block

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

Scope sites:write. This removes a suspension, not the site, so it is gated on the can_modify (edit) role — the same permission as the sender-identity write, and deliberately not the stricter can_destroy. A member who can edit the site can lift the block.

Outbound mail is paused automatically when the site's sending draws a spam complaint, and when hard bounces and drops stop looking like accidents and start looking like a list-quality problem. The API exposes the resulting state, not the machinery: read suspension.suspended, suspension.abuse, suspension.system, suspension.reason and suspension.suspended_at on the status endpoint.

Check suspension.can_self_unsuspend first. This endpoint only clears an abuse hold the customer is allowed to clear themselves. It returns 403 unsuspend_not_allowed when:

• the account is not suspended at all;
• the hold is a billing or lifecycle hold (suspension.system is true) — those lift through the path that raised them, not from here;
• an abuse verdict is parked behind a system hold, waiting to be applied when that hold lifts; or
• the self-service allowance is spent (suspension.remaining_self_unsuspends is 0). The allowance is two self-service unblocks per 30-day window.

On success the response is 200 with the refreshed mail object — the same shape as the status read — and a reconcile is queued so the site's delivery configuration is re-evaluated rather than waiting for the next scheduled sweep.

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

Re-check Mail DNS

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

Scope sites:write, plus the can_modify (edit) role. Queues an out-of-band re-check of the site's mail DNS instead of waiting for the scheduled sweep — the call to make right after publishing the records. It returns 202 Accepted immediately; poll GET /api/sites/{site-id}/mail for the resulting verdict.

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

Search Send Logs

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

Scope sites:read. The site's outbound message log, searched upstream. Requires an active account: an account that exists but has not finished provisioning returns 422 mail_not_active.

Each search field is its own named parameter. All are optional; omit them all for the most recent messages.

This endpoint is cursor-paged, not page-numbered: it does not read page or per_page, and the page size is fixed. Page with start_at, following next_start_at and prev_start_at.

Usage Metrics

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

Scope sites:read. Daily send volume, open/click counts, and the site's usage against its plan allowance for the current billing period. Requires an active account (422 mail_not_active otherwise).

The billing period is anchored on the day the site's transactional-email account was created and advances a month at a time from that anchor — it is not tied to your invoice date.

Error Codes

All errors use the standard {"errors": [...], "code": "..."} envelope described in Error Responses. The permission failure is the exception — it carries errors but no code.