ResellerHQ
Log inTry the sandbox free
GuidesAPI reference
MailboxesDomains

Update a mailbox domain

PATCH
/v1/mailbox-domains/{id}

Fixes what the customer pays per mailbox on this domain.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.

Path Parameters

id*string

Request Body

application/json
  1. body
customerPrice?|

What the customer pays for one unit of this item from now on, in minor units of their list's currency. It beats their contract and list prices. null clears it

Response Body

Success

application/json
  1. response

Success

id*string
domain*string
status*string

awaiting_domain while a domain bought with the order is still being registered; awaiting_nameservers until the domain points at nameservers; propagating once we have pointed a domain held here ourselves; active when mailboxes can be set up on it; failed when it never pointed there in time (regenerate the nameservers and try again); deleting then deleted once you delete it

Value in"awaiting_domain""awaiting_nameservers""propagating""active""failed""deleting""deleted"
source*string

resellerhq for a domain you hold here, whose nameservers we change for you; external for one registered elsewhere, whose nameservers you change at its registrar

Value in"resellerhq""external"
domainId*|

The domain held here, for resellerhq

nameserversManaged*boolean

True when we point the domain at nameservers ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar

nameservers*array<string>

Where the domain must point. Its DNS is hosted there from then on

failure*|

Why the domain is failed

customerId*string|null
unitPrice*integer

What you pay per mailbox per month on this domain, fixed when it was connected

Range0 <= value
customerPrice*|

What the customer pays per mailbox, when fixed here

periodEndsAt*|

When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered

unpaidSince*|

When the renewal now due first could not be charged. Null when nothing is owed

deletesAt*|

When an unpaid domain is deleted with its mailboxes. Add funds before then

forwarding*|

Where the domain's website redirects

dmarc*|null
actor*|

Who did it; null for anything done before we recorded that

createdAt*string
Formatdate-time
curl -X PATCH "https://example.com/v1/mailbox-domains/mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "domain": "northwind-mail.com",  "status": "awaiting_domain",  "source": "resellerhq",  "domainId": "dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "nameserversManaged": true,  "nameservers": [    "ns1.example-dns.net"  ],  "failure": {    "code": "DOMAIN_IN_USE_GOOGLE",    "message": "Domain is already in use in Google Workspace."  },  "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "unitPrice": 450,  "customerPrice": 450,  "periodEndsAt": "2026-10-07T11:04:31.000Z",  "unpaidSince": "2026-10-07T11:04:31.000Z",  "deletesAt": "2026-10-07T11:04:31.000Z",  "forwarding": {    "url": "https://northwind.com",    "captcha": true  },  "dmarc": {    "reportingEmail": "string",    "policy": "none",    "subdomainPolicy": "none",    "percentage": 0  },  "actor": {    "kind": "user",    "label": "string"  },  "createdAt": "2026-10-07T11:04:31.000Z"}

Get a mailbox domain GET

Previous Page

Delete a mailbox domain DELETE

Deletes the domain and every mailbox on it, for good: they stop renewing and are removed from Google. A mailbox cannot be deleted on its own. Nothing already paid is refunded; money held for mailboxes not yet set up goes back to your wallet. A domain held here keeps its nameservers: change them on the domain afterwards.