🧪 Sandbox only for now. Every endpoint here works fully in the sandbox. Most accounts get a 403calling one in production; live access is rolling out gradually.
POST /domain/register): we own the nameservers, so we write every record needed to verify the domain and set up DKIM ourselves. You don't add anything and you never call POST /dns-propagation-checks. After your first POST /gws, the workspace provisions end to end on its own.POST /dns-propagation-checks so we can confirm it went live. That handshake happens twice: once for the verification TXT, once for DKIM.dnsRecords always includes an spf entry (v=spf1 include:_spf.google.com ~all) - add it to the domain's DNS yourself. Unlike the verification TXT and DKIM records, it's never propagation-checked: there's no webhook for it and no POST /dns-propagation-checks call. DMARC isn't part of this API at all - we don't write or check it, so add it on the customer's DNS yourself too. Mail deliverability depends on both.userId, domain, and mailboxes[] (plus optional orgName, autoRenew, collectionMethod, paymentReference). The first mailbox is your admin, and you get one seat per mailbox. You get a 202 back right away. That just means we accepted the request; the real work happens asynchronously.status: "provisioned". Nothing to do here, just record it.On platform-managed DNS? Skip ahead. If the domain is registered through the platform, steps 3a to 10a aren't yours to handle. We write the TXT, MX, and DKIM records for you, so jump straight to step 11.
dnsRecords[domain_verification].expectedValue, the TXT tokendnsRecords[mx].expectedValue, always smtp.google.com at priority 1@) of the domain in the customer's DNS provider.status: "dns_pending": not visible yet, wait a bit and try againstatus: "verification_queued": we can see it, sit tight for the webhookallPropagated: true or falsestatus: "in_progress", and dnsRecords[domain_verification].propagatedAt is now set.dnsRecords[dkim].host, the subdomain (for example google._domainkey)dnsRecords[dkim].expectedValue, the full TXT valuehost and expectedValue straight from the webhook.status: "dns_pending": not live yet, retrystatus: "verification_queued": confirmed, wait for the webhookdnsRecords[dkim].propagatedAt is now set.workspace.active event, so the workspace is done when the last mailbox lands (or when GET /gws reads status: "active").status: "active"appPassword and totpSecret as non-null strings: the event only fires once both exist. Store them when they arrive; you can also read them later with GET /mailboxes.active. It carries status: "failed" and a reason. Handle it after every step above, not just at the end, and stop polling DNS for that workspace.