1. GWS
ResellerStack Developer API
  • Introduction
  • Quick start
  • API Reference
    • Customers
      • List customers
      • Create customer
      • Get customer
      • Update customer notes
      • Update customer status
      • Update billing details
    • Geo
      • List countries
      • List states
    • Pricing
      • List TLD pricing
      • Update TLD pricing
      • Set TLD featured
      • Apply bulk margin
      • Reorder TLD pricing
    • Domains
      • List domains
      • Check domain availability
      • Register a domain
      • Checkout domain cart (bulk)
      • Toggle WHOIS privacy
      • Update domain contacts
      • Get domain
      • Toggle transfer lock
      • Toggle auto-renew
      • Preview renewal price
      • Renew domain now
      • Register a domain with Google Workspace
      • List bundle offers for a name
      • Register a bundle
    • Contacts
      • List contacts
      • Create contact
      • Get contact
    • Orders
      • List orders
      • Get order
    • DNS
      • List DNS records
      • Add DNS records
      • Update DNS record
      • Delete DNS record
      • Update nameservers
      • Reset nameservers
      • List DNSSEC records
      • Add DNSSEC record
      • Delete DNSSEC record
    • Wallet
      • Get wallet balance
    • Webhooks
      • workspace.pastdue
      • workspace.expired
      • workspace.txt.failed
      • workspace.renewed
      • workspace.provisioned
      • workspace.txt.ready
      • workspace.txt.propagated
      • workspace.licenses.increased
      • workspace.deleted
      • workspace.failed
      • mailbox.ready
      • mailbox.deleted
      • workspace.dkim.ready
      • workspace.dkim.propagated
      • workspace.domain.swapped
      • Delivered when domain.order.success fires
      • Delivered when domain.order.failed fires
      • Delivered when domain.renewal.success fires
      • Delivered when domain.renewal.failed fires
    • GWS
      • Google Workspace ~ Creation Flow
      • Google Workspace ~ Sandbox Environment
      • Check Workspace Exists
        POST
      • Create Workspace
        POST
      • List Workspaces
        GET
      • Delete Workspace
        DELETE
      • Check DNS Propagation
        POST
      • Renew Workspace
        POST
      • Change Primary Domain (Beta)
        POST
    • Licenses & Mailboxes
      • Create Mailbox
      • List Mailboxes
      • Delete Mailboxes
      • Decrease Seats
  • Health check
    GET
  • Get current partner
    GET
  1. GWS

Google Workspace ~ Creation Flow

These endpoints let you buy and manage Google Workspace licenses for your customers. You can spin up new workspaces, add or remove mailboxes, handle renewals, and follow every stage of provisioning over webhooks.
🧪 Sandbox only for now. Every endpoint here works fully in the sandbox. Most accounts get a 403 calling one in production; live access is rolling out gradually.

Nameserver management#

How a workspace provisions comes down to one thing: who controls the domain's DNS.
Domain registered through Reseller Stack (via 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.
Customer brought their own domain (GoDaddy, Namecheap, wherever): they own the nameservers, so you're in the loop. We generate each record and push it to you over a webhook, you add it to their DNS, then you call POST /dns-propagation-checks so we can confirm it went live. That handshake happens twice: once for the verification TXT, once for DKIM.
SPF is informational; DMARC is entirely yours. Every Google workspace's 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.

Here's the whole lifecycle at a glance. Pick the path that matches your customer's DNS.

External DNS (customer brings their own domain)#

Provisioning flow, external DNS

Managed DNS (registered through the platform)#

Provisioning flow, managed DNS

Step 1: call POST /gws#

Send 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.

Step 2: webhook workspace.provisioned#

We've accepted the request. You'll see 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.

Step 3a: webhook workspace.txt.ready#

Your verification records are ready. Grab:
dnsRecords[domain_verification].expectedValue, the TXT token
dnsRecords[mx].expectedValue, always smtp.google.com at priority 1

Step 4a: add the TXT + MX records#

Drop both at the root (@) of the domain in the customer's DNS provider.

Step 5a: call POST /dns-propagation-checks#

Once the records are in, call this and read the response:
status: "dns_pending": not visible yet, wait a bit and try again
status: "verification_queued": we can see it, sit tight for the webhook
allPropagated: true or false
It's safe to call on a loop. It's a no-op until the record actually resolves.

Step 6a: webhook workspace.txt.propagated#

TXT is live. You'll see status: "in_progress", and dnsRecords[domain_verification].propagatedAt is now set.

Step 7a: webhook workspace.dkim.ready#

DKIM key is ready. Grab:
dnsRecords[dkim].host, the subdomain (for example google._domainkey)
dnsRecords[dkim].expectedValue, the full TXT value

Step 8a: add the DKIM TXT record#

Same deal as before: use host and expectedValue straight from the webhook.

Step 9a: call POST /dns-propagation-checks again#

Same two outcomes:
status: "dns_pending": not live yet, retry
status: "verification_queued": confirmed, wait for the webhook

Step 10a: webhook workspace.dkim.propagated#

DKIM is live. dnsRecords[dkim].propagatedAt is now set.

Step 11: webhook mailbox.ready (one per mailbox)#

You get one of these per mailbox. There's no workspace.active event, so the workspace is done when the last mailbox lands (or when GET /gws reads status: "active").
status: "active"
Each one carries 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.

If something breaks: webhook workspace.failed#

If provisioning dies for good, you get this instead of the workspace going 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.
Modified at 2026-10-22 09:07:31
Previous
Delivered when domain.renewal.failed fires
Next
Google Workspace ~ Sandbox Environment
Built with